Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-11-30 00:17:06 -05:00
Code Issues Projects Releases Packages Wiki Activity

Move current pages to /en/ subdirectory

Browse source
This commit is contained in:
Axon 2015-10-11 07:29:00 +00:00
parent f3ee78f223
commit a91496e9d6
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
159 changed files with 2 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

119
en/basics/GettingStarted.md Normal file
View file

@ -0,0 +1,119 @@
---
layout: doc
title: GettingStarted
permalink: /en/doc/getting-started/
redirect_from:
- /doc/GettingStarted/
- /wiki/GettingStarted/
---
Getting Started with Qubes OS
=============================
Note: This guide assumes that you've just installed Qubes for the first time. The installation guide for your Qubes release can be found on the [Downloads](/doc/QubesDownloads/) page.
Now that you've installed Qubes, let's cover some basic concepts.
AppVMs (Domains) and TemplateVMs
--------------------------------
In Qubes, you run all your programs in **domains**. Domains are also called **AppVMs** because they're implemented as lightweight virtual machines (VMs). Not every app runs in its own VM. (That would be a big waste of resources!) Instead, each VM represents a *security domain* (e.g., "work," "personal," "banking," etc.). Each domain is based, by default, on a single, common **TemplateVM** (but you can create as many as you'd like). This means that when you create a new AppVM, you don't copy the whole root filesystem needed for this AppVM to work (which would include copying all the programs). Instead, each AppVM *shares* the root filesystem with its respective TemplateVM. An AppVM has read-only access to the filesystem of the Template on which it's based, so an AppVM cannot modify a TemplateVM in any way. This is important, as it means that if an AppVM is ever compromised, the TemplateVM on which it's based (and any other AppVMs based on that TemplateVM) will still be safe. This means that creating a large number of domains is cheap: Each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
If you've installed Qubes using the default options, a few domains have already been created for you:
- work
- personal
- untrusted
Each domain, apart from having a distinct name, is also assigned a **label**, which is one of several pre-defined colors. The trusted window manager uses these colors in order to draw window decorations (color frames) around the windows of applications running in each domain. These allow you to quickly and easily identify the trust level of a given window at a glance. It's totally up to you how you'd like to interpret these colors. Personally, I find it natural to associate red with that which is untrusted and dangerous (the “red light” -- stop! danger!), green with that which is safe and trusted, and yellow and orange with things in the middle. I've also extended this scheme to include blue and black, which I interpret as indicating progressively more trusted domains than green, with black being ultimately trusted.
![snapshot12.png](/attachment/wiki/GettingStarted/snapshot12.png)
In addition to AppVMs and TemplateVMs, there's one special domain called "dom0," which is where the Desktop Manager runs. This is where you log in to the system. Dom0 is more trusted than any other domain (including TemplateVMs and black-labeled domains). If dom0 were ever compromised, it would be Game Over<sup>TM</sup>. (The entire system would effectively be compromised.) Due to its overarching importance, dom0 has no network connectivity and is used only for running the Window and Desktop Managers. Dom0 shouldn't be used for anything else. In particular, [you should never run user applications in dom0](/doc/SecurityGuidelines/#dom0-precautions). (That's what your AppVMs are for!)
Qubes VM Manager and Command Line Tools
---------------------------------------
All aspects of the Qubes system can be controlled using command line tools run under a dom0 console. To open a console window in dom0, either go to Start-\>System Tools-\>Konsole or press Alt-F2 and type `konsole`.
Various command line tools are described as part of this guide, and the whole reference can be found [here](/en/doc/dom0-tools/).
![r2b1-dom0-konsole.png](/attachment/wiki/GettingStarted/r2b1-dom0-konsole.png)
Alternatively, you can use a rather intuitive GUI tool called **Qubes VM Manager**. It supports most of the functionality that command line tools provide. The Qubes VM Manager starts and opens automatically when Qubes starts up, but you can also start it by going to Start-\>System Tools-\>Qubes Manager. Once the Qubes VM Manager is running, you can open the window at any time by clicking on the Qubes tray icon, which typically resides in the bottom-right corner of the screen.
![r2b1-qubes-manager-2.png](/attachment/wiki/GettingStarted/r2b1-qubes-manager-2.png)
Starting Apps in Domains
------------------------
Apps can be started either by using the shortcuts in the Desktop Manager's menu or by using the command line (i.e., a console running in dom0).
You can start apps directly from the start menu. Each domain has its own menu directory under the scheme **Domain: \<name\>**. After navigating into one of these directories, simply click on the application you'd like to start:
![r2b1-appsmenu-1.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-1.png) ![r2b1-appsmenu-3.png](/attachment/wiki/GettingStarted/r2b1-appsmenu-3.png)
By default, each domain's menu contains only a few shortcuts. If you'd like to add more, simply click **Add more shortcuts...**, select the desired applications, and click **OK**. You can also add shortcuts manually. (This is sometimes necessary if the desired application doesn't show up in the Qubes VM Manager window.) To do this in KDE, right-click on the **Start** button and click **Menu Editor**. Click the domain directory in which you'd like the menu to appear, click **New Item**, enter its name as **\<domain name\>: \<app name\>**, and provide the command for starting the app (see below). Then click **Save** and wait approximately 15 seconds for the changes to propagate to the KDE menu.
To start apps from the console in dom0, type:
qvm-run -a <domain> "<app name> [arguments]"
e.g.:
qvm-run -a untrusted firefox
Adding, Removing, and Listing Domains
-------------------------------------
Domains can easily be added and removed by clicking on the **Add** and **Remove** buttons in the Qubes VM Manager.
Domains can also be added, removed, and listed from command line (i.e., a console running in dom0) using the following tools:
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
How Many Domains Do I Need?
---------------------------
That's a great question, but there's no one-size-fits-all answer. It depends on the structure of your digital life, and this is at least a little different for everyone. If you plan on using your system for work, then it also depends on what kind of job you do.
It's a good idea to start out with the three domains created automatically by the installer: work, personal, and untrusted. Then, if and when you start to feel that some activity just doesn't fit into any of your existing domains, you can easily create a new domain for it. You'll also be able to easily copy any files you need to the newly created domain, as explained [here](/en/doc/copying-files/).
More paranoid people might find it worthwhile to read [this article](http://theinvisiblethings.blogspot.com/2011/03/partitioning-my-digital-life-into.html), which describes how one of the Qubes authors partitions her digital life into security domains.
Full Screen Domains
-------------------
By default, Qubes doesn't allow any application window to occupy the entire screen such that its window name (which includes the name of the domain to which it belongs) and colored window border are no longer visible. This is a security precaution designed to prevent a situation in which an application which has been allowed to enter full screen mode begins to emulate the entire Qubes system. We want it to be the case that the user is always able to identify which domain is displaying any given window. Otherwise, a compromised domain which is able to occupy the entire screen could trick the user into thinking that she is interacting with a variety of different domains (including dom0), when in fact she is interacting with only a single, compromised domain pretending to be the whole system.
However, if the user makes use of an "expose-like" desktop switcher, such as the "Desktop Grid" effect that is enabled by default under KDE (default activation command: Ctrl-F8), then we can safely allow domains to enter full screen mode, as we have assurance that we can always "preempt" them by hitting the magic key combination (e.g., Ctrl-F8), which will be consumed by the trusted window manager and not passed down to the fullscreen AppVM. This means that the AppVM has no way of effectively "faking" the fullscreen view of the system, as the user can easily identify it as "just another AppVM." Theoretically, this could be achieved even with primitive Alt-Tab like switching, which should be available on simpler Window Managers (such as Xfce4, which we also support as an alternative dom0 Desktop Environment), but this might be less obvious to the user.
To allow domains to enter full screen mode, one should edit the `/etc/qubes/guid.conf` file in dom0.
E.g. to allow all domains to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section:
global: {
# default values
allow_fullscreen = false;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
To allow only select AppVMs to enter full screen mode, create a per-VM section, and set `allow_fullscreen` flag there to `true`:
VM: {
work: {
allow_fullscreen = true;
};
};
In order for the changes to take effect, restart the AppVM(s).
* * * * *
Now that you're familiar with the basics, feel free to have a look at other [Qubes User Guides](/en/doc/).

85
en/basics/MailingLists.md Normal file
View file

@ -0,0 +1,85 @@
---
layout: doc
title: MailingLists
permalink: /en/doc/mailing-lists/
redirect_from:
- /doc/QubesLists/
- /wiki/QubesLists/
---
Qubes Mailing Lists
===================
Please send all the questions regarding Qubes to one of the following mailing lists. **Please do not send questions to individual Qubes developers.** By sending a message to the appropriate mailing list, you are not only giving others a chance to help you, but you may also be helping others by starting a public discussion about a shared problem or interest.
Mailing List Rules
------------------
- Send your message to the correct list. Read the sections below to determine which list is correct for your message.
- Do not [top-post](https://en.wikipedia.org/wiki/Posting_style).
- Include a precise and informative subject line. This will allow others to easily find your thread in the future and use it as a reference.
- Bad: "Help! Qubes problems!"
- Good: "R2B2 Installation problem: Apple keyboard not working in installer."
- Be concise. Do not write an essay. Include only essential information. Please think about how many messages come to the list every day and whether people will want to read through your lengthy message (hint: they won't!).
- Do not apologize for your poor English. This is a waste of everyone's time, including your own. If we can't understand you, we will ask you to clarify (or ignore your message if it's a total mess ;).
- While we're generally open to hearing suggestions for new features, please note that we already have a pretty well defined [roadmap](https://github.com/QubesOS/qubes-issues/milestones), and it's rather unlikely that we will change our schedule in order to accommodate your request. If there's a particular feature you'd like to see in Qubes, a much more effective way to make it happen is to... contribute code to Qubes which implements it! We happily accept such contributions, provided they meet our standards. Please note, however, that it's always a good idea to field a discussion of your idea on the qubes-devel list before putting in a lot of hard work on something that we may not be able or willing to accept.
The `qubes-users` Mailing List
------------------------------
### How to Use This List
This list is for helping users solve various daily problems with Qubes OS. Examples of topics or questions suitable for this list include:
- [HCL reports](/doc/HCL/#generating-and-submitting-new-reports).
- Installation problems.
- Hardware compatibility problems.
- Bug reports.
- How do I...?
### Read These First
Please try searching both the Qubes website and the archives of the mailing lists before sending a question. In addition, please make sure that you have read and understood the following basic documentation prior to posting to the list:
- [Installation guides, System Requirements, and HCL](/doc/QubesDownloads/) \<-- for problems related to Qubes OS installation
- [Qubes User FAQ](/en/doc/user-faq/)
- [Qubes User Guides](/en/doc/) \<-- for questions about how to use Qubes OS
### How to Subscribe and Post
You don't have to subscribe in order to post to this list. However, subscribing might nonetheless be desirable, as it ensures that your messages will not be eaten by the Google Groups spam filter and allows you to receive messages which were sent directly to the list.
- To subscribe to the list, send a blank mail to `qubes-users+subscribe@googlegroups.com`. (Note: A Gmail account is not required. Any email address should work.)
- To post a message to the list, address your email to `qubes-users@googlegroups.com`. (Note: You don't have to be subscribed in order to post.)
- To unsubscribe, send a blank email to `qubes-users+unsubscribe@googlegroups.com`.
- This list has a Google Groups web interface: [https://groups.google.com/group/qubes-users](https://groups.google.com/group/qubes-users)
- Some users prefer to interact with the mailing list through the Google Groups web interface. This has the advantage that it allows you to search and reply to messages which were sent prior to your subscription to the list. However, a Google account is required in order to post through this interface.
The `qubes-devel` mailing list
------------------------------
### How to Use This List
This list is primarily intended for people who are interested in contributing to Qubes OS or who are willing to learn more about its architecture and implementation. Examples of topics and questions suitable for this list include:
- Questions about why we made certain architecture or implementation decisions. ("Why did you implement XYZ this way and not the other way?")
- Questions about code layout and where is code for certain functionality.
- Discussions about proposed new features, patches, etc. ("I would like to implement feature XYZ.")
- Contributed code and patches.
- Security discussions which are relevant to Qubes in some way.
### How to Subscribe and Post
You must be subscribed in order to post to this list.
- To subscribe to the list, send a blank mail to `qubes-devel+subscribe@googlegroups.com`. (Note: A Gmail account is not required. Any email address should work.)
- To post a message to the list, address your email to `qubes-devel@googlegroups.com`. (Note: You must be subscribed in order to post. If your post does not appear, please allow time for moderation to occur.)
- To unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
- This list has a Google Groups web interface: [https://groups.google.com/group/qubes-devel](https://groups.google.com/group/qubes-devel)
- Some users prefer to interact with the mailing list through the Google Groups web interface. This has the advantage that it allows you to search and reply to messages which were sent prior to your subscription to the list. However, a Google account is required in order to post through this interface.

227
en/basics/UserFaq.md Normal file
View file

@ -0,0 +1,227 @@
---
layout: doc
title: UserFaq
permalink: /en/doc/user-faq/
redirect_from:
- /doc/UserFaq/
- /wiki/UserFaq/
---
Qubes Users' FAQ
================
1. [General Questions](#general-questions)
1. [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution)
2. [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions)
3. [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes)
4. [What about other approaches to security?](#what-about-other-approaches-to-security)
5. [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels)
6. [Why does Qubes use virtualization?](#why-does-qubes-use-virtualization)
7. [Does Qubes run every app in a separate VM?](#does-qubes-run-every-app-in-a-separate-vm)
8. [Why does Qubes use Xen instead of KVM or some other hypervisor?](#why-does-qubes-use-xen-instead-of-kvm-or-some-other-hypervisor)
9. [What about this other/new (micro)kernel/hypervisor?](#what-about-this-othernew-microkernelhypervisor)
10. [What's so special about Qubes' GUI virtualization?](#whats-so-special-about-qubes-gui-virtualization)
11. [Can I watch YouTube videos in AppVMs?](#can-i-watch-youtube-videos-in-appvms)
12. [Can I run applications, like games, which require 3D support?](#can-i-run-applications-like-games-which-require-3d-support)
13. [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system)
14. [Why passwordless sudo?](#why-passwordless-sudo)
15. [How should I report documentation issues?](#how-should-i-report-documentation-issues)
2. [Installation & Hardware Compatibility](#installation--hardware-compatibility)
1. [How much disk space does each AppVM require?](#how-much-disk-space-does-each-appvm-require)
2. [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes)
3. [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x)
4. [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d)
5. [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x)
6. [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware)
7. [Why does my network adapter not work?](#why-does-my-network-adapter-not-work)
3. [Common Problems](#common-problems)
1. [My AppVMs lost Internet access after a TemplateVM update. What should I do?](#my-appvms-lost-internet-access-after-a-templatevm-update-what-should-i-do)
2. [My keyboard layout settings are not behaving correctly. What should I do?](#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do)
3. [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)
4. [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)
5. [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)
6. [I assigned a PCI device to an AppVM, then unassigned it/shut down the …](#i-assigned-a-pci-device-to-an-appvm-then-unassigned-itshut-down-the-appvm-why-isnt-the-device-available-in-dom0)
General Questions
-----------------
### Is Qubes just another Linux distribution?
If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one. But Qubes is much more than just Xen packaging. It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc. It also has a very unique GUI virtualization infrastructure.
### How is Qubes different from other security solutions?
Please see [this article](http://theinvisiblethings.blogspot.com/2012/09/how-is-qubes-os-different-from.html) for a thorough discussion.
### What is the main concept behind Qubes?
To build security on the “Security by Isolation” principle.
### What about other approaches to security?
The other two popular [approaches](http://theinvisiblethings.blogspot.com/2008/09/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.” We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### What about safe languages and formally verified microkernels?
In short: these are non-realistic solutions today. We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### Why does Qubes use virtualization?
We believe that this is currently the only practically viable approach to implementing strong isolation while simultaneously providing compatibility with existing applications and drivers.
### Does Qubes run every app in a separate VM?
No! This would not make much sense. Qubes uses lightweight VMs to create security domains (e.g., "work," "personal," and "banking,"). A typical user would likely need around five domains. Very paranoid users, or those who are high-profile targets, might use a dozen or more domains.
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### What about this other/new (micro)kernel/hypervisor?
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux AppVMs). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### What's so special about Qubes' GUI virtualization?
We have designed the GUI virtualization subsystem with two primary goals: security and performance. Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks. At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
### Can I watch YouTube videos in AppVMs?
Absolutely.
### Can I run applications, like games, which require 3D support?
Those won’t fly. We do not provide OpenGL virtualization for AppVMs. This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure. However, Qubes does allow for the use of accelerated graphics (OpenGL) in Dom0’s Window Manager, so all the fancy desktop effects should still work.
For further discussion about the potential for GPU passthorugh on Xen/Qubes, please see the following threads:
- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&)
- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&)
### Is Qubes a multi-user system?
No. Qubes does not pretend to be a multi-user system. Qubes assumes that the user who controls Dom0 controls the whole system. It would be very difficult to **securely** implement multi-user support. See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
### Why passwordless sudo?
Please refer to [this page](https://www.qubes-os.org/doc/VMSudo/).
### How should I report documentation issues?
Create an issue in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues), but **please make sure your issue does not already exist**. Documentation-related issues will be assigned the `doc` label. Issues which have been created in `qubes-issues` are significantly more likely to be addressed than those sent in emails to the mailing lists.
Installation & Hardware Compatibility
-------------------------------------
(See also: [System Requirements](/en/doc/system-requirements/) and [Hardware Compatibility List](/hcl/).)
### How much disk space does each AppVM require?
Each AppVM is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner). This means that each AppVM needs only as much disk space as is necessary to store its own private data. This also means that it is possible to update the software for several AppVMs simultaneously by running a single update process in the TemplateVM upon which those AppVMs are based. (These AppVMs will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
At least 4 GB. It is possible to install Qubes on a system with 2 GB of RAM, but the system would probably not be able to run more than three AppVMs at a time.
### Can I install Qubes on a system without VT-x?
Yes. Xen doesn't use VT-x (or AMD-v) for PV guest virtualization. (It uses ring0/3 separation instead.) However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based AppVMs), which were introduced in Qubes 2. In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.)
### Can I install Qubes on a system without VT-d?
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 AppVM 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.**
### Can I use AMD-v instead of VT-x?
See [this message](http://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
### Can I install Qubes in a virtual machine (e.g., on VMWare)?
Some users have been able to do this, but it is neither recommended nor supported. Qubes should be installed bare-metal. (After all, it uses its own bare-metal hypervisor!)
### Why does my network adapter not work?
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes. There may be a binary blob, which provides drivers in the linux-firmware package.
Open a terminal and run `sudo yum install linux-firmware` in the TemplateVM upon which your NetVM is based. You have to restart the NetVM after the TemplateVM has been shut down.
Common Problems
---------------
### My AppVMs lost Internet access after a TemplateVM update. What should I do?
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based. You may have to reboot afterward for the change to take effect. (Note: This is an upstream problem. See [here](https://bugzilla.redhat.com/show_bug.cgi?id=974811). For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
### My keyboard layout settings are not behaving correctly. What should I do?
Please read [this disccusion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion).
### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do?
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
In your TemplateVMs, open a terminal and run `sudo yum upgrade`.
### How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?
Enable "debug mode" in the AppVM's settings, either by checking the box labelled "Run in debug mode" in the Qubes VM Manager AppVM settings menu or by running the [qvm-prefs command](/en/doc/dom0-tools/qvm-prefs/).)
### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.
This is probably because one of the controllers does not support reset. In Qubes R2 any such errors were ignored but in Qubes R3.0 they are not.
A device that does not support reset is not safe and generally should not be assigned to a VM.
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.
Another solution would be to set the pci_strictreset option using qvm-prefs in dom0:
`qvm-prefs usbVM -s pci_strictreset false`
This option allows the VM to ignore the error and the VM will start.
Please review the note on [this page](https://www.qubes-os.org/doc/Dom0Tools/QvmPrefs/) and be aware of the potential risk.
### I assigned a PCI device to an AppVM, then unassigned it/shut down the AppVM. Why isn't the device available in dom0?
This is an intended feature. A device which was previously assigned to a less trusted AppVM could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
1. Reboot the physical machine.
or
1. Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind

80
en/basics/intro.md Normal file
View file

@ -0,0 +1,80 @@
---
layout: doc
title: Introduction
permalink: /en/intro/
redirect_from:
- /intro/
- "/doc/SimpleIntro/"
- "/wiki/SimpleIntro/"
---
A Simple Introduction to Qubes
==============================
This is a short, non-technical introduction to Qubes intended for a popular audience. (If you just want to quickly gain a basic understanding of what Qubes is all about, you're in the right place!)
What is Qubes?
--------------
Qubes is a security-oriented operating system (OS). The OS is the software which runs all the other programs on a computer. Some examples of popular OSes are Microsoft Windows, Mac OS X, Android, and iOS. Qubes is free and open-source software (FOSS). This means that everyone is free to use, copy, and change the software in any way. It also means that the source code is openly available so others can contribute to and audit it.
Why is OS security important?
-----------------------------
Most people use an operating system like Windows or OS X on their desktop and laptop computers. These OSes are popular because they tend to be easy to use and usually come pre-installed on the computers people buy. However, they present problems when it comes to security. For example, you might open an innocent-looking email attachment or website, not realizing that you're actually allowing malware (malicious software) to run on your computer. Depending on what kind of malware it is, it might do anything from showing you unwanted advertisements to logging your keystrokes to taking over your entire computer. This could jeopardize all the information stored on or accessed by this computer, such as health records, confidential communications, or thoughts written in a private journal. Malware can also interfere with the activities you perform with your computer. For example, if you use your computer to conduct financial transactions, the malware might allow its creator to make fradulent transactions in your name.
Aren't antivirus programs and firewalls enough?
-----------------------------------------------
Unfortunately, conventional security approaches like antivirus programs and (software and/or hardware) firewalls are no longer enough to keep out sophisticated attackers. For example, nowadays it's common for malware creators to check to see if their malware is recognized by any popular antivirus programs. If it's recognized, they scramble their code until it's no longer recognizable by the antivirus programs, then send it out. The best antivirus programs will subsequently get updated once the antivirus programmers discover the new threat, but this usually occurs at least a few days after the new attacks start to appear in the wild. By then, it's typically too late for those who have already been compromised. In addition, bugs are inevitably discovered in the common software we all use (such as our web browsers), and no antivirus program or firewall can prevent all of these bugs from being exploited.
How does Qubes provide security?
--------------------------------
Qubes allows you to separate the various parts of your digital life into securely isolated virtual machines (VMs). A VM is basically a simulated computer with its own OS which runs as software on your physical computer. You can think of a VM as a *computer within a computer*. This allows you to have, for example, one VM for visiting untrusted websites and a different VM for doing online banking. This way, if your untrusted browsing VM get compromised by a malware-laden website, your online banking activities won't be at risk. Similarly, if you're concerned about risky email attachments, Qubes can make it so that every attachment gets opened in its own single-use, "disposable" VM.
In general, Qubes takes an approach called **security by isolation**, which in this context means keeping the things you do on your computer securely isolated in different VMs so that one VM getting compromised won't affect the others. This allows you to do everything on a single physical computer without having to worry about one successful cyberattack taking down your entire digital life in one fell swoop.
How does Qubes compare to using a "live CD" OS?
-----------------------------------------------
Booting your computer from a live CD (or DVD) when you need to perform sensitive activities can certainly be more secure than simply using your main OS, but this method still preserves many of the risks of conventional OSes. For example, popular live OSes (such as [Tails](https://tails.boum.org/) and other Linux distributions) are still **monolithic** in the sense that all software is still running in the same OS. This means, once again, that if your session is compromised, then all the data and activities performed within that same session are also potentially compromised.
How does Qubes compare to running VMs in a convential OS?
---------------------------------------------------------
Not all virtual machine software is equal when it comes to security. You may have used or heard of VMs in relation to software like VirtualBox or VMware Workstation. These are known as "Type 2" or "hosted" hypervisors. (The **hypervisor** is the software, firmare, or hardware that creates and runs virtual machines.) These programs are popular because they're designed primarily to be easy to use and run under popular OSes like Windows (which is called the **host** OS, since it "hosts" the VMs). However, the fact that Type 2 hypervisors run under the host OS means that they're really only as secure as the host OS itself. If the host OS is ever compromised, then any VMs it hosts are also effectively compromised.
By contrast, Qubes uses a "Type 1" or "bare metal" hypervisor called [Xen](http://www.xenproject.org). Instead of running inside an OS, Type 1 hypervisors run directly on the "bare metal" of the hardware. This means that an attacker must be capable of subverting the hypervisor itself in order to compromise the entire system, which is vastly more difficult.
Qubes makes it so that multiple VMs running under a Type 1 hypervisor can be securely used as an integrated OS. For example, it puts all of your application windows on the same desktop with special colored borders indicating the trust levels of their respective VMs. It also allows for things like secure copy/paste operations between VMs, securely copying and transferring files between VMs, and secure networking between VMs and the Internet.
How does Qubes compare to using a separate physical machine?
------------------------------------------------------------
Using a separate physical computer for sensitive activities can certainly be more secure than using one computer with a conventional OS for everything, but there are still risks to consider. Briefly, here are some of the main pros and cons of this approach relative to Qubes:
Pros:
- Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if she were to manage to do so, she could potentially gain control over the entire system.)
- Physical separation can be a natural complement to physical security. (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
Cons:
- Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
- There's generally no secure way to transfer data between physically separate computers running conventional OSes. (Qubes has a secure inter-VM file transfer system to handle this.)
- Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature.
- Malware which can bridge air gaps has existed for several years now and is becoming increasingly common.
(For more on this topic, please see the paper [Software compartmentalization vs. physical separation](http://www.invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf).)
More information
----------------
This page is just a brief sketch of what Qubes is all about, and many technical details have been omitted here for the sake of presentation.
- If you're a current or potential Qubes user, you may want to check out the [documentation](/en/doc/) and the [FAQ](/en/doc/user-faq/).
- If you're a developer, there's dedicated [documentation](/en/doc/system-doc/) and an [FAQ](/en/doc/devel-faq/) just for you.
- Ready to give Qubes a try? Head on over to the [downloads page](/downloads/).
- Once you've installed Qubes, here's a guide on [getting started](/en/doc/getting-started/).

109
en/common-tasks/BackupEmergencyRestoreV2.md Normal file
View file

@ -0,0 +1,109 @@
---
layout: doc
title: Emergency Backup Recovery - format version 2
permalink: /en/doc/backup-emergency-restore-v2/
redirect_from: /doc/BackupEmergencyRestoreV2/
---
Emergency Backup Recovery without Qubes - format version 2
==========================================================
This page describes how to perform emergency restore of backup created on Qubes R2 Beta3 or earlier (which uses backup format 2).
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 assumed to be both encrypted and compressed.
1. Untar the main backup file.
~~~
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
backup-header.hmac
qubes.xml.000
qubes.xml.000.hmac
vm1/private.img.000
vm1/private.img.000.hmac
vm1/icon.png.000
vm1/icon.png.000.hmac
vm1/firewall.xml.000
vm1/firewall.xml.000.hmac
vm1/whitelisted-appmenus.list.000
vm1/whitelisted-appmenus.list.000.hmac
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
~~~
1. Verify the integrity of the `private.img` file which houses your data.
~~~
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
~~~
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
1. Decrypt the `private.img` file.
~~~
[user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
~~~
**Note:** For multi-part files, a loop can be used:
~~~
for f in private.img.*; do
openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
${f/.img/.img.dec}
done
~~~
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
1. Decompress the decrypted `private.img` file.
~~~
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
~~~
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program.
1. Untar the decrypted and decompressed `private.img` file.
~~~
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
~~~
**Note:** For multi-part files, a script is required:
1. Create a `new-volume-script`:
~~~
#!/bin/sh
name=`expr $TAR_ARCHIVE : '\(.*\)\..*'`
suffix=`printf %03d $[ $TAR_VOLUME - 1 ]`
echo $name.$suffix >&$TAR_FD
~~~
2. `chmod +x new-volume-script`.
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`. (The `--new-volume-script` option enables multi-volume untaring.)
1. 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!
~~~
**Note:** You may wish to store a plain text 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. You may obtain a plaintext version of this file in Git repository housing all the documentation at:
https://github.com/QubesOS/qubes-doc.git

101
en/common-tasks/BackupEmergencyRestoreV3.md Normal file
View file

@ -0,0 +1,101 @@
---
layout: doc
title: Emergency Backup Recovery - format version 3
permalink: /en/doc/backup-emergency-restore-v3/
redirect_from: /doc/BackupEmergencyRestoreV3/
---
Emergency Backup Recovery without Qubes - format version 3
==========================================================
This page describes how to perform an emergency restore of a backup created on Qubes R2 or later (which uses backup format version 3).
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. Untar the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
backup-header.hmac
qubes.xml.000
qubes.xml.000.hmac
vm1/private.img.000
vm1/private.img.000.hmac
vm1/icon.png.000
vm1/icon.png.000.hmac
vm1/firewall.xml.000
vm1/firewall.xml.000.hmac
vm1/whitelisted-appmenus.list.000
vm1/whitelisted-appmenus.list.000.hmac
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
2. Verify the integrity of the `backup-header` file, which contains basic information about your backup.
[user@restore ~]$ openssl dgst -sha512 -hmac "your_passphrase" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
[user@restore ~]$ cat backup-header.hmac
(stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3), however it is not recommended to open this file until its integrity and authenticity has been verified (the current step). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
3. 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=3
hmac-algorithm=SHA512
crypto-algorithm=aes-256-cbc
encrypted=True
compressed=True
compression-filter=gzip
**Note:** If you see `version=2` here, go to [Emergency Backup Recovery - format version 2](/doc/BackupEmergencyRestoreV2/) instead.
4. Verify the integrity of the `private.img` file which houses your data.
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
5. Decrypt the `private.img` file.
[user@restore vm1]$ cat private.img.??? | openssl enc -d -pass pass:your_passphrase -aes-256-cbc -out private.img.dec
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. This information is contained in the `backup-header` file (see step 3). A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
6. Decompress the decrypted `private.img` file.
[user@restore vm1]$ zforce private.img.dec
private.img.dec -- replaced with private.img.dec.gz
[user@restore vm1]$ gunzip private.img.dec.gz
**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).
7. Untar the decrypted and decompressed `private.img` file.
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
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 4--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

96
en/common-tasks/BackupRestore.md Normal file
View file

@ -0,0 +1,96 @@
---
layout: doc
title: BackupRestore
permalink: /en/doc/backup-restore/
redirect_from:
- /doc/BackupRestore/
- /wiki/BackupRestore/
---
Qubes Backup, Restoration, and Migration
========================================
1. [Qubes Backup, Restoration, and Migration](#QubesBackupRestorationandMigration)
1. [Creating a Backup](#CreatingaBackup)
2. [Restoring from a Backup](#RestoringfromaBackup)
3. [Emergency Backup Recovery without Qubes](#EmergencyBackupRecoverywithoutQubes)
4. [Migrating Between Two Physical Machines](#MigratingBetweenTwoPhysicalMachines)
5. [Notes](#Notes)
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/en/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/en/doc/dom0-tools/qvm-backup-restore/).
Creating a Backup
-----------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the dropdown list. This brings up the **Qubes Backup VMs** window.
1. Move the AppVMs which you desire to back up to the right-hand **Selected** column. AppVMs in the left-hand **Available** column will not be backed up.
**Note:** An AppVM must be shut down in order to be backed up. Currently running AppVMs appear in red.
Once you have selected all desired AppVMs, click **Next**.
1. Select the destination for the backup:
- If you wish to send your backup to a [USB mass storage device](/en/doc/stick-mounting/), select the device in the dropdown 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 dropdown box next to **Target AppVM**.
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.
By specifying the appropriate directory as the destination in an AppVM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the AppVM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the AppVM. This can be used to send your backup directly to, e.g., a remote server using SSH.
At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box.
**Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
1. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the dropdown list. This brings up the **Qubes Restore VMs** window.
1. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/en/doc/stick-mounting/), select the device in the dropdown box next to **Device**.
- If your backup is located in a (currently running) AppVM, select the AppVM in the dropdown box next to **AppVM**.
You must also specify the directory in which the backup resides (or a command to be executed in an AppVM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of an AppVM as your destination in step 3, you would now select the same AppVM and again type `backups` into the **Backup directory** field.
**Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field.
1. There are three options you may select when restoring from a backup:
1. **ignore missing**: If any of the AppVMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM which is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the AppVMs anyway.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **skip dom0**: If this box is checked, dom0's home directory will not be restored from your backup.
1. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
**Note:** An AppVM cannot be restored from a backup if an AppVM with the same name already exists on the current system. You must first remove or change the name of any AppVM with the same name in order to restore such an AppVM.
1. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**.
Emergency Backup Recovery without Qubes
---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
For emergency restore of backup created on Qubes R2 or newer take a look [here](/doc/BackupEmergencyRestoreV3/). For backups created on earlier Qubes version, take a look [here](/doc/BackupEmergencyRestoreV2/).
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/QubesDownloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
Notes
-----
- For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
- If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

75
en/common-tasks/CopyPaste.md Normal file
View file

@ -0,0 +1,75 @@
---
layout: doc
title: CopyPaste
permalink: /en/doc/copy-paste/
redirect_from:
- /doc/CopyPaste/
- /wiki/CopyPaste/
---
Copy and Paste between domains
==============================
Qubes fully supports secure copy and paste operation between domains. In order to copy a clipboard from domain A to domain B, follow those steps:
1. Click on the application window in the domain A where you have selected text for copying. Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C).
2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains.
3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system.
4. Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard.
Note that the global clipboard will be cleared after step \#3, to prevent accidental leakage to another domain, if the user accidentally pressed Ctrl-Shift-V later.
This 4-step process might look complex, but after some little practice it really is very easy and fast. At the same time it provides the user with full control over who has access to the clipboard.
Note that only simple plain text copy/paste is supported between AppVMs. This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd).
On Copy/Paste Security
----------------------
The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard. However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer). This is a general problem and applies to any data transfer between *less trusted to more trusted* domain. It even applies to copying files between physically separate machines (air-gapped) systems. So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains.
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.
And [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06e01) from qubes-devel.
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.](/en/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.
Clipboard automatic policy enforcement
--------------------------------------
The Qubes clipboard policy is configurable in:
~~~
/etc/qubes-rpc/policy/qubes.ClipboardPaste
~~~
You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows:
~~~
$anyvm vault deny
$anyvm $anyvm ask
~~~
Shortcut Configuration
----------------------
The copy/paste shortcuts are configurable in:
~~~
/etc/qubes/guid.conf
~~~

36
en/common-tasks/CopyToDom0.md Normal file
View file

@ -0,0 +1,36 @@
---
layout: doc
title: CopyToDom0
permalink: /en/doc/copy-to-dom0/
redirect_from:
- /doc/CopyToDomZero/
- /wiki/CopyToDomZero/
---
Copying files to between VMs and Dom0
-------------------------------------
First, there should normally be few reasons for the user to want to copy files from VMs to Dom0, as Dom0 only acts as a "thin trusted terminal", and no user applications run there. However, one exception to this is if we want to copy a desktop wallpaper, that we normally have in one of the AppVMs (e.g. in the 'personal' AppVM where we got it from our camera, or downloaded from the Internet). While it's a well justified reason, one should remember, however, that copying untrusted files to Dom0 might be a fatal security problem. Imagine what would happen if the wallpaper (e.g. a JPEG file) was somehow malformed and was in fact attempting to exploit a hypothetical JPEG parser bug in Dom0 code (e.g. in the Dom0's Xorg/KDE component that parses the wallpaper and displays it).
For this reason we intentionally do not provide a convenient tool for copying files between VMs and Dom0 (while we provide a tool for copying files between VMs). However, if you're determined to copy some files to Dom0 anyway, you can use the following method (run this command from Dom0's console):
~~~
qvm-run --pass-io <src_domain> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
~~~
BTW, you can use the same method to copy files from Dom0 to VMs:
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dst_domain> 'cat > /path/to/file_name_in_appvm'
~~~
### Copying logs from dom0
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).

42
en/common-tasks/CopyingFiles.md Normal file
View file

@ -0,0 +1,42 @@
---
layout: doc
title: CopyingFiles
permalink: /en/doc/copying-files/
redirect_from:
- /doc/CopyingFiles/
- /wiki/CopyingFiles/
---
Copying files between domains
=============================
Qubes also supports secure file coping between domains. In order to copy file(s) from domain A to domain B, follow those steps:
GUI
---
1. Open file manager in the source domain (domain A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM`
1. A dialog box will appear asking for the name of the destination domain (domain B). Ensure the domain B is running (start it by pressing the Play button in the manager if needed)
1. You will get now a confirmation dialog box (this will be displayed by Dom0, so none of the domains can fake your consent). After you click ok, the file copy operation will start, and the files will be copied into the following folder in domain B:
- `/home/user/QubesIncoming/<srcdomain>`
1. You can now move them whenever you like in the domain B filesystem using the file manager there.
CLI
---
[qvm-copy-to-vm](/en/doc/vm-tools/qvm-copy-to-vm/)
On inter-domain file copy security
----------------------------------
The scheme is *secure* because it doesn't allow other domains to steal the files that are being copying, and also doesn't allow the source domain to overwrite arbitrary file on the destination domain. Also, Qubes file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. For example, the receiving domain is *not* forced to parse untrusted partitions or file systems. In this respect our files copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. a seemingly innocent JPEG that we copy from untrusted domain, might turned out to be specially craft exploit for some hypothetical bug in JPEG parsing application in the destination domain). This is a general problem and applies to any data transfer between *less trusted to more trusted* domain. It even applies to the scenario of copying files between air-gapped machines. So, you should always copy data only from *more trusted* to *less trusted* domains.
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)

82
en/common-tasks/Dispvm.md Normal file
View file

@ -0,0 +1,82 @@
---
layout: doc
title: DisposableVMs
permalink: /en/doc/dispvm/
redirect_from:
- /doc/DisposableVms/
- /wiki/DisposableVMs/
---
Disposable VMs (DispVMs)
========================
Background
----------
See [this article](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html) for a background on why would one want to use a Disposable VM and what it is.
A DisposableVM is a lightweight VM that can be created quickly and which will disappear when it is finished with. Usually a Disposable VM is created in order to host a single application, like a viewer or an editor. This means that you can safely work with files without risk of compromising any of your VMs. Changes made to a file opened in a disposable VM are passed back to the originating VM.
By default a Disposable VM will inherit the netVM and firewall settings of the ancestor VM. You can change this behaviour: in the Qubes Manager go to the advanced tab of VM Settings where you can set the default netVM to be used for DisposableVMs created from that VM.
Once a dispVM has been created it will appear in the Qubes Manager with the name "dispX", and NetVM and firewall rules can be set as for a normal VM.
Opening a file in a Disposable VM (via GUI)
-------------------------------------------
In some AppVM, right click on the file you wish to open in a Disposable VM (in the Nautilus file manager), then choose "Open in Disposable VM". Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in a whole new VM -- a disposable VM created for the purpose of viewing or editing this very file. Once you close the viewing application the whole Disposable VM will be destroyed. If you have edited the file and saved the changes the changed file will be saved back to the original VM, overwriting the original.
![r1-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-1.png) ![r1-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-2.png)
Opening a fresh web browser instance in a new Disposable VM
-----------------------------------------------------------
Sometimes it is convenient to open a fresh instance of Firefox within a new fresh Disposable VM. This can be easily done by using the Start Menu: just go to Start -\> System Tools -\> DispVM:Firefox web browser . Wait a few seconds until a web browser starts. Once you close the viewing application the whole Disposable VM will get destroyed.
![r1-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r1-open-in-dispvm-3.png)
Opening a file in a Disposable VM via command line (from AppVM)
---------------------------------------------------------------
Use the `qvm-open-in-dvm` command line (from your AppVM), e.g.:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
The qvm-open-in-dvm will not exit until you close the application in the Disposable VM.
Starting an arbitrary application in a disposable VM via command line (from Dom0)
---------------------------------------------------------------------------------
**Note:** Normally there should be no need for doing this -- this is just for Qubes hackers ;)
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
In fact the Disposable VM appmenu used for starting Firefox contains a very similar command to the above. Please note, however, that it generally makes little sense to start any other application other than a Web Browser this way...
Starting an arbitrary program in a Disposable VM from an AppVM
--------------------------------------------------------------
Sometimes it might be useful to start an arbitrary program, such as e.g. terminal in an Disposable VM from an AppVM. This could be simply done this way:
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
Note the above command is issued in an AppVM, not in Dom0. The created Disposable VM can be normally accessed via other tools, such as e.g. `qvm-copy-to-vm`, using its 'dispX' name, as shown by the Qubes Manager or `qvm-ls` tools.
Customizing Disposable VMs
---------------------------------------------------------
You can change the template used to generate the Disposable VM, and change settings used in the Disposable VM savefile. These changes will be reflected in every new Disposable VM.
Full instructions are [here](/en/doc/disp-vm-customization/)
Disposable VMs and Local Forensics
----------------------------------
At this time, DispVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).

58
en/common-tasks/FullScreenMode.md Normal file
View file

@ -0,0 +1,58 @@
---
layout: doc
title: FullScreenMode
permalink: /en/doc/full-screen-mode/
redirect_from:
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
---
Enabling Full Screen Mode for select VMs
========================================
What is full screen mode?
-------------------------
Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window. This allows the user to easily realize to which domain a specific window belongs. See the [screenshots](/doc/QubesScreenshots/) for better understanding.
Why is full screen mode potentially dangerous?
----------------------------------------------
If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on a full screen, it might not be possible for the user to further realize if the applications/VM really "released" the full screen, or does it keep emulating the whole desktop and pretends to be the trusted Window Manager, drawing shapes on the screen that look e.g. like other windows, belonging to other domains (e.g. to trick the user into entering a secret passphrase into a window that looks like belonging to some trusted domain).
Secure use of full screen mode
------------------------------
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
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:** 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))
~~~
VM: {
personal: {
allow_fullscreen = true;
};
};
~~~
The string 'personal' above is exemplary and should be replaced by the actual name of the VM for which you want to enable this functionality.
One can also enable this functionality for all the VMs globally in the same file, by modifying the 'global' section:
~~~
global: {
# default values
allow_fullscreen = true;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
~~~
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.

36
en/common-tasks/ManagingAppvmShortcuts.md Normal file
View file

@ -0,0 +1,36 @@
---
layout: doc
title: ManagingAppVmShortcuts
permalink: /en/doc/managing-appvm-shortcuts/
redirect_from:
- /doc/ManagingAppVmShortcuts/
- /wiki/ManagingAppVmShortcuts/
---
Managing shortcuts to applications in AppVMs
============================================
For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. Clicking on such shortcut runs the assigned application in its AppVM.
![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png)
To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically):
`qvm-sync-appmenus vmname`
After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown:
![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png)
The above image shows that Windows HVMs are also supported (provided that Qubes Tools are installed).
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`.
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'`
`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/en/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.

82
en/common-tasks/SoftwareUpdateDom0.md Normal file
View file

@ -0,0 +1,82 @@
---
layout: doc
title: SoftwareUpdateDom0
permalink: /en/doc/software-update-dom0/
redirect_from:
- /doc/SoftwareUpdateDom0/
- /wiki/SoftwareUpdateDom0/
---
Updating software in dom0
=========================
Why would one want to update software in dom0?
----------------------------------------------
Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the 3rd party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in Qubes 2.0.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
However, we anticipate some other situations in which updating dom0 software might be necessary or desirable:
- Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool)
How is software updated securely in dom0?
-----------------------------------------
The update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable. For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation. At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack. While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain.
How to update software in dom0
------------------------------
As of Qubes R2 Beta 3, the main update functions have been integrated into the Qubes VM Manager GUI: Simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click.
Of course, command line tools are still available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands:
1. To check and install updates for dom0 software:
~~~
$ sudo qubes-dom0-update
~~~
1. To install additional packages in dom0 (usually not recommended):
~~~
$ sudo qubes-dom0-update anti-evil-maid
~~~
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing.
### How to downgrade a specific package
1. Download an older version of the package:
~~~
sudo qubes-dom0-update package-version
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
1. Downgrade the packge:
~~~
sudo yum downgrade package-version
~~~
### Kernel Upgrade ###
Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1.
~~~
sudo qubes-dom0-update kernel-3.19*
~~~
Rebuild grub config.
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Reboot required.

146
en/common-tasks/SoftwareUpdateVm.md Normal file
View file

@ -0,0 +1,146 @@
---
layout: doc
title: SoftwareUpdateVM
permalink: /en/doc/software-update-vm/
redirect_from:
- /doc/SoftwareUpdateVM/
- /wiki/SoftwareUpdateVM/
---
Installing and updating software in VMs
=======================================
How Template VM works 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.
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.**
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.
Installing (or updating) software in the template VM
----------------------------------------------------
In order to permanently install new software, you should:
- Start the template VM and then start either console (e.g. `gnome-terminal`) or dedicated software management application, such as `gpk-application` (*Start-\>Applications-\>Template: fedora-XX-x64-\>Add/Remove software*),
- Install/update software as usual (e.g. using yum, or the dedicated GUI application). Then, shutdown the template VM,
- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their fielsystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you.
Notes on trusting your Template VM(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.
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](/en/doc/qubes-firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Use *standalone VMs* (see below) for installation of untrusted software packages.
- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
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](/en/doc/qubes-firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
- But why trusting Fedora?
Because we chose to use Fedora as a vendor for the Qubes OS foundation (e.g. for Dom0 packages and for AppVM packages). We also chose to trust several other vendors, such as Xen.org, kernel.org, and a few others whose software we use in Dom0. We had to trust *somebody* as we are unable to write all the software from scratch ourselves. But there is a big difference in trusting all Fedora packages to be non-malicious (in terms of installation scripts) vs. trusting all those packages are non-buggy and non-epxloitable. We certainly do not assume the latter.
- So, are the template VMs as trusted as Dom0?
Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over (TM). However, a compromise of a template affects only a subset of all your AppVMs (in case you use more than one template, or also some standalone VMs). Also, if your AppVMs are network disconnected, even though their filesystems might got compromised due to the corresponding template compromise, it still would be difficult for the attacker to actually leak out the data stolen in an AppVM. Not impossible (due to existence of cover channels between VMs on x86 architecture), but difficult and slow.
Standalone VMs
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.:
- VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
~~~
qvm-create <vmname> --standalone --label <label>
~~~
... or click appropriate options in the Qubes Manager's Create VM window.
Using more than one template
----------------------------
It's also possible to have more than one template VM in the system. E.g. one could clone the default template using the `qvm-clone` command in Dom0. This allows to have a customized template, e.g. with devel packages, or less trusted apps, shared by some subset of domains. It is important to note that the default template is "system managed" and therefore cannot be backed up using Qubes' built-in backup function. In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
When you create a new domain you can choose which template this VM should be based on. If you use command line, you should use the `--template` switch:
~~~
qvm-create <vmname> --template <templatename> --label <label>
~~~
Temporarily allowing networking for software installation
---------------------------------------------------------
Some 3rd party applications cannot be installed using the standard yum repositories, and need to be manually downloaded and installed. When the installation requires internet connection to access 3rd party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections to standard yum repositories. So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template. As soon as software installation is completed, firewall rules should be returned back to the default state. The user should decided by themselves whether such 3rd party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
Updates proxy
-------------
Updates proxy is a service which filter http access to allow access to only something that looks like yum or apt repository. This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation. It is done with http proxy instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date). The proxy is used only to filter the traffic, not to cache anything.
The proxy is running in selected VMs (by default all the NetVMs (1)) and intercept traffic directed to 10.137.255.254:8082. Thanks to such configuration all the VMs can use the same proxy address, and if there is a proxy on network path, it will handle the traffic (of course when firewall rules allows that). If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure yum to really use the proxy (3). Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
(1) Services tab -\> "qubes-yum-proxy" entry; check qvm-service manual for details
(2) Firewall tab -\> Allow connections to Updates Proxy; this setting works immediately (once OK is clicked)
(3) Services tab -\> "yum-proxy-setup" entry; this setting works at next VM startup
### Technical details
1. Updates proxy: It is running as "qubes-yum-proxy" service. Startup script of this service setup firewall rule to intercept proxy traffic:
~~~
iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
~~~
1. VM using the proxy service Startup script (qubes-misc-post service) configure yum using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain
~~~
proxy=http://10.137.255.254:8082/
~~~
line, or be empty. Note that this file is specifically included from main yum.conf, yum does not support real conf.d configuration style...
Note on treating AppVM's root filesystem non-persistency as a security feature
------------------------------------------------------------------------------
As explained above, any AppVM that is based on a Template VM (i.e. which is not a Standalone VM) has its root filesystem non-persistent across the VM reboots. In other words whatever changes the VM makes (or the malware running in this AppVM makes) to its root filesystem, are automatically discarded whenever one restarts the AppVM. This might seem like an excellent anti-malware mechanism to be used inside the AppVM...
However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free. This is because the non-persistency, in case of normal AppVMs, applies only to the root filesystem and not to the user filesystem (on which the `/home`, `/rw`, and `/usr/local` are stored) for obvious reasons. It is possible that malware, especially malware that could be specifically written to target a Qubes-based AppVMs, could install its hooks inside the user home directory files only. Examples of obvious places for such hooks could be: `.bashrc`, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user's home directory.
One advantage of the non-persistent rootfs though, is that the malware is still inactive before the user's filesystem gets mounted and "processed" by system/applications, which might theoretically allow for some scanning programs (or a skilled user) to reliably scan for signs of infections of the AppVM. But, of course, the problem of finding malware hooks in general is hard, so this would work likely only for some special cases (e.g. an AppVM which doesn't use Firefox, as otherwise it would be hard to scan the Firefox profile directory reliably to find malware hooks there). Also note that the user filesystem's metadata might got maliciously modified by malware in order to exploit a hypothetical bug in the AppVM kernel whenever it mounts the malformed filesystem. However, these exploits will automatically stop working (and so the infection might be cleared automatically) after the hypothetical bug got patched and the update applied (via template update), which is an exceptional feature of Qubes OS.
Also note that Disposable VMs do not have persistent user filesystem, and so they start up completely "clean" every time. Note the word "clean" means in this context: the same as their template filesystem, of course.
RPMFusion for a Fedora TemplateVM
---------------------------------
If you would like to enable the [RPM Fusion](http://rpmfusion.org/) repository...
dom0 Start Menu -> Template:Fedora 21 -> Package Sources -> Enable RPMFusion
This already covers RPMFusion yum signing keys.

99
en/common-tasks/StickMounting.md Normal file
View file

@ -0,0 +1,99 @@
---
layout: doc
title: StickMounting
permalink: /en/doc/stick-mounting/
redirect_from:
- /doc/StickMounting/
- /wiki/StickMounting/
---
How to Mount USB Sticks to AppVMs
=================================
(**Note:** In the present context, the term "USB stick" denotes any [USB mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class). In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
Qubes supports the ability to attach a USB stick (or just one or more of its partitions) to any AppVM easily, no matter which VM actually handles the USB controller. (The USB controller may be assigned on the **Devices** tab of an AppVM's settings page in Qubes VM Manager or by using the [qvm-pci command](/en/doc/assigning-devices/).)
As of Qubes R2 Beta 3, USB stick mounting has been integrated into the Qubes VM Manager GUI. Simply insert your USB stick, right-click the desired AppVM in the Qubes VM Manager list, click **Attach/detach block devices**, and select your desired action and device. This, however, only works for the whole device.
If you would like to attach individual partitions you must use the command-line tool (shown below). The reason for this is that when attaching a single partition, it used to be that Nautilus file manager would not see it and automatically mount it (see [this ticket](https://github.com/QubesOS/qubes-issues/issues/623)). This problem, however, seems to be resolved (see [this issue comment](https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051)).
If for some reason the device does not appear in nautilus and you still need to attach just a single partition to a device, you will need to mount it manually; the device will show up as /dev/xvdi (or /dev/xvdj if there is already one device attached - if two, /dev/xvdk and so on).
The command-line tool you may use to mount whole USB sticks or their partitions is `qvm-block`. This tool can be used to assign a USB stick to an AppVM as follows:
1. Insert your USB stick.
1. In a dom0 console (running as normal user), list all available block devices:
qvm-block -l
This will list all available block devices connected to any USB controller
in your system, no matter which VM hosts the controller. The name of the
VM hosting the USB controller is displayed before the colon in the device
name. The string after the colon is the name of the device used within the
VM. Like this:
dom0:sdb1 Cruzer () 4GiB
usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by calling (from the VM to which device is connected):
sudo udevadm trigger --action=change
1. Assuming our USB stick is attached to dom0 and is sdb, we attach the device to an AppVM like so:
`qvm-block -a personal dom0:sdb`
This will attach the device to the AppVM as "/dev/xvdi", if not already taken by another attached device, or "/dev/xvdj" etc.
You may also mount one partition at a time by using the same command with the partition number after sdb.
**Warning: when working with single partitions, it is possible to assign the same partition to multiple VMs.** For example, you could attach sdb1 to VM1 and then sdb to VM2. It is up to the user not to make this mistake. Xen block device framework currently does not provide an easy way around this. Point 2 of [this ticket comment](https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124119309) gives details on this.
1. The USB stick is now attached to the AppVM. If using a default AppVM, you may open Nautilus file manager in the AppVM, and your stick should be visible in the **Devices** panel on the left.
1. When you finish using your USB stick, click the eject button or right-click and select **Unmount**.
1. In a dom0 console, detach the stick:
qvm-block -d <device> <vmname>
1. You may now remove the device.
**Warning: Do not remove the device before detatching it from the VM!** Otherwise you
will not be able to attach it anywhere later. See [this
ticket](https://github.com/QubesOS/qubes-issues/issues/1082) for details.
What if I removed the device before detaching it from the VM?
------------------------------------------------------------
Currently (until [this
ticket](https://github.com/QubesOS/qubes-issues/issues/1082) got implemented),
if you remove the device before detaching it from the VM, Qubes (more precisely
- libvirtd) will think that the device is still attached to the VM and will not
allow attaching further devices under the same name. The easiest way to recover
from such situation is to reboot the VM to which device was attached. But if
this isn't an option, you can manually recover from the situation by following
this steps:
1. Physically connect the device back. You can use any device as long as it
will be detected under the same name (for example `sdb`).
2. Attach the device manually to the same VM using `xl block-attach` command.
It is important to use the same "frontend" device name (by default `xvdi`) -
you can get it from `qvm-block` listing:
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
In above example all `xl block-attach` parameters can be deduced from
`qvm-block` output. In order:
* `testvm` - name of target VM to which device was attached - listed in brackets by `qvm-block` command
* `phy:/dev/sda` - physical path at which device appears in source VM (just after source VM name in `qvm-block` output)
* `backend=sys-usb` - name of source VM, can be omitted in case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output
3. Now properly detach the device, either using Qubes Manager, or `qvm-block -d` command.

130
en/configuration/AssigningDevices.md Normal file
View file

@ -0,0 +1,130 @@
---
layout: doc
title: AssigningDevices
permalink: /en/doc/assigning-devices/
redirect_from:
- /doc/AssigningDevices/
- /wiki/AssigningDevices/
---
Assigning Devices to VMs
========================
In order to assign a whole PCI(e) device to a VM, one should use `qvm-pci` tool. E.g.
~~~
lspci
~~~
Find the BDF address of the device you want to assign, and then:
~~~
qvm-pci -a <vmname> <bdf>
~~~
E.g. assuming 00:1a.0 is a BDF of the device I want to assign to the "personal" domain:
~~~
qvm-pci -a personal 00:1a.0
~~~
Note that one can only assign full PCI or PCI Express devices. This means one cannot assign single USB devices -- only the whole USB controller with whatever USB devices connected to it. This limit is imposed by PC and VT-d architecture.
Using Qubes Manager
-------------------
TODO
\<screenshot\>
Finding the right USB controller
--------------------------------
If you want assign certain USB device to a VM (by attaching a whole USB controller), you need to figure out which PCI device is the right controller. First check to which USB bus the device is connected:
~~~
lsusb
~~~
For example I want assign a broadband modem to the netvm. In lsusb output it can be listed as something like this (in this case device isn't fully identified):
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
~~~
The device is connected to the USB bus \#3. Then check which other devices are connected to the same bus - all of them will be assigned to the same VM. Now is the time to find right USB controller:
~~~
readlink /sys/bus/usb/devices/usb3
~~~
This should output something like:
~~~
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
~~~
Now you see BDF address in the path (right before final usb3). Strip leading "0000:" and pass the rest to qvm-pci tool:
~~~
qvm-pci -a netvm 00:1a.0
~~~
Possible issues
---------------
### DMA buffer size
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb). By default it is 2MB, but some devices need a larger buffer. To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
~~~
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
~~~
This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3) for Realtek RTL8111DL Gigabit Ethernet Controller.
### PCI passthrough issues
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
~~~
[Unit]
Description=Netvm fixup
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo 0000:04:00.0 > /sys/bus/pci/drivers/pciback/permissive'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
~~~
Then enable it with `systemctl enable qubes-pre-netvm.service`
See also: [https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI](https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI), [http://wiki.xen.org/wiki/Xen\_PCI\_Passthrough](http://wiki.xen.org/wiki/Xen_PCI_Passthrough)
**NOTE:** By setting the permissive flag for the PCI device, you're potentially weakening the device isolation, especially if your system is not equipped with VT-d Interrupt Remapping unit -- see [this paper, page 7](http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) for more details.
Bringing PCI device back to dom0
--------------------------------
By default device detached from some VM (or when VM with PCI device attached get shut down) isn't attached back to dom0. This is an intended feature. A device which was previously assigned to a less trusted AppVM could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
1. Reboot the physical machine.
or
1. Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
~~~

68
en/configuration/ConfigFiles.md Normal file
View file

@ -0,0 +1,68 @@
---
layout: doc
title: ConfigFiles
permalink: /en/doc/config-files/
redirect_from:
- /doc/ConfigFiles/
- "/doc/UserDoc/ConfigFiles/"
- "/wiki/UserDoc/ConfigFiles/"
---
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).
- `/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
rm -rf /var/lib/bluetooth
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.
Note that scripts need to be executable (chmod +x) to be used.
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):
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
global: {
# default values
#allow_fullscreen = false;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
#audio_low_latency = false;
};
# most of setting can be set per-VM basis
VM: {
work: {
#allow_utf8_titles = true;
};
video-vm: {
#allow_fullscreen = true;
};
};
~~~
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.

37
en/configuration/DiskTrim.md Normal file
View file

@ -0,0 +1,37 @@
---
layout: doc
title: DiskTRIM
permalink: /en/doc/disk-trim/
redirect_from:
- /doc/DiskTRIM/
- /wiki/DiskTRIM/
---
VMs have already TRIM enabled by default, but dom0 doesn't. There are some security implications (read for example [this article](http://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but IMO not very serious.
To enable TRIM in dom0 you need:
1. Get your LUKS device UUID:
~~~
ls /dev/mapper/luks-*
~~~
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
~~~
luks-<UUID> UUID=<UUID> none allow-discards
~~~
3. Add `rd.luks.allow-discards=1` to kernel cmdline (`/etc/default/grub`, GRUB\_CMDLINE\_LINUX line)
4. Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
5. Rebuild initrd **in hostonly mode**:
~~~
dracut -H -f
~~~
6. Add "discard" option to `/etc/fstab` for root device
7. Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)
There is a [bug affecting allow-discards option](https://bugzilla.redhat.com/show_bug.cgi?id=890533), once it will be fixed, first two steps will be no longer needed.

48
en/configuration/ExternalAudio.md Normal file
View file

@ -0,0 +1,48 @@
---
layout: doc
title: ExternalAudio
permalink: /en/doc/external-audio/
redirect_from:
- /doc/ExternalAudio/
- /wiki/ExternalAudio/
---
Using External Audio Devices
============================
Why you want to use external audio devices
------------------------------------------
Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible. Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms. So applications demanding higher audio quality (even Skype) need a better environment. But Qubes flexibility fully allows that using external audio devices. These are mostly USB audio cards, but firewire devices also might be used.
Implementing external audio devices
-----------------------------------
First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it. In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
### Fedora VMs
In a terminal of the template from which you user VM depends, install pavucontrol with:
~~~
sudo yum install pavucontrol
~~~
Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with:
~~~
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
~~~
Start the audio application that is going to use the external audio device.
Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select you external audio card in pavucontrol. You need to do that only the first time you use a new external audio device, then pulse audio will remember you selection.
If you detach your external audio device, then want to insert it again, or change it with another one, you need to repeat the previous commands in terminal, adding an other line at the beginning:
~~~
pactl unload-module module-udev-detect
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
~~~

16
en/configuration/ExternalDeviceMountPoint.md Normal file
View file

@ -0,0 +1,16 @@
---
layout: doc
title: ExternalDeviceMountPoint
permalink: /en/doc/external-device-mount-point/
redirect_from:
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
---
All external storage devices connected to an AppVM using the Fedora template can be found under
~~~
/run/media/user/
~~~
...of that AppVM's filesystem.

78
en/configuration/Fetchmail.md Normal file
View file

@ -0,0 +1,78 @@
---
layout: doc
title: Fetchmail
permalink: /en/doc/fetchmail/
redirect_from:
- /doc/Fetchmail/
- /wiki/Fetchmail/
---
Fetchmail
=========
Fetchmail is standalone MRA (Mail Retrieval Agent) aka "IMAP/POP3 client". Its sole purpose is to fetch your messages and store it locally or feed to local MTA (Message Transfer Agent). It cannot "read" messages — for that, use a MUA like Thunderbird or [Mutt](/en/doc/mutt/).
Installation
------------
`yum install fetchmail`
Configuration
-------------
Assuming you have more than one account (safe assumption these days), you need to spawn multiple fetchmail instances, one for each IMAP/POP3 server (though one instance can watch over several accounts on one server). The easiest way is to create template systemd unit and start it several times. Fedora does not supply any, so we have to write one anyway.
**NOTE:** this assumes you use [Postfix](/en/doc/postfix/) as your local MTA.
In TemplateVM create `/etc/systemd/system/fetchmail@.service`:
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
Requires=postfix.service
[Service]
User=user
ExecStart=/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid
RestartSec=1
~~~
Then shutdown TemplateVM, start AppVM and create directory `/usr/local/etc/fetchmail`. In it, create one `.rc` file for each instance of fetchmail, ie. `personal1.rc` and `personal2.rc`. Sample configuration file:
~~~
set syslog
set no bouncemail
#set daemon 600
poll mailserver1.com proto imap
no dns
uidl
tracepolls
user woju pass supersecret
ssl
sslproto "TLS1"
sslcertfile "/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt"
sslcertck
mda "/usr/sbin/sendmail -i -f %F -- user"
fetchall
idle
# vim: ft=fetchmail
~~~
Then `chown -R user:user /usr/local/etc/fetchmail` and `chmod 600 /usr/local/etc/fetchmail/*.rc`. **This is important**, fetchmail will refuse to run with wrong permissions on its rc-file.
Next, add this to `/rw/config/rc.local`:
~~~
#!/bin/sh
for rc in /usr/local/etc/fetchmail/*.rc; do
instance=${rc%.*}
instance=${instance##*/}
echo systemctl --no-block start fetchmail@${instance}
done
~~~
Now reboot your AppVM and you are done.

219
en/configuration/Mutt.md Normal file
View file

@ -0,0 +1,219 @@
---
layout: doc
title: Mutt
permalink: /en/doc/mutt/
redirect_from:
- /doc/Mutt/
- /wiki/Mutt/
---
Mutt
====
Mutt is a fast, standards-compliant, efficient MUA (Mail User Agent). In some areas it works better than Thunderbird+Enigmail, and is certainly faster and more responsive.
Mutt lacks true MTA (Message Transfer Agent aka "SMTP client") and MRA (Mail
Retrieval Agent aka "IMAP/POP3 client"), thus there are some provisions
built-in. In principle it is only mail reader and composer. You may install
true MTA such as [Postfix](/en/doc/postfix/) or Exim and MRA such as
[Fetchmail](/en/doc/fetchmail/). Alternatively you can synchronize your mailbox
using [OfflineIMAP](https://github.com/OfflineIMAP/offlineimap) and just stick
to integrated SMTP support. You can even use integrated IMAP client, but it is
not very convenient.
Installation
------------
`yum install mutt`
Configuration
-------------
Mutt generally works out of the box. This configuration guide discusses only Qubes-specific setup. In this example we will have one TemplateVM and several AppVMs. It also takes advantage of [SplitGPG](/en/doc/split-gpg/), which is assumed to be already working.
**NOTE:** this requires `qubes-gpg-split >= 2.0.9`. 2.0.8 and earlier contains bug which causes this setup to hang in specific situations and does not allow to list keys.
First, paste this to `/etc/Muttrc.local` in TemplateVM:
~~~
# specify your key or override in ~/.mutt/muttrc in AppVM
set pgp_sign_as="0xDEADBEEF"
set pgp_use_gpg_agent = no
# this needs qubes-gpg-split >= 2.0.8; 2.0.7 end earlier has had a deadlock on this
set pgp_decode_command="qubes-gpg-client-wrapper --status-fd=2 --batch %f"
#set pgp_decode_command="gpg --status-fd=2 %?p?--passphrase-fd=0? --no-verbose --quiet --batch --output - %f"
set pgp_decrypt_command="$pgp_decode_command"
set pgp_verify_command="qubes-gpg-client-wrapper --status-fd=2 --no-verbose --quiet --batch --output - --verify %s %f"
set pgp_sign_command="qubes-gpg-client-wrapper --batch --armor --detach-sign --textmode %?a?-u %a? %f"
set pgp_clearsign_command="qubes-gpg-client-wrapper --batch --armor --textmode --clearsign %?a?-u %a? %f"
# I found no option to add Charset armor header when it is UTF-8, since this is
# default (as specified in RFC4880). This is needed to workaround bug in
# Enigmail, which ignores RFC and without this header Thunderbird interprets
# plaintext as us-ascii. See http://sourceforge.net/p/enigmail/bugs/38/.
### also note you must specify absolute path of pgpewrap when using debian
### e.g. /usr/lib/mutt/pgpewrap
set pgp_encrypt_only_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt -- -r %r -- %f | sed -e '2iCharset: UTF-8'"
set pgp_encrypt_sign_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt --sign %?a?-u %a? -- -r %r -- %f | sed -e '2iCharset: UTF-8'"
# we need to import both into vault and locally wrt $pgp_verify_command
set pgp_import_command="qubes-gpg-import-key %f; gpg --no-verbose --import %f"
# those are unsupported by split-gpg
set pgp_export_command="gpg --no-verbose --export --armor %r"
set pgp_verify_key_command="gpg --no-verbose --batch --fingerprint --check-sigs %r"
# read in the public key ring
set pgp_list_pubring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-keys %r"
# read in the secret key ring
set pgp_list_secring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-secret-keys %r"
# this set the number of seconds to keep in memory the passpharse used to encrypt/sign
# the more the less secure it will be
set pgp_timeout=600
# it's a regexp used against the GPG output: if it matches some line of the output
# then mutt considers the message a good signed one (ignoring the GPG exit code)
#set pgp_good_sign="^gpg: Good signature from"
set pgp_good_sign="^\\[GNUPG:\\] GOODSIG"
# mutt uses by default PGP/GPG to sign/encrypt messages
# if you want to use S-mime instead set the smime_is_default variable to yes
# automatically sign all outcoming messages
set crypt_autosign=yes
# sign only replies to signed messages
#set crypt_replysign
# automatically encrypt outcoming messages
#set crypt_autoencrypt=yes
# encrypt only replies to signed messages
set crypt_replyencrypt=yes
# encrypt and sign replies to encrypted messages
set crypt_replysignencrypted=yes
# automatically verify the sign of a message when opened
set crypt_verify_sig=yes
send-hook "~A" set pgp_autoinline=no crypt_autoencrypt=no
send-hook "~t @invisiblethingslab\.com" set crypt_autoencrypt=yes
# vim:ft=muttrc
~~~
Then shutdown your TemplateVM. Next open your AppVM, create file `/home/user/.mutt/muttrc` and adjust for your needs:
~~~
#
# accounts
#
set from = "Wojciech Zygmunt Porczyk <woju@invisiblethingslab.com>"
alternates '^woju@invisiblethingslab\.com$'
alternates '^wojciech@porczyk\.eu$'
#
# crypto
#
set pgp_sign_as = "0xDEADBEEF"
send-hook "~t @my\.family\.com" set crypt_autoencrypt=no
#
# lists
#
# google groups
lists .*@googlegroups\.com
subscribe (qubes-(users|devel)|othergroup)@googlegroups\.com
fcc-save-hook qubes-users@googlegroups\.com =list/qubes-users/
fcc-save-hook qubes-devel@googlegroups\.com =list/qubes-devel/
fcc-save-hook othergroup@googlegroups\.com =list/othergroup/
~~~
You may also create `/home/user/.signature`:
~~~
regards,
Wojciech Porczyk
~~~
Some additional useful settings
-------------------------------
In `muttrc`:
###qubes integration stuff
#open links in a dispvm using urlview
#see below for sample .urlview
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'
#override default mailcap MIME settings with qvm-open-in-dvm calls
#see sample .mailcap below
set mailcap_path=~/.mailcap
bind attach <return> view-mailcap
Debian-specific options:
#use debian mutt-patched package for mailbox sidebar hack
set sidebar_width = 30
set sidebar_visible = no
set sidebar_delim='|'
#show/hide sidebar
macro index S '<enter-command>toggle sidebar_visible<enter>'
macro pager S '<enter-command>toggle sidebar_visible<enter>'
#navigate the sidebar folders
bind index CP sidebar-prev
bind index CN sidebar-next
bind index CO sidebar-open
bind pager CP sidebar-prev
bind pager CN sidebar-next
In `.urlview`:
### TODO: this doesn't work with encrypted emails --
### urlview can't find the links
###
COMMAND qvm-open-in-dvm %s
In `.mailcap`:
### TODO: override most/all default mailcap settings to prevent
### opening in muttvm
### is there a way to do this polymorphically? i.e. not
### listing every damn mimetype by hand
###
### also would be convenient to use mailcap's TEST feature to
### show some html in mutt pager (e.g. with w3m, links or html2text),
### else open others in dispvm
# MS Word documents
application/msword; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.spreadsheet; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.text; qvm-open-in-dvm %s
# Images
image/jpg; qvm-open-in-dvm %s
image/jpeg; qvm-open-in-dvm %s
image/png; qvm-open-in-dvm %s
image/gif; qvm-open-in-dvm %s
# PDFs
application/pdf; qvm-open-in-dvm %s
# HTML
text/html; qvm-open-in-dvm %s

145
en/configuration/NetworkBridgeSupport.md Normal file
View file

@ -0,0 +1,145 @@
---
layout: doc
title: NetworkBridgeSupport
permalink: /en/doc/network-bridge-support/
redirect_from:
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
---
Network Bridge Support (EXPERIMENTAL and UNSUPPORTED)
=====================================================
The Qubes developpement team does not support bridging the network interfaces found in NetVM and don't plan to support it at all. Several reasons for that:
- Using a bridged VM is almost only necessary for developpers testing or working on OSI layer 2 or layer 3 tools (MAC or routing protocols). If not for testing, such tools are almost only used directly on routers ...).
- Most of these tools can be anyway used directly inside the NetVM, which has direct access to the network card.
- It is also possible to use a secondary network card plugged into a specific development VM.
- Such a setup could break security features of Qubes such as AppVM firewalling.
Now if you really want to work with OSI layer2 / layer 3 tools, that you don't have a secondary network card, or that you want to completely expose services of a given AppVM (at your own risk), a bridged setup may help you.
Qubes manager patch (Qubes R2B2)
--------------------------------
The following patches can be applied to the Qubes Manager GUI in order to add an option to easily bridge a VM. Use it at your own risk. If the patch breaks the Qubes Manager, you can try to restore the qubes packages:
~~~
# qubes-dom-update qubes-core-dom0 qubes-manager
# yum reinstall qubes-core-dom0
# yum reinstall qubes-manager
~~~
First, retrieve the attachment of this Wifi article in dom0. Then apply the three patches the following way after installing the patch tool :
~~~
# qubes-dom0-update patch
# patch /usr/lib64/python2.7/site-package/qubes/qubes.py < qubes.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/settings.py < settings.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/ui_settingsdlg.py < ui_settingsdlg.py-bridge.diff
~~~
Finally restart the qubes manager GUI.
A new option is now available in the AppVM Settings to enable set the NetVM in bridge mode. For a bridged AppVM, you should the select a netvm instead of a firewall vm, enabled the Bridge option and restart your AppVM.
NetVM patch (Qubes R2B2)
------------------------
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accept traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file.
- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment :
~~~
# Bridge support
# Comment the following line
#-A POSTROUTING -j MASQUERADE
# Ensure packets coming from firewallVMs or AppVMs use NAT
-A POSTROUTING -m iprange --src-range 10.137.1.0-10.137.2.255 -j MASQUERADE
# Allow redirection of bridge packets (optional as POSTROUTING default is ACCEPT)
#-A POSTROUTING -o bridge+ -j ACCEPT
# End Bridge support
~~~
- Starting from the line -A FORWARD -i vif+ -j ACCEPT:
~~~
-A FORWARD -i vif+ -o vif+ -j DROP
-A FORWARD -i vif+ -j ACCEPT
# Bridge Support
-A FORWARD -i bridge+ -j ACCEPT
# End Bridge Support
-A FORWARD -j DROP
~~~
Ensure that the IP addresses used by default in qubes are in the form 10.137.1.\* or 10.137.2.\* by running ifconfig. Of course, this setup won't work with IPv6.
Now you need to restart the NetVM and FirewallVM or only iptables in both VMs if you prefer:
~~~
# systemctl restart iptables
~~~
Create a Bridge inside the NetVM
--------------------------------
A bridge can be created inside the standard network manager (the network icon in the taskbar).
This requires:
- creating a bridge that will be your main IP (ex: setup the bridge with DHCP)
- attach eth0 to your bridge
Note: A wireless interface cannot be bridged.
The bridge edition GUI is somehow buggy as it does not remember all the parameter you setup. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
- Bridge-DHCP
~~~
[connection]
id=Bridge-DHCP
uuid=fd68198b-313a-47cb-9155-52e95cdc67f3
type=bridge
autoconnect=false
timestamp=1363938302
[ipv6]
method=auto
[ipv4]
method=auto
[bridge]
interface-name=bridge0
stp=false
~~~
Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :)
- bridge0-eth0
~~~
[802-3-ethernet]
duplex=full
mac-address=88:AE:1D:AE:30:31
[connection]
id=bridge0-eth0
uuid=38320e5b-226c-409e-9fd6-0fbf4d0460a0
type=802-3-ethernet
autoconnect=false
timestamp=1363601650
master=fd68198b-313a-47cb-9155-52e95cdc67f3
slave-type=bridge
~~~
If you do not manager to start your bridge, you can start it manually from a NetVM terminal:
~~~
$ nmcli con up id bridge0-eth0
~~~
Now that the bridge is ready, the bridged AppVM can be started...

39
en/configuration/NetworkPrinter.md Normal file
View file

@ -0,0 +1,39 @@
---
layout: doc
title: NetworkPrinter
permalink: /en/doc/network-printer/
redirect_from:
- /doc/NetworkPrinter/
- /wiki/NetworkPrinter/
---
Configuring a network printer for Qubes AppVMs
==============================================
Where to configure printers and install drivers?
------------------------------------------------
One would normally want to configure a printer in a template VM, rather than in particular AppVMs. This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown. When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
Alternatively one can add a printer in a standalone VM, but this would limit the printer usage to this particular VM.
Security considerations for network printers and drivers
--------------------------------------------------------
Some printers require 3rd party drivers, typically downloadable from the vendor's website. Such drivers are typically distributed in a form of ready to install RPM packages. However, they are often unsigned, and additionally the downloads are available via HTTP connections only. As a result, installation of such 3rd party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template. (Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the 3rd party, unverified drivers there. Such template might then be made the default template for [Disposable VM creation](/en/doc/disposable-vms/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" and print from there. This would allow to print documents from more trusted AppVMs (based on a trusted default template, that is not poisoned by 3rd party printer drivers).
However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols. This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed. This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
Additionally, the printer drivers as well as CUPS application itself, might be buggy and might got exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM). Consider not using printing from your more trusted AppVMs for this reason.
Steps to configure a network printer in a template VM
----------------------------------------------------------
1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template).
2. Add/Configure the printer in the same way as one would do on any normal Linux. Be sure to allow network access from the template VM to your printer, as normally the template VM is not allowed any network access, except to the Qubes proxy for software installation. One can use Qubes Manager to modify firewall rules for particular VMs.
3. Optional: Test the printer by printing a test page. If it works, shut down the template VM.
4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works. If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager. Also, make sure that the AppVM gets restarted after the template was shutdown.
5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there.

152
en/configuration/Postfix.md Normal file
View file

@ -0,0 +1,152 @@
---
layout: doc
title: Postfix
permalink: /en/doc/postfix/
redirect_from:
- /doc/Postfix/
- /wiki/Postfix/
---
Postfix
=======
Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](/en/doc/mutt/)+Postfix+[Fetchmail](/en/doc/fetchmail/) stack.
Installation
------------
`yum install postfix procmail make`
Procmail is not strictly neccessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not neccessary, 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
-------------
In TemplateVM open `/etc/aliases` and add line:
~~~
root: user
~~~
and run `newaliases`.
This is the only thing to do in TemplateVM, as MTA configuration is AppVM specific, so we will keep it in `/usr/local` (ie. `/rw/usrlocal`) in each AppVM.
Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` there.
### Makefile
Postfix keeps its lookup tables in bdb hash databases. They need to be compiled from source files. Postfix admins like to keep track of them by means of `/usr/local/etc/postfix/Makefile`:
~~~
all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf))
newaliases
clean:
$(RM) *.db
.PHONY: all clean
%.db: %
/usr/sbin/postmap hash:$<
~~~
### Postfix main configuration
`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it):
~~~
mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain
mynetworks_style = host
inet_protocols = ipv4
smtp_generic_maps = hash:/etc/postfix/generic
local_header_rewrite_clients =
smtp_sender_dependent_authentication = yes
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/saslpass
smtp_sasl_security_options =
smtp_tls_security_level = encrypt
smtp_sasl_mechanism_filter = plain, login
smtpd_relay_restrictions = permit_mynetworks,permit_sasl_authenticated,defer_unauth_destination
smtpd_sender_restrictions = check_sender_access hash:/etc/postfix/sender_access
home_mailbox = .maildir/
setgid_group = postdrop
mail_owner = postfix
html_directory = no
manpage_directory = /usr/share/man
queue_directory = /var/spool/postfix
readme_directory = no
mailbox_command = /usr/bin/procmail
sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
alias_maps = hash:/etc/aliases
~~~
### Lookup tables
`/usr/local/etc/postfix/generic` (put there your primary address):
~~~
@localhost your.mail@example.com
~~~
`/usr/local/etc/postfix/sender_relay`. This is important file. Put there all your SMTP servers. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
~~~
`/usr/local/etc/postfix/saslpass`. Here you put passwords to abovementioned servers. It depends on provider if you need to put whole email as username or just the part before `@`.
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
[smtp.mail.com]:smtp your.other@mail.com:supers3cret
~~~
`/usr/local/etc/postfix/sender_access`. I use it to nullroute known spam domains. If you do not need it, comment respective line in `main.cf`.
~~~
spamdomain1.com DISCARD
spamdomain2.com DISCARD
~~~
Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four abovementioned lookup tables (`generic.db`, `sender_relay.db`, `saslpass.db` and `sender_access`).
### procmail
Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`:
~~~
MAILDIR = "${HOME}/.maildir"
ORGMAIL = "${MAILDIR}/"
DEFAULT = "${MAILDIR}/"
:0
* ^List-Id:.*qubes-users\.googlegroups\.com
list/qubes-users/
:0
* ^List-Id:.*qubes-devel\.googlegroups\.com
list/qubes-devel/
~~~
Run
---
Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them):
~~~
#!/bin/sh
mount --bind /usr/local/etc/postfix /etc/postfix
systemctl --no-block start postfix
~~~
Reboot your AppVM and you are done.

127
en/configuration/ResizeDiskImage.md Normal file
View file

@ -0,0 +1,127 @@
---
layout: doc
title: ResizeDiskImage
permalink: /en/doc/resize-disk-image/
redirect_from:
- /doc/ResizeDiskImage/
- /wiki/ResizeDiskImage/
---
Resizing Disk Image
-------------------
There are several disk images which can be easily extended.
But pay attention to the overall consumed space of your sparse disk images.
### Private disk image
1048576 MB is the maximum size which can be assigned to a private storage through qubes-manager.
To grow the private disk image of a AppVM beyond this limit [qubes-grow-private](/en/doc/dom0-tools/qvm-grow-private/) can be used:
~~~
qvm-grow-private <vm-name> <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
Note2: If once the VM is started, the disk is has not been increased, you can issue in the VM's terminal:
~~~
sudo resize2fs /dev/xvdb
~~~
### Shrinking private disk image (Linux VM)
**This operation is dangerous and this is why it isn't available in standard Qubes tools. If you have enough disk space, it is safer to create new VM with smaller disk and move the data.**
The basic idea is to:
1. Shrink filesystem on the private disk image.
2. Then shrink the image.
Ext4 does not support online shrinking, so can't be done as convenient as image grown. Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. First you need to start VM without `/rw` mounted. One of the possibility is to interrupt its normal startup by adding `rd.break` kernel option:
~~~
qvm-prefs -s <vm-name> kernelopts rd.break
qvm-start --no-guid <vm-name>
~~~
And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
~~~
sudo xl console <vm-name>
# you should get dracut emergency shell here
mount --bind /dev /sysroot/dev
chroot /sysroot
mount /proc
e2fsck -f /dev/xvdb
resize2fs /dev/xvdb <new-desired-size>
umount /proc
exit
umount /sysroot/dev
poweroff
~~~
Now you can resize the image:
~~~
truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
~~~
**It is critical to use the same (or bigger for some safety margin) size in truncate call compared to resize2fs call. Otherwise you will loose your data!** Then reset kernel options back to default:
~~~
qvm-prefs -s <vm-name> kernelopts default
~~~
Done.
### Template disk image
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
1. Make sure that all the VMs based on this template are shut off (including netvms etc).
2. Sanity check: verify that none of loop device are pointing at this template root.img: `sudo losetup -a`
3. Resize root.img file using `truncate -s <desired size>` (the root.img path can be obtained from qvm-prefs).
4. If any netvm/proxyvm used by this template is based on it, set template netvm to none.
5. Start the template.
6. Execute `sudo resize2fs /dev/mapper/dmroot` in the template.
7. Verify available space in the template using `df -h`
8. Shutdown the template.
9. Restore original netvm setting (if changed), check firewall settings (setting netvm to none causes firewall reset to "block all")
### HVM disk image
In this example we will grow the disk image of an HVM to 30GB.
First, stop/shutdown the HVM.
Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
~~~
cd /var/lib/qubes/appvms/<yourHVM>/
ls -lh root.img (<--verify current size of disk image)
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:
#### Windows 7
1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management
3. Right-click on your existing volume, select "Extend Volume..."
4. Click through the wizard.
No reboot required.
#### FreeBSD
~~~
gpart recover ada0
sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~

32
en/configuration/ResizeRootDiskImage.md Normal file
View file

@ -0,0 +1,32 @@
---
layout: doc
title: ResizeRootDiskImage
permalink: /en/doc/resize-root-disk-image/
redirect_from:
- /doc/ResizeRootDiskImage/
- /wiki/ResizeRootDiskImage/
---
Resizing \`root.img\` Size
--------------------------
The safest way to increase the size of \`root.img\` is to do it for a standalone
VM (qvm-create --standalone) - which has its own root filesystem
(copy of template, instead of smart sharing).
But it should also work for a normal template (as long as changes in the
template between reboots didn't exceed 10G).
Replace the size and the path (name) of the template as wished and run your
modified command:
~~~
truncate -s 20G /var/lib/qubes/vm-templates/fedora-21/root.img
~~~
Then start your template or standalone VM and run:
~~~
sudo resize2fs /dev/mapper/dmroot
~~~
after that shutdown the template.
Then you should have extended \`root.img\` in your VM/template

141
en/configuration/Rxvt.md Normal file
View file

@ -0,0 +1,141 @@
---
layout: doc
title: Rxvt
permalink: /en/doc/rxvt/
redirect_from:
- /doc/Rxvt/
- /wiki/Rxvt/
---
Rxvt
====
`rxvt-unicode` is an advanced and efficient vt102 emulator. Here is a quick guide to configuration in both dom0 and guest VM.
Installation
------------
`yum install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension. Let me also recommend excellent Terminus font: `yum install terminus-fonts`.
Xresources
----------
In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below. `!`-lines are comments and may be left out. `#`-lines are directives to CPP (C preprocessor) and are neccessary. This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
~~~
! CGA colour palette
!*color0: #000000
!*color1: #AA0000
!*color2: #00AA00
!*color3: #AA5500
!*color4: #0000AA
!*color5: #AA00AA
!*color6: #00AAAA
!*color7: #AAAAAA
!*color8: #555555
!*color9: #FF5555
!*color10: #55FF55
!*color11: #FFFF55
!*color12: #5555FF
!*color13: #FF55FF
!*color14: #55FFFF
!*color15: #FFFFFF
! Qubes' favourite tango palette (improved with cyan)
#define TANGO_Butter1 #c4a000
#define TANGO_Butter2 #edd400
#define TANGO_Butter3 #fce94f
#define TANGO_Orange1 #ce5c00
#define TANGO_Orange2 #f57900
#define TANGO_Orange3 #fcaf3e
#define TANGO_Chocolate1 #8f5902
#define TANGO_Chocolate2 #c17d11
#define TANGO_Chocolate3 #e9b96e
#define TANGO_Chameleon1 #4e9a06
#define TANGO_Chameleon2 #73d216
#define TANGO_Chameleon3 #8ae234
#define TANGO_SkyBlue1 #204a87
#define TANGO_SkyBlue2 #3465a4
#define TANGO_SkyBlue3 #729fcf
#define TANGO_Plum1 #5c3566
#define TANGO_Plum2 #75507b
#define TANGO_Plum3 #ad7fa8
#define TANGO_ScarletRed1 #a40000
#define TANGO_ScarletRed2 #cc0000
#define TANGO_ScarletRed3 #ef2929
#define TANGO_Aluminium1 #2e3436
#define TANGO_Aluminium2 #555753
#define TANGO_Aluminium3 #888a85
#define TANGO_Aluminium4 #babdb6
#define TANGO_Aluminium5 #d3d7cf
#define TANGO_Aluminium6 #eeeeec
*color0: TANGO_Aluminium1
*color1: TANGO_ScarletRed2
*color2: TANGO_Chameleon1
*color3: TANGO_Chocolate2
*color4: TANGO_SkyBlue1
*color5: TANGO_Plum2
*color6: #06989a
*color7: TANGO_Aluminium4
*color8: TANGO_Aluminium3
*color9: TANGO_ScarletRed3
*color10: TANGO_Chameleon3
*color11: TANGO_Butter3
*color12: TANGO_SkyBlue3
*color13: TANGO_Plum3
*color14: #34e2e2
*color15: TANGO_Aluminium6
URxvt.foreground: #E0E0E0
!URxvt.background: black
!URxvt.cursorColor: rgb:ffff/0000/0000
URxvt.cursorColor: TANGO_ScarletRed3
!URxvt.font: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2
!URxvt.boldFont: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2
URxvt.font: xft:Terminus:pixelsize=14:style=Bold
URxvt.boldFont: xft:Terminus:pixelsize=14:style=Bold
URxvt.italicFont: xft:Terminus:pixelsize=14:style=Regular
URxvt.boldItalicFont: xft:Terminus:pixelsize=14:style=Regular
URxvt.scrollBar: False
URxvt.visualBell: False
! Qubes X11 passthrough does not support those, but in dom0 they are nice.
URxvt.background: rgba:0000/0000/0000/afff
URxvt.depth: 32
URxvt.urgentOnBell: True
! TODO: write qubes-rpc to handle printing
URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
! selection-to-clipboard violates
! http://standards.freedesktop.org/clipboards-spec/clipboards-latest.txt [1],
! but it does for greater good: urxvt has no other means to move PRIMARY to
! CLIPBOARD, so Qubes' clipboard won't work without it. Also the rationale given
! in [1] has little relevance to advanced terminal emulator, specifically there
! is no need for w32-style intuition and virtually no need to "paste over".
URxvt.perl-ext-common: default,selection-to-clipboard
URxvt.insecure: False
! some termcap-aware software sometimes throw '$TERM too long'
!URxvt.termName: rxvt-256color
~~~
Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
~~~
#!/bin/sh
[ -r /etc/X11/Xresources.urxvt ] && xrdb -merge /etc/X11/Xresources.urxvt
~~~
Shortcuts
---------
For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*. Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.

43
en/configuration/SecondaryStorage.md Normal file
View file

@ -0,0 +1,43 @@
---
layout: doc
title: SecondaryStorage
permalink: /en/doc/secondary-storage/
redirect_from:
- /doc/SecondaryStorage/
- /wiki/SecondaryStorage/
---
Storing AppVMs on Secondary Drives
==================================
Suppose you have a fast but small primary SSD and a large but slow secondary
HDD. You want to store a subset of your AppVMs on the HDD. In dom0:
1. `# mv /var/lib/qubes/appvms/my-new-appvm
/path/to/secondary/drive/my-new-appvm`
2. `# ln -s /path/to/secondary/drive/my-new-appvm /var/lib/qubes/appvms/`
Now, `my-new-appvm` will behave as if it were still stored on the primary SSD
(except that it will probably be slower, since it's actually stored on the
secondary HDD).
Known Issues
------------
* The above procedure does **not** interfere with [Qubes Backup][]. However,
attempting to symlink a `private.img` file (rather than the whole AppVM
directory) is known to prevent the `private.img` file from being backed up.
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
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
detached when you shut down the AppVM.) [[2]]
[Qubes Backup]: https://www.qubes-os.org/doc/BackupRestore/
[TemplateVM]: https://www.qubes-os.org/doc/Templates/
[1]: https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion
[2]: https://groups.google.com/d/topic/qubes-users/nDrOM7dzLNE/discussion

280
en/configuration/Torvm.md Normal file
View file

@ -0,0 +1,280 @@
---
layout: doc
title: TorVM
permalink: /en/doc/torvm/
redirect_from:
- /doc/TorVM/
- "/doc/UserDoc/TorVM/"
- "/wiki/UserDoc/TorVM/"
---
Known issues:
-------------
- [Service doesn't start without (even empty) user torrc](https://groups.google.com/d/msg/qubes-users/fyBVmxIpbSs/R5mxUcIEZAQJ)
Qubes TorVM (qubes-tor)
==========================
Qubes TorVM is a ProxyVM service that provides torified networking to all its
clients.
By default, any AppVM using the TorVM as its NetVM will be fully torified, so
even applications that are not Tor aware will be unable to access the outside
network directly.
Moreover, AppVMs running behind a TorVM are not able to access globally
identifying information (IP address and MAC address).
Due to the nature of the Tor network, only IPv4 TCP and DNS traffic is allowed.
All non-DNS UDP and IPv6 traffic is silently dropped.
See [this article](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) for a description of the concept, architecture, and the original implementation.
If you are interested TorVM, you may find the [Whonix](https://www.qubes-os.org/doc/Templates/Whonix/) templates in Qubes a more usable and robust solution for torifying traffic.
## Warning + Disclaimer
1. Qubes TorVM is produced independently from the Tor(R) anonymity software and
carries no guarantee from The Tor Project about quality, suitability or
anything else.
2. Qubes TorVM is not a magic anonymizing solution. Protecting your identity
requires a change in behavior. Read the "Protecting Anonymity" section
below.
3. Traffic originating from the TorVM itself **IS NOT** routed through Tor.
This includes system updates to the TorVM. Only traffic from VMs using TorVM
as their NetVM is torified.
Installation
============
0. *(Optional)* If you want to use a separate vm template for your TorVM
qvm-clone fedora-21 fedora-21-tor
1. In dom0, create a proxy vm and disable unnecessary services and enable qubes-tor
qvm-create -p torvm
qvm-service torvm -d qubes-netwatcher
qvm-service torvm -d qubes-firewall
qvm-service torvm -e qubes-tor
# if you created a new template in the previous step
qvm-prefs torvm -s template fedora-21-tor
2. From your TemplateVM, install the torproject Fedora repo
sudo yum install qubes-tor-repo
3. Then, in the template, install the TorVM init scripts
sudo yum install qubes-tor
5. Configure an AppVM to use TorVM as its NetVM (for example a vm named anon-web)
qvm-prefs -s anon-web sys-net torvm
... repeat for any other AppVMs you want torified...
6. Shutdown the TemplateVM.
7. Set the prefs of your TorVM to use the default sys-net or sys-firewall as its NetVM
qvm-prefs -s torvm netvm sys-net
8. Start the TorVM and any AppVM you have configured to be route through the TorVM
9. From the AppVMs, verify torified connectivity
curl https://check.torproject.org
### Troubleshooting ###
1. Check if the qubes-tor service is running (on the torvm)
[user@torvm] $ sudo service qubes-tor status
2. Tor logs to syslog, so to view messages use
[user@torvm] $ sudo grep Tor /var/log/messages
3. Restart the qubes-tor service (and repeat 1-2)
[user@torvm] $ sudo service qubes-tor restart
4. You may need to manually create the private data directory and set its permissions:
[user@torvm] $ sudo mkdir /rw/usrlocal/lib/qubes-tor
[user@torvm] $ sudo chown user:user /rw/usrlocal/lib/qubes-tor
Usage
=====
Applications should "just work" behind a TorVM, however there are some steps
you can take to protect anonymity and increase performance.
## Protecting Anonymity
The TorVM only purports to prevent the leaking of two identifiers:
1. WAN IP Address
2. NIC MAC Address
This is accomplished through transparent TCP and transparent DNS proxying by
the TorVM.
The TorVM cannot anonymize information stored or transmitted from your AppVMs
behind the TorVM.
*Non-comprehensive* list of identifiers TorVM does not protect:
* Time zone
* User names and real name
* Name+version of any client (e.g. IRC leaks name+version through CTCP)
* Metadata in files (e.g., exif data in images, author name in PDFs)
* License keys of non-free software
### Further Reading
* [Information on protocol leaks](https://trac.torproject.org/projects/tor/wiki/doc/TorifyHOWTO#Protocolleaks)
* [Official Tor Usage Warning](https://www.torproject.org/download/download-easy.html.en#warning)
* [Tor Browser Design](https://www.torproject.org/projects/torbrowser/design/)
## How to use Tor Browser behind TorVM
1. In a clean VM, [download Tor Browser from the Tor Project][tor-browser].
2. [Verify the PGP signature][tor-verify-sig].
3. Copy/move the Tor Browser archive into your AnonVM (i.e., the AppVM which has your TorVM as its netvm).
4. Unpack the Tor Browser archive into your home directory.
5. In dom0, right click the KDE Application Launcher Menu (AKA "Start Menu") and left click "Edit Applications..."
6. In the KDE Menu Editor, find your AnonVM's group and create a new item (or make a copy of an existing item).
7. Edit the following fields on the "General" tab:
* Name: `my-new-anonvm: Tor Browser`
* Command: `qvm-run -q --tray -a my-new-anonvm 'TOR_SKIP_LAUNCH=1 TOR_SKIP_CONTROLPORTTEST=1 TOR_SOCKS_PORT=9050 TOR_SOCKS_HOST=1.2.3.4 ./tor-browser_en-US/Browser/start-tor-browser'`
* Replace `my-new-anonvm` with the name of your AnonVM.
* Replace `1.2.3.4` with your TorVM's internal Qubes IP address, which can be viewed in Qubes VM Manager by clicking "View" --> "IP" or by running `qvm-ls -n` in dom0.
* Replace `en-US` with your locale ID, if different.
8. Click "Save" in the KDE Menu Editor.
Tor Browser should now work correctly in your AnonVM when launched via the shortcut you just created.
**Note:** If you want to use Tor Browser in a [DispVM][dispvm], the steps are the same as above, except you should copy the Tor Browser directory into your DVM template, [regenerate the DVM template][dispvm-customization], then use the following command in your KDE menu entry:
`sh -c 'echo TOR_SKIP_LAUNCH=1 TOR_SKIP_CONTROLPORTTEST=1 TOR_SOCKS_PORT=9050 TOR_SOCKS_HOST=1.2.3.4 ./tor-browser_en-US/Browser/start-tor-browser | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red'`
(Replace `1.2.3.4` and `en-US` as indicated above.)
## Performance
In order to mitigate identity correlation TorVM makes use of Tor's new [stream
isolation feature][stream-isolation]. Read "Threat Model" below for more
information.
However, this isn't desirable in all situations, particularly web browsing.
These days loading a single web page requires fetching resources (images,
javascript, css) from a dozen or more remote sources. Moreover, the use of
IsolateDestAddr in a modern web browser may create very uncommon HTTP behavior
patterns, that could ease fingerprinting.
Additionally, you might have some apps that you want to ensure always share a
Tor circuit or always get their own.
For these reasons TorVM ships with two open SOCKS5 ports that provide Tor
access with different stream isolation settings:
* Port 9050 - Isolates by SOCKS Auth and client address only
Each AppVM gets its own circuit, and each app using a unique SOCKS
user/pass gets its own circuit
* Port 9049 - Isolates client + estination port, address, and by SOCKS Auth
Same as default settings listed above, but additionally traffic
is isolated based on destination port and destination address.
## Custom Tor Configuration
Default tor settings are found in the following file and are the same across
all TorVMs.
/usr/lib/qubes-tor/torrc
You can override these settings in your TorVM, or provide your own custom
settings by appending them to:
/rw/usrlocal/etc/qubes-tor/torrc
For information on tor configuration settings `man tor`
Threat Model
============
TorVM assumes the same Adversary Model as [TorBrowser][tor-threats], but does
not, by itself, have the same security and privacy requirements.
## Proxy Obedience
The primary security requirement of TorVM is *Proxy Obedience*.
Client AppVMs MUST NOT bypass the Tor network and access the local physical
network, internal Qubes network, or the external physical network.
Proxy Obedience is assured through the following:
1. All TCP traffic from client VMs is routed through Tor
2. All DNS traffic from client VMs is routed through Tor
3. All non-DNS UDP traffic from client VMs is dropped
4. Reliance on the [Qubes OS network model][qubes-net] to enforce isolation
## Mitigate Identity Correlation
TorVM SHOULD prevent identity correlation among network services.
Without stream isolation, all traffic from different activities or "identities"
in different applications (e.g., web browser, IRC, email) end up being routed
through the same tor circuit. An adversary could correlate this activity to a
single pseudonym.
TorVM uses the default stream isolation settings for transparently torified
traffic. While more paranoid options are available, they are not enabled by
default because they decrease performance and in most cases don't help
anonymity (see [this tor-talk thread][stream-isolation-explained])
By default TorVM does not use the most paranoid stream isolation settings for
transparently torified traffic due to performance concerns. By default TorVM
ensures that each AppVM will use a separate tor circuit (`IsolateClientAddr`).
For more paranoid use cases the SOCKS proxy port 9049 is provided that has all
stream isolation options enabled. User applications will require manual
configuration to use this socks port.
Future Work
===========
* Integrate Vidalia
* Create Tor Browser packages w/out bundled tor
* Use local DNS cache to speedup queries (pdnsd)
* Support arbitrary [DNS queries][dns]
* Fix Tor's openssl complaint
* Support custom firewall rules (to support running a relay)
Acknowledgements
================
Qubes TorVM is inspired by much of the previous work done in this area of
transparent torified solutions. Notably the following:
* [adrelanos](mailto:adrelanos@riseup.net) for his work on [aos/Whonix](https://www.whonix.org)
* The [Tor Project wiki](https://trac.torproject.org/projects/tor/wiki/doc/TorifyHOWTO)
* And the many people who contributed to discussions on [tor-talk](https://lists.torproject.org/pipermail/tor-talk/)
[stream-isolation]: https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/171-separate-streams.txt
[stream-isolation-explained]: https://lists.torproject.org/pipermail/tor-talk/2012-May/024403.html
[tor-threats]: https://www.torproject.org/projects/torbrowser/design/#adversary
[qubes-net]: https://www.qubes-os.org/doc/QubesNet/
[dns]: https://tails.boum.org/todo/support_arbitrary_dns_queries/
[tor-browser]: https://www.torproject.org/download/download-easy.html
[tor-verify-sig]: https://www.torproject.org/docs/verifying-signatures.html
[dispvm]: https://www.qubes-os.org/doc/DisposableVms/
[dispvm-customization]: https://www.qubes-os.org/doc/UserDoc/DispVMCustomization/

54
en/configuration/Vpn.md Normal file
View file

@ -0,0 +1,54 @@
---
layout: doc
title: VPN
permalink: /en/doc/vpn/
redirect_from:
- /doc/VPN/
- /wiki/VPN/
---
How To make a VPN Gateway in Qubes
----------------------------------
The simplest case if you set up a VPN connection using the Network Manager inside one of your VMs. Setting up such a connection is really not Qubes specific and it is documented in Your operating system documentation. If you using the Qubes default Guest OS (Fedora): [Establishing a VPN Connection](http://docs.fedoraproject.org/en-US/Fedora/18/html/System_Administrators_Guide/sec-Establishing_a_VPN_Connection.html)
The Qubes specific part is to choose the right VM for the VPN client:
### NetVM
The simplest case is to set up a VPN connection using the Network Manager inside your NetVM. Because the NetworkManager already started you are ready to set up your VPN connection. However this has some disadvantages:
- You have to place (and probably save) Your VPN credentials inside the NetVM which is directly connected to the outside world
- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default)
### AppVM
While the Network Manager is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well, however it is only suggested if you have to use a special VPN client.
### ProxyVM
**WARNING:** *Currently the NetworkManager is not working in ProxyVMs as expected. Actually it will mess up the routing table and because of that your packets may not be routed to the VPN tunnel. - This surely occurs if your VPN wants to be the default gateway.*
One of the best thing in Qubes that you can use a special type of VMs called ProxyVM (or FirewallVM). The special thing is that your AppVMs see this as a NetVM, and the NetVMs see it as an AppVM. Because of that You can place a ProxyVM between your AppVMs and Your NetVM. This is how the default firewall VM is working.
Using a ProxyVM to set up a VPN client gives you the ability to:
- 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.
**To setup a ProxyVM as a VPN gateway you should:**
1. check (`rpm -q qubes-core-vm`) if you have the package **qubes-core-vm** version **2.1.36** (or later)
2. create a new VM and check the ProxyVM radio button
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
1. add the network-manager service to this new VM
![Settings-services.png](/attachment/wiki/VPN/Settings-services.png)
1. set up Your VPN as described in the Network Manager documentation linked above.
1. connect your AppVMs to use the new VM as a NetVM.
[![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)

196
en/configuration/Zfs.md Normal file
View file

@ -0,0 +1,196 @@
---
layout: doc
title: ZFS
permalink: /en/doc/zfs/
redirect_from:
- /doc/ZFS/
- /wiki/ZFS/
---
ZFS in Qubes
============
**Use at your own risk**!
Beware: Dragons might eat your precious data!
Install ZFS in Dom0
===================
Install DKMS style packages for Fedora <sup>(defunct\\ in\\ 0.6.2\\ due\\ to\\ spl/issues/284)</sup>
----------------------------------------------------------------------------------------------------
Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html):
~~~
disp1# wget http://archive.zfsonlinux.org/fedora/zfs-release-1-1$(rpm -E %dist).noarch.rpm
dom0# qvm-run --pass-io disp1 'cat /home/user/zfs-release-1-1.fc18.noarch.rpm' > /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo yum localinstall /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo sed -i 's/$releasever/18/g' /etc/yum.repo.d/zfs.repo
dom0# sudo qubes-dom0-update @development-tools
dom0# sudo qubes-dom0-update zfs
~~~
Install DKMS style packages from git-repository
-----------------------------------------------
Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.org/generic-rpm.html](http://zfsonlinux.org/generic-rpm.html).
### Prerequisites steps in AppVM <sup>(i.e.\\ disp1)</sup>
Checkout repositories for SPL and ZFS:
~~~
mkdir ~/repositories && cd ~/repositories
git clone https://github.com/zfsonlinux/spl.git
git clone https://github.com/zfsonlinux/zfs.git
~~~
Revert changes in SPL repository due to this bug: [https://github.com/zfsonlinux/spl/issues/284](https://github.com/zfsonlinux/spl/issues/284)
~~~
cd ~/repositories/spl
git config --global user.email "user@example.com"
git config --global user.name "user"
git revert e3c4d44886a8564e84aa697477b0e37211d634cd
~~~
### Installation steps in Dom0
Copy repositories over to Dom0:
~~~
mkdir ~/repositories
qvm-run --pass-io disp1 'tar -cf - -C ~/repositories/ {spl,zfs}' | tar -xpf - -C ~/repositories/
~~~
Installing build requirements for SPL and ZFS DKMS modules:
~~~
sudo qubes-dom0-update dkms kernel-devel zlib-devel libuuid-devel libblkid-devel lsscsi bc autoconf automake binutils bison flex gcc gcc-c++ gdb gettext libtool make pkgconfig redhat-rpm-config rpm-build strace
~~~
Configure and build SPL DKMS packages:
~~~
cd ~/repositories/spl
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
~~~
Configure and build ZFS DKMS packages:
~~~
cd ~/repositories/zfs
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
~~~
Install SPL and ZFS packages (i.e. version 0.6.2):
~~~
sudo yum localinstall \
~/repositories/spl/spl-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/spl/spl-dkms-0.6.2-1.qbs2.noarch.rpm \
~/repositories/zfs/zfs-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/zfs/zfs-dkms-0.6.2-1.qbs2.noarch.rpm \
~/repositories/zfs/zfs-dracut-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/zfs/zfs-test-0.6.2-1.qbs2.x86_64.rpm
~~~
Configure ZFS
=============
Automatically load modules
--------------------------
/etc/sysconfig/modules/zfs.modules
~~~
#!/bin/sh
for module in spl zfs; do
modprobe ${module} >/dev/null 2>&1
done
~~~
Make this file executable.
Tuning
------
Tame the memory-eating dragon (i.e. 512 Mb zfs\_arc\_max):
/etc/modprobe.d/zfs.conf
~~~
options zfs zfs_arc_max=536870912
~~~
Setup a zpool with ZFS datasets
-------------------------------
You can create a ZFS dataset for each AppVM, ServiceVM, HVM or TemplateVM or just use a pool as your backup location.
Move your existing directory to a temporary location, or the ZFS mount will overlay your directory.
Beware: VMs on a ZFS dataset aren't working, if your ZFS installation deserts you.
So keep netvm, firewallvm and your templates on your root file-system (preferably on a SSD).
~~~
zpool create -m none -o ashift=12 -O atime=off -O compression=lz4 qubes mirror /dev/mapper/<cryptname1> /dev/mapper/<cryptname2>
zfs create -p qubes/appvms
zfs create -m /var/lib/qubes/backup-zfs qubes/backup
zfs create -m /var/lib/qubes/appvms/banking qubes/appvms/banking
zfs create -m /var/lib/qubes/appvms/personal qubes/appvms/personal
zfs create -m /var/lib/qubes/appvms/untrusted qubes/appvms/untrusted
zfs create -m /var/lib/qubes/appvms/work qubes/appvms/work
~~~
Have fun with zpool and zfs.
Tips and Hints
==============
Backup your data
----------------
You're depending on an huge amount of code for this file system, keep this in mind and backup your precious data.
Encrypt underlying devices
--------------------------
~~~
dom0# cryptsetup -c aes-xts-plain64 luksFormat <device1>
dom0# cryptsetup luksOpen <device1> <cryptname1>
~~~
With the use of cryptsetup a keyfile can be specified to decrypt devices.
~~~
dom0# head -c 256 /dev/random > /root/keyfile1
dom0# chmod 0400 /root/keyfile1
dom0# cryptsetup luksAddKey <device1> /root/keyfile1
~~~
Decrypt devices on boot
-----------------------
Add your devices to /etc/crypttab.
~~~
<cryptname1> <device1> <keyfile1>
<cryptname2> <device2> none
~~~
Specifying a keyfile is especially useful, if ZFS should be ready during boot.
Further Reading
---------------
- [http://www.open-zfs.org](http://www.open-zfs.org)
- [http://zfsonlinux.org](http://zfsonlinux.org)

60
en/customization/DispvmCustomization.md Normal file
View file

@ -0,0 +1,60 @@
---
layout: doc
title: DispVMCustomization
permalink: /en/doc/dispvm-customization/
redirect_from:
- /doc/DispVMCustomization/
- "/doc/UserDoc/DispVMCustomization/"
- "/wiki/UserDoc/DispVMCustomization/"
---
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.
In order to regenerate the Disposable VM "snapshot" (called 'savefile' on Qubes) one can use the following command in Dom0:
[joanna@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
This would create a new Disposable VM savefile based on the custom template. Now, whenever one opens a file (from any AppVM) in a Disposable VM, a Disposable VM based on this template will be used.
One can easily verify if the new Disposable VM template is indeed based on a custom template (in the example below the template called "f17-yellow" was used as a basis for the Disposable VM):
[joanna@dom0 ~]$ ll /var/lib/qubes/dvmdata/
total 0
lrwxrwxrwx 1 joanna joanna 45 Mar 11 13:59 default_dvm.conf -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm.conf
lrwxrwxrwx 1 joanna joanna 49 Mar 11 13:59 default_savefile -> /var/lib/qubes/appvms/f17-yellow-dvm/dvm-savefile
lrwxrwxrwx 1 joanna joanna 47 Mar 11 13:59 savefile_root -> /var/lib/qubes/vm-templates/f17-yellow/root.img
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:
1. Start a terminal in the `fedora-20-x64-dvm` TemplateVM by running the following command in a dom0 terminal. (By default, this TemplateVM is not shown in Qubes VM Manager. However, it can be shown by selecting "Show/Hide internal VMs.")
[user@dom0 ~]$ qvm-run -a fedora-20-x64-dvm gnome-terminal
2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing Nautilus' default file preview settings.
- Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a TorVM, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM.
3. Create an empty `/home/user/.qubes-dispvm-customized` file:
[user@fedora-20-x64-dvm ~]$ touch /home/user/.qubes-dispvm-customized
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DispVM template:
[user@dom0 ~]$ qvm-create-default-dvm --default-template --default-script
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.

10
en/customization/LanguageLocalization.md Normal file
View file

@ -0,0 +1,10 @@
---
layout: doc
title: LanguageLocalization
permalink: /en/doc/language-localization/
redirect_from:
- /doc/LanguageLocalization/
- /wiki/LanguageLocalization/
---
For digiting with special alphabets, please see this [thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ)

62
en/customization/Xfce.md Normal file
View file

@ -0,0 +1,62 @@
---
layout: doc
title: XFCE
permalink: /en/doc/xfce/
redirect_from:
- /doc/XFCE/
- "/doc/UserDoc/XFCE/"
- "/wiki/UserDoc/XFCE/"
---
XFCE installtion in dom0
========================
**Disclaimer: XFCE isn't fully integrated with Qubes environment, it still require 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
Reboot the system. At system startup, select "Xfce session" in login screen (menu on the right bottom corner of the screen).
Configuration
-------------
Things needs/recommended to be done:
- remove some useless entries from menu and panel, especially file manager, web browser
- create own favorites menu (currently standard XFCE menu isn't modified to use per-VM subsections, which makes it very inconvenient):
1. create `~/.config/menus/favorites.menu`, example content:
~~~
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
<Name>Favorites</Name>
<DefaultAppDirs/>
<DefaultDirectoryDirs/>
<Directory>favorites.directory</Directory>
<Include>
<Filename>personal-gnome-terminal.desktop</Filename>
<Filename>personal-firefox.desktop</Filename>
<Filename>work-gnome-terminal.desktop</Filename>
<Filename>work-firefox.desktop</Filename>
<Filename>mail-mozilla-thunderbird.desktop</Filename>
<Filename>mail-gnome-terminal.desktop</Filename>
<Filename>banking-mozilla-firefox.desktop</Filename>
<Filename>untrusted-firefox.desktop</Filename>
</Include>
</Menu>
~~~
2. add it to the panel: right click on panel, "add new items", select "XFCE menu", choose custom menu file - just created one

171
en/developers/CodingStyle.md Normal file
View file

@ -0,0 +1,171 @@
---
layout: doc
title: CodingStyle
permalink: /en/doc/coding-style/
redirect_from:
- /doc/CodingStyle/
- /wiki/CodingStyle/
- /trac/wiki/CodingStyle/
---
Coding Guidelines for Qubes Developers
======================================
Rationale
---------
Maintaining proper coding style is very important for any larger software project, such as Qubes. Here's why:
- It eases maintenance, such as adding new functionality or generalization later,
- It allows others (as well as the original author after some time!) to easily understand fragments of code, what they were supposed to do, and so makes it easier to later extend them with newer functionality or bug fixes,
- It allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code...
Often, developers, usually smart developers, neglect the value of proper coding style, thinking that it's most important how their code works, and expecting that if it solves some problem using a nice and neat trick, then it's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, however bright and smart, might not be a good fit for any larger project. Writing a clever exploit, that is to be used at one Black Hat show is one thing, while writing a useful software that is to be used and maintained for years, is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. We often, at Qubes project, often took shortcuts, and often wrote nasty code, and this always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the above described problem lead to a real security bug. Never assume you're smart enough that you can disregard clean and rigorous coding!
General typographic conventions
-------------------------------
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs, instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). Anyway, if this makes you feel better, assume this is just an arbitrary choice.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, still maintaining shorter line lengths improves readability. It also allows to have two parallel windows open, side by side, each with different parts of the source code.
- Class, functions, variables, and arguments naming convention for any OS other than Windows:
- `ClassName`
- `some_variable`, `some_function`, `some_argument`
- Class, functions, variables, and arguments naming convention for **Windows OS** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use hungerian notation for argument and variables
- Horizontal spacing -- maintain at least decent amount of horizontal spacing, such as e.g. add obligatory space after `if` or before `{` in C, and similar in other languages. Whether to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after and before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use `if (condition)` instead.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings -- this will allow the source code to be easily view-able in various Windows-based programs.
- **Use descriptive names for variables and functions**! Really, these days, when most editors have auto-completion feature, there is no excuse for using short variable names.
- Comments should be indent together with the code, e.g. like this:
~~~
for (...) {
// The following code finds PGP private key matching the given public key in O(1)
while (key_found) {
(...)
}
}
~~~
File naming conventions
-----------------------
- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
**File naming in Linux/Unix-like systems:**
- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
- Helper, non-executable files in `/usr/share/qubes/`
- Various config files in `/etc/qubes`
- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
- All VM-related configs, images, and other files in `/var/lib/qubes/`
- System-wide temporary files which reflect the current state of system in `/var/run/qubes`
- Logs: either log to the system-wide messages, or to `/var/log/qubes/`
**File naming in Windows systems:**
- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
- Other, 3rd party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
General programming style guidelines
------------------------------------
- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
- Make sure your code compiles and builds without warnings.
- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
~~~
// Return window id
int get_window_id (...) {
(...)
return id;
}
~~~
- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
~~~
#if 0
(...) // Some unused code here
#endif
~~~
... and preferably use some descriptive macro instead of just `0`, e.g.:
~~~
#if USE_OLD_WINDOW_TRAVERSING
(...) // Some unused code here
#endif
~~~
Not sure how to do similar thing in Python... Anyone?
> But generally, there is little excuse to keep old, unused code fragments in the code. One should really use the functionality provided by the source code management system, such as git, instead. E.g. create a special branch for storing the old, unused code -- this way you will always be able to merge this code into upstream in the future.
- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
Source Code management (Git) guidelines
---------------------------------------
- Use git to maintain all code for Qubes project.
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
- Qubes code is divided into many git repositories. There are several reasons for that:
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
- Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
- We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html).
Security coding guidelines
--------------------------
- As a general rule: **untrusted input** is our \#1 enemy!
- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
~~~
read_struct(untrusted_conf);
/* sanitize start */
if (untrusted_conf.width > MAX_WINDOW_WIDTH)
untrusted_conf.width = MAX_WINDOW_WIDTH;
if (untrusted_conf.height > MAX_WINDOW_HEIGHT)
untrusted_conf.height = MAX_WINDOW_HEIGHT;
width = untrusted_conf.width;
height = untrusted_conf.height;
~~~
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
Python-specific guidelines
--------------------------
- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
C and C++ specific guidelines
-----------------------------
- Do not place code in `*.h` files.
- Use `const` whenever possible, e.g. in function arguments passed via pointers.
- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
- Think about classes hierarchy, before start implementing specific methods.
Bash-specific guidelines
------------------------
- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.

28
en/developers/DevelBooks.md Normal file
View file

@ -0,0 +1,28 @@
---
layout: doc
title: DevelBooks
permalink: /en/doc/devel-books/
redirect_from:
- /doc/DevelBooks/
- /wiki/DevelBooks/
---
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)
- 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)
- 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)
- Good book about GIT:
- [http://progit.org/book/](http://progit.org/book/)
- Useful books about Python:
- [http://www.qtrac.eu/py3book.html](http://www.qtrac.eu/py3book.html) (Note that Qubes management tools are written in Python 2.6, but this book is still a very good choice)
- [http://www.qtrac.eu/pyqtbook.html](http://www.qtrac.eu/pyqtbook.html)

45
en/developers/DevelFaq.md Normal file
View file

@ -0,0 +1,45 @@
---
layout: doc
title: DevelFaq
permalink: /en/doc/devel-faq/
redirect_from:
- /doc/DevelFaq/
- /wiki/DevelFaq/
---
Qubes Developers FAQ
====================
1. 1. [Q: Why does dom0 need to be 64-bit?](#q-why-does-dom0-need-to-be-64-bit)
2. [Q: Why do you use KDE in Dom0? What is the roadmap for Gnome support?](#q-why-do-you-use-kde-in-dom0-what-is-the-roadmap-for-gnome-support)
3. [Q: What is the recommended build environment?](#q-what-is-the-recommended-build-environment)
4. [Q: How to build Qubes from sources?](#q-how-to-build-qubes-from-sources)
5. [Q: How do I submit a patch?](#q-how-do-i-submit-a-patch)
### Q: Why does dom0 need to be 64-bit?
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](/en/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?
Any rpm-based, 64-bit. Preferred Fedora.
### Q: How to build Qubes from sources?
See [the instruction](/en/doc/qubes-builder/)
### Q: How do I submit a patch?
See [Qubes Source Code Repositories](/en/doc/source-code/).

34
en/developers/QubesResearch.md Normal file
View file

@ -0,0 +1,34 @@
---
layout: doc
title: QubesResearch
permalink: /en/doc/qubes-research/
redirect_from:
- /doc/QubesResearch/
- /wiki/QubesResearch/
---
Here are some links to various papers/research projects that somehow relate to Qubes.
### Attacks on Intel TXT
- [Attacking Intel® Trusted Execution Technology](http://invisiblethingslab.com/resources/bh09dc/Attacking%20Intel%20TXT%20-%20paper.pdf) by Rafal Wojtczuk, Joanna Rutkowska
- [ACPI: Design Principles and Concerns](http://www.ssi.gouv.fr/IMG/pdf/article_acpi.pdf) by Loic Duflot, Olivier Levillain, and Benjamin Morin
- [Another Way to Circumvent Intel® Trusted Execution Technology](http://invisiblethingslab.com/resources/misc09/Another%20TXT%20Attack.pdf) by Rafal Wojtczuk, Joanna Rutkowska, Alex Tereshkin
- [Attacking Intel TXT® via SINIT code execution hijacking](http://www.invisiblethingslab.com/resources/2011/Attacking_Intel_TXT_via_SINIT_hijacking.pdf) by Rafal Wojtczuk and Joanna Rutkowska
### Software attacks coming through devices
- [Can you still trust your network card?](http://www.ssi.gouv.fr/IMG/pdf/csw-trustnetworkcard.pdf) by Loïc Duflot, Yves-Alexis Perez and others
- [Remotely Attacking Network Cards (or why we do need VT-d and TXT)](http://theinvisiblethings.blogspot.com/2010/04/remotely-attacking-network-cards-or-why.html) by Joanna Rutkowska
- [On Formally Verified Microkernels (and on attacking them)](http://theinvisiblethings.blogspot.com/2010/05/on-formally-verified-microkernels-and.html) by Joanna Rutkowska
- [Following the White Rabbit: Software Attacks against Intel® VT-d](http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) by Rafal Wojtczuk and Joanna Rutkowska
### Application-level security
- [Virtics: A System for Privilege Separation of Legacy Desktop Applications](http://www.eecs.berkeley.edu/Pubs/TechRpts/2010/EECS-2010-70.pdf) by Matt Piotrowski
### VMM/Xen disagregation
- [[http://tjd.phlegethon.org/words/sosp11-xoar.pdf](http://tjd.phlegethon.org/words/sosp11-xoar.pdf) "Breaking Up is Hard to Do: Security and Functionality in a Commodity Hypervisor] by Patrick Colp at el.
(Also see [this thread on xen-devel](http://www.gossamer-threads.com/lists/xen/devel/230011))

47
en/developers/SourceCode.md Normal file
View file

@ -0,0 +1,47 @@
---
layout: doc
title: SourceCode
permalink: /en/doc/source-code/
redirect_from:
- /doc/SourceCode/
- /wiki/SourceCode/
---
Qubes Source Code Repositories
==============================
All the Qubes code is kept in GIT repositories. We divided the project into several components, each of which has its own separate repository, some of them:
- `core-admin.git` -- the core Qubes infrastructure responsible for VM management, VM templates, fs sharing, etc.
- `gui-daemon.git` -- GUI virtualization, Dom0 side.
- `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
- `linux-template-builder.git` - scripts and other files used to create Qubes templates images.
You can browse the repositories [online on
GitHub](https://github.com/QubesOS/). The Qubes official repositories are on
this `QubesOS` github account.
To clone a repository:
~~~
git clone git://github.com/QubesOS/<repo_name>.git <repo_name>
~~~
e.g.:
~~~
git clone git://github.com/QubesOS/qubes-core-admin.git core-admin
~~~
## Sending a patch
If you want to contribute to the project, there are two ways:
* **Preferred**: Use github [fork & pull requests](https://guides.github.com/activities/forking/)
* Sending a patch via the project's 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.
2. Add the changes and commit them (git add, git commit). Never mix different changes into one commit! Write a good description of the commit. The first line should contain a short summary, and then, if you feel like more explanations are needed, enter an empty new line, and then start the long, detailed description (optional).
3. Test your changes NOW: check if RPMs build fine, etc.
4. Create the patch using 'git format-patch'. This has an advantage over 'git diff', because the former will also include your commit message, your name and email, so that \*your\* name will be used as a commit's author.
5. Send your patch to qubes-devel. Start the message subject with the '[PATCH]' string.

53
en/developers/SystemDoc.md Normal file
View file

@ -0,0 +1,53 @@
---
layout: doc
title: SystemDoc
permalink: /en/doc/system-doc/
redirect_from:
- /doc/SystemDoc/
- /wiki/SystemDoc/
---
System Documentation for Developers
===================================
Fundamentals
------------
* [Qubes OS Architecture Overview](/en/doc/qubes-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](/en/doc/security-critical-code/)
* Qubes RPC: [`qrexec` v2](/en/doc/qrexec/) ([R2 implementation](/en/doc/qrexec2-implementation/))
* Qubes RPC: [`qrexec` v3](/en/doc/qrexec3/) ([R3 implementation](/en/doc/qrexec3-implementation/)) (Odyssey)
* [Example for writing a `qrexec` service in Qubes OS (blog post)](http://theinvisiblethings.blogspot.com/2013/02/converting-untrusted-pdfs-into-trusted.html)
* [Qubes GUI virtualization protocol](/en/doc/gui-docs/)
* [Networking in Qubes](/en/doc/qubes-net/)
* [Implementation of template sharing and updating](/en/doc/template-implementation/)
Services
--------
* [Inter-domain file copying](/en/doc/qfilecopy/) (deprecates [`qfileexchgd`](/en/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/en/doc/qmemman/)
* [Implementation of DisposableVMs](/en/doc/dvm-impl/)
* [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
* [Dom0 secure update mechanism](/en/doc/dom0-secure-updates/)
* VM secure update mechanism (forthcoming)
Debugging
---------
* [Profiling python code](/en/doc/profiling/)
* [Test environment in separate machine for automatic tests](/en/doc/test-bench/)
* [Automated tests](/en/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/en/doc/vm-interface/)
* [Debugging Windows VMs](/en/doc/windows-debugging/)
Building
--------
* [Building Qubes](/en/doc/qubes-builder/) (["API" Details](/en/doc/qubes-builder-details/))
* [Development Workflow](/en/doc/development-workflow/)
* [KDE Dom0 packages for Qubes](/en/doc/kde-dom0/)
* [How to build Qubes installation ISO](/en/doc/installation-iso-building/)
* [Building Qubes OS 3.0 ISO](/en/doc/qubes-r3-building/)
* [Building USB passthrough support (experimental)](/en/doc/usbvm/)
* [Building a TemplateVM based on a new OS (ArchLinux example)](/en/doc/building-non-fedora-template/)
* [Building the Archlinux Template](/en/doc/building-archlinux-template/)

150
en/developers/VersionScheme.md Normal file
View file

@ -0,0 +1,150 @@
---
layout: doc
title: VersionScheme
permalink: /en/doc/version-scheme/
redirect_from:
- /doc/VersionScheme/
- /wiki/VersionScheme/
---
Version Scheme
==============
Beginning with R3 release, we change (and formalise) the versioning scheme.
From now on, it will be as follows.
Qubes distributions and products
--------------------------------
We intend to make it easy to make a remix of qubes, targetting another
hypervisor or isolation provider. We may also create commercial products
intended for specific circumstances. There is one distinguished distribution
called **Qubes OS**. All source code for it is available for download under GPL
licence and is openly developed on the mailing lists. The rest of this document
discusses Qubes OS. Another remix may have its own version series.
Release version
---------------
Qubes OS as a whole is released from time to time. Version scheme for all
releases is modelled after Linux kernel version numbers. When announcing new
release, we decide on the major.minor version (like `3.0`) and release
`3.0-rc1`. When we feel that enough progress has been made, we put `3.0-rc2`
and so on. All these versions are considered unstable and not ready for
production. You may ask for support on mailing lists (specifically
**qubes-devel**), but it is not guaranteed (you may for example get answer
„update to newer `-rc`”). Public ISO image may or may not be available.
When enough development has been made, we announce the first stable version,
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
we support it for some period. Core components are branched at this moment and
bugfixes are backported from master branch. Questions about stable release
should be directed to the **qubes-users** mailing list. No major features and
interface incompatibilities are to be included in this release. We release
bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the next
release e.g. `3.1-rcX`.
Tickets in the tracker are sorted out by release major.minor, such as `3.0`,
`3.1` (trac calls this „milestone”).
Release schedule
----------------
There is no specific schedule for major and minor other that more general
roadmap. When time comes, Supreme Committee declares feature freeze and tags
`-rc1` and releases ISO image. From this time on, no new features are accepted.
Also a strict time schedule kicks in.
Each release candidate period is as follows. For the first two weeks we accept
and assign bugreports to be fixed before next release candidate. For the next
two weeks we generally focus on fixing assigned bugreports, so issues discovered
during this time may be postponed until later RC. Finally after that there is
one week of current-testing freeze, during which time no new packages are
released, in hope that they will be installed by wider user base and tested.
The next RC is released five weeks after the former. All packets are published
in `current` repository and the cycle starts over. There should be no less than
1 and no more than 3 release candidates before final release.
<table border>
<thead>
<tr><th>stage</th><th>time</th></tr>
</thead>
<tbody>
<tr><td>initial testing</td><td>2 weeks</td></tr>
<tr><td>bug fixing</td><td>2 weeks</td></tr>
<tr><td>`current-testing` freeze</td><td>1 week</td></tr>
</tbody>
</table>
Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
(after primary bug-reporting period) the Supreme Committee decides wether there
should be another RC. If, based on remaining issues, the Committee decides to
release final, then the Committee agrees upon the release date, which should be
no later than a week after.
!["Release cycle"](/attachment/wiki/VersionScheme/release-cycle.svg)
Bug priorities
--------------
When deciding whether the current release candidate is the final one, the Committee
takes bugs priorities into consideration. The meaning of them is as follows:
* `blocker` - when any such bug is present in the current release candidate, it
can't be considered final release. Bugs with this priority must be fixed before
the next release candidate, even if that means delaying its release (which
should be considered only last resort option).
* `critical` - when any such bug is present in the current release candidate, it
can't be considered final release. But such bugs are not qualified to delay
next release candidate release.
* `major` - existence of such bugs do not strictly prevent the current release
candidate be considered final (but of course we should try hard to not have
them there). Fixing bugs of this priority can be delayed and qualified as
updates to the final stable release.
* `minor` - existence of such bugs do not prevent the current release candidate
be considered final. Fixing such bugs can be delayed to the next Qubes OS
release. Eventually such fixes might be backported as an update to the stable
release(s).
All above is about bugs, no features should be assigned to the current release
after first `-rc`. Supreme Committee is free to adjust priorities appropriately.
Component version
-----------------
Qubes release is defined as specific versions of components, which are
developed more or less separately. Their versions are composed of major and
minor version of target Qubes OS release followed by third component which is
just incremented. There is no apparent indication that given version is stable
or not.
There are some non-essential components like `qubes-apps-*` that are shared
between releases. Their versions indicate oldest qubes-release that is
supported. We try hard to support multiple releases by one branch to ease code
maintenance.
Different Qubes releases remixes may comprise of different components and
version are not guaranteed to be monotonic between releases. We may decide that
for newer release some component should be downgraded. There is no guarantee
that arbitrary combination of different versions of random components will
yield usable (or even install-able) compilation.
Git tags and branches
---------------------
We mark each component version in the repository by tag containing
`v<version>`. Likewise, each Qubes OS release is marked by `R<release>` tag.
At the release of some release we create branches named like `release2`. Only
bugfixes and compatible improvements are backported to these branches. These
branches should compile. All new development is done in `master` branch. This
branch is totally unsupported and may not even compile depending on maintainer
of repository.
All version and release tags should be made and signed by someone from ITL
staff. Public keys are included in `qubes-builder` and available at
[https://keys.qubes-os.org/keys/](https://keys.qubes-os.org/keys/).

232
en/developers/building/BuildingArchlinuxTemplate.md Normal file
View file

@ -0,0 +1,232 @@
---
layout: doc
title: BuildingArchlinuxTemplate
permalink: /en/doc/building-archlinux-template/
redirect_from:
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
---
Template building
=================
The archlinux VM is now almost working as a NetVM. Based on qubes-builder code, you could find below how to build it and problem that could arise from template building to using archlinux as a netvm:
Download qubes-builder git code
-------------------------------
Prefer marmarek git repository as it is the most recent one
Change your builder.conf
------------------------
Change the following variables GIT\_SUBDIR=marmarek DISTS\_VM=archlinux
Get all required sources
------------------------
~~~
make get-sources
~~~
Note that make get-sources sometimes fails because it didn't download packages that are not used by archlinux such as xfce or kde packages.
You can ignore the repositories that are failing by adding the following line to your builder.conf:
~~~
COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
~~~
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
Make all required qubes components
----------------------------------
The first use of the builder can take several hours depending on your bandwidth as it will install an archlinux chroot:
~~~
make vmm-xen-vm
make core-vchan-xen-vm
make linux-utils-vm
make core-agent-linux-vm
make gui-common-vm
make gui-agent-linux-vm
~~~
Now build the template itself
-----------------------------
This can take again several hours, especially the first time you built and archlinux template:
~~~
make linux-template-builder
~~~
Retrieve your template
----------------------
You can now find your template in qubes-src/linux-template-builder/rpm/noarch. Install it in dom0 (just take care as it will replace your current archlinux-x64 template)
* * * * *
Known problems during building or when running the VM
=====================================================
Can't open file archlinux-2013.02.01-dual.iso
---------------------------------------------
Archlinux ISO files are sometimes removed from mirrors. Check the last version available on the archlinux mirror (eg: [http://mir.archlinux.fr/iso/](http://mir.archlinux.fr/iso/)), and update qubes-src/linux-template-builder/scripts\_archlinux/00\_prepare.sh accordingly:
~~~
ISO_VERSION=2013.06.01
~~~
You will also need to download the signature matching this ISO version inside qubes-src/linux-template-builder/scripts\_archlinux/:
~~~
wget http://mir.archlinux.fr/iso/2013.06.01/archlinux-2013.06.01-dual.iso.sig
~~~
The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm:
-----------------------------------------------------------------------------------------------
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
~~~
<deny send_destination="org.freedesktop.NetworkManager"/>
~~~
to
~~~
<allow send_destination="org.freedesktop.NetworkManager"/>
~~~
DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all.
--------------------------------------------------------------------------------------
The sound does not work in AppVMs and there are messages related to pulse segfault in glibc when running dmesg (FIXED)
----------------------------------------------------------------------------------------------------------------------
This is apparently a bug in Archlinux between glibc and pulseaudio package 4.0-6. The packages pulseaudio-4.0-2 and libpulse-4.0-2 are known to work and can be downloaded and reinstalled manually.
Error when building the gui-agent-linux with pulsecore error
------------------------------------------------------------
~~~
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
~~~
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
You can create fake new headers just by copying the old headers:
~~~
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
~~~
You can check the current archlinux pulseaudio version like this:
~~~
sudo chroot chroot-archlinux/ pacman -Qi pulseaudio
~~~
chroot-archlinux/dev/pts has not been unmounted
-----------------------------------------------
This is a known problem when there are errors during building. Check what is mounted using the command mount (with no parameters). Just unmount what you can (or reboot your vm if you are too lazy :) )
Known problems in Qubes R2-B2
=============================
xen-vmm-vm fail to build with a PARSETUPLE related error (FIXED):
-----------------------------------------------------------------
Commenting out "\#define HAVE\_ATTRIBUTE\_FORMAT\_PARSETUPLE" from chroot\_archlinux/usr/include/python2.7/pyconfig.h fixes the problem, but it isn't the right solution [1]...
A better fix is planned for the next python release (the bug is considered release blocking), and will be updated in archlinux chroot as soon as available.
[1] [http://bugs.python.org/issue17547](http://bugs.python.org/issue17547)
The boot process fails without visible errors in the logs, but spawn a recovery shell
-------------------------------------------------------------------------------------
The problem is a new conflict between systemd and the old sysvinit style. To fix this, you can change the master xen template in dom0 to remove sysvinit remains: Edit **INSIDE DOM0** /usr/share/qubes/vm-template.conf, and change the variable 'extra' that contains the kernel variables: from:
~~~
extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
~~~
to:
~~~
extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
~~~
Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
----------------------------------------------------------------------------------------------------
Apply the following fix in the template to revert the variable name to the old Qubes version.
You can edit the template the following way:
~~~
sudo mkdir /mnt/vm
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
sudo chroot /mnt/vm
~~~
Then apply the fix:
~~~
sudo sed 's:qubes-keyboard:qubes_keyboard:g' -i /etc/X11/xinit/xinitrc.d/qubes-keymap.sh
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/lib/qubes/init/qubes-sysinit.sh
sudo sed 's:qubes-ip:qubes_ip:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netmask:qubes_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-gateway:qubes_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-secondary-dns:qubes_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-iptables-domainrules:qubes_iptables_domainrules:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-header:qubes_iptables_header:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-error:qubes_iptables_error:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables:qubes_iptables:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_trigger_sync_appmenus.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/bin/qubes-session
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/bin/qubes-session
~~~
Do not forgot to:
~~~
umount /mnt/vm
~~~
Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
---------------------------------------------------------------------------------------------
Again you built a template based on a recent Qubes API which has not been released yet. So skip the dependency for now:
~~~
sudo rpm -U --nodeps yourpackage.rpm
~~~

159
en/developers/building/BuildingNonFedoraTemplate.md Normal file
View file

@ -0,0 +1,159 @@
---
layout: doc
title: BuildingNonFedoraTemplate
permalink: /en/doc/building-non-fedora-template/
redirect_from:
- /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/
---
Building a TemplateVM for ArchLinux (or another non fedora OS)
==============================================================
If you don't like using Fedora because of specific administration or package management / building needs, you could build a VM Template for your Distribution of choice.
This article shows how to build a template for a different OS, taking ArchLinux as an example.
Qubes builder scripts
=====================
You can start creating Qubes builder scripts for your new OS. Just note that it will probably make your testing process harder than trying to build the package directly in an HVM on which you already installed this new OS.
chroot initialization
---------------------
You need to install your OS inside a chroot that will be used to build all the required qubes agents of tools.
The scripts you will be interested in will be inside the qubes-src/linux-template-builder project:
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
~~~
### 00\_prepare.sh
The goal of the first script 00\_prepare.sh is to download and verify the signature of the installation cd and tools. You can use the \$CACHEDIR directory variable to store files that could be reused (such as downloaded scripts or iso files)
### 01\_install\_core.sh
The goal of this script is to install a base environment of your target OS inside the \$INSTALLDIR directory variable. Generally you need to bootstrap/install your package manager inside the \$INSTALLDIR directory and install the base packages.
### Testing the installation process
Edit the builder.conf file to change the variable DISTS\_VM to your OS name (DISTS\_VM=your\_os\_name). The try to make the template to check that at least these to first scripts are working correctly:
~~~
make linux-template-builder
~~~
Qubes builder Makefiles
-----------------------
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside qubes-builder:
~~~
prepare-chroot-yourOSname
Makefile.yourOSname
~~~
### prepare-chroot-yourOSname
The goal of this file is to prepare a development environment of your target OS inside a chroot. You will reuse there the 00\_prepare.sh and 01\_install\_core.sh scripts. Additionally, the following things will be necessary to use to chroot environment:
- the \$1 variable will contain the installation directory (INSTALLDIR should contain the same value than \$1 when you run 00\_prepare or 01\_install\_core)
- after your base system is installed, you should install development tools and libraries (gcc, make, ...)
- create a user called 'user' inside your chroot, and give him enought right to run the command sudo without any password
- register all the repository that could be necessary and synchronize the package database
- register a custom repository that will be used to store qubes packages
### Makefile.yourOSname
This file will be used to define the action required when installing a package. The most important one are:
- dist-prepare-chroot: that's where you will call prepare-chroot-yourOSname if the chroot has not been initialized
- dist-package: that's where you will chroot the development environment and run the command used to build a package.
- dist-build-dep: that's where you will create the custom repository for your target OS based on already compiled packages.
These additional target need to exist once you created your first packages:
- dist-copy-out: that's where you will retrieve the package you just built and put it with all the other package you prepared.
- update-repo: that's where you will retrieve the package that have been built and that need to be installed inside the template
### Testing the development chroot
You will be able to test these script when making the first qubes packages. Don't forget that the first things that run when running 'make somcomponent-vm' will be these two scripts, and that you will need to debug it at this point.
Qubes packages
--------------
### vmm-xen-vm
### core-vchan-xen-vm
### linux-utils-vm
### core-agent-linux-vm
### gui-common-vm
### gui-agent-linux-vm
Additional Installation scripts
-------------------------------
Again you need to work on scripts inside the qubes-src/linux-template-builder project:
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
~~~
### 02\_install\_groups.sh
The goal of this script is to install all the package that you want to use in your template (eg: firefox, thunderbird, a file manager, Xorg...)
### 04\_install\_qubes.sh
The goal of this script is to install in your template all the packages you built previously. Also you need to edit the fstab file of your template to mount qubes virtual hard drives.
### 09\_cleanup.sh
This script is use to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ...
Starting with an HVM
====================
If no Qubes packages are available for your selected OS. You could start to install an HVM with your OS. Your goals will be:
- to identify how to install the OS using command lines
- to create required Qubes packages
- to identify potential issue making all Qubes agents and scripts working correctly.
As soon as you manage to make qrexec and qubes-gui-agent working, it should be sufficient to start preparing a template VM.
### Xen libraries
Several XEN libraries are required for Qubes to work correctly. In fact, you need to make xenstore commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developpers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone git://git.qubes-os.org/marmarek/xen`
Find the .spec file in the git repository (this is the file being used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'xen-vm'. For example, a PKGBUILD has been created for [ArchLinux](/en/doc/templates/archlinux/) and can be found on [http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD](http://aur.archlinux.org/packages/qu/qubes-vm-xen/PKGBUILD).
Don't be afraid with the complexity of the PKGBUILD, most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository.
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the folowing line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`
Now install the package you built and mount /proc/xen. Verify that xenstore-read works by running: `xenstore-read qubes_vm_type` That should give you the current VM type such as HVM or AppVM.
### Qubes-OS core agents (qrexec...)
[https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD)
### Qubes-OS kernel modules
[https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD)
### Qubes-OS gui agents
[https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD)

204
en/developers/building/DevelopmentWorkflow.md Normal file
View file

@ -0,0 +1,204 @@
---
layout: doc
title: DevelopmentWorkflow
permalink: /en/doc/development-workflow/
redirect_from:
- /doc/DevelopmentWorkflow/
- /wiki/DevelopmentWorkflow/
---
Development Workflow
====================
A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/en/doc/qubes-builder/). This guide assumes you're using qubes-builder to build Qubes.
Repositories and committing Code
--------------------------------
Qubes is split into a bunch of git repos. This are all contained in the `qubes-src` directory under qubes-builder.
FIXME(ypid): Not on github?
The best way to write and contribute code is to create a git repo somewhere (e.g., github) for the repo you are interested in editing (e.g., `qubes-manager`, `core`, etc). To integrate your repo with the rest of Qubes, cd to the repo directory and add your repository as a remote in git
**Example:**
~~~
$ cd qubes-builder/qubes-src/qubes-manager
$ git remote add abel git@github.com:abeluck/qubes-manager.git
~~~
You can then proceed to easily develop in your own branches, pull in new commits from the dev branches, merge them, and eventually push to your own repo on github.
When you are ready to submit your changes to Qubes to be merged, push your changes, then create a signed git tag (using `git tag -s`). Finally, send a letter to the Qubes listserv describing the changes and including the link to your repository. Don't forget to include your public PGP key you use to sign your tags.
### Kernel-specific notes
#### Prepare fresh version of kernel sources, with Qubes-specific patches applied
In qubes-builder/qubes-src/kernel:
~~~
make prep
~~~
The resulting tree will be in kernel-\<VERSION\>/linux-\<VERSION\>:
~~~
ls -ltrd kernel*/linux*
~~~
~~~
drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18
drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
~~~
#### Go to the kernel tree and update the version
In qubes-builder/qubes-src/kernel:
~~~
cd kernel-3.4.18/linux-3.4.18
~~~
#### Changing the config
In kernel-3.4.18/linux-3.4.18:
~~~
cp ../../config-pvops .config
make oldconfig
~~~
Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18:
~~~
make menuconfig
~~~
Copy the modified config back into the kernel tree:
~~~
cp .config ../../../config-pvops
~~~
#### Patching the code
TODO: describe the workflow for patching the code, below are some random notes, not working well
~~~
ln -s ../../patches.xen
export QUILT_PATCHES=patches.xen
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
export QUILT_SERIES=../../series-pvops.conf
quilt new patches.xen/pvops-3.4-0101-usb-xen-pvusb-driver-bugfix.patch
quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \
drivers/usb/host/xen-usbback/* drivers/usb/host/xen-usbfront.c \
include/xen/interface/io/usbif.h
*edit something*
quilt refresh
cd ../..
vi series-pvops.conf
~~~
#### Building RPMS
TODO: Is this step generic for all subsystems?
Now it is a good moment to make sure you have changed kernel release name in rel-pvops file. For example, if you change it to '1debug201211116c' the resulting RPMs will be named 'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help distinguish between different versions of the same package.
You might want to take a moment here to review (git diff, git status), commit your changes locally.
To actually build RPMS, in qubes-src/kernel:
~~~
make rpms
~~~
RPMS will appear in qubes-src/kernel/rpm/x86\_64:
~~~
-rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
~~~
### Useful [QubesBuilder](/en/doc/qubes-builder/) commands
1. *make check* - will check if all the code was commited into repository and if all repository are tagged with signed tag.
2. *make show-vtags* - show version of each component (based on git tags) - mostly useful just before building ISO. **Note:** this will not show version for components containing changes since last version tag
3. *make push* - push change from **all** repositories to git server. You must set proper remotes (see above) for all repositories first.
4. *make prepare-merge* - fetch changes from remote repositories (can be specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally) verify tags and show the changes. This do not merge the changes - there are left for review as FETCH\_HEAD ref. You can merge them using "git merge FETCH\_HEAD" (in each repo directory).
Copying Code to dom0
--------------------
When developing it is convenient to be able to rapidly test changes. Assuming you're developing Qubes on Qubes, you should be working in a special VM for Qubes and occasionally you will want to transfer code or rpms back to dom0 for testing.
Here are some handy scripts Marek has shared to facilitate this.
You may also like to run your [test environment on separate machine](/en/doc/test-bench/).
### Syncing dom0 files
TODO: edit this script to be more generic
~~~
#!/bin/sh
set -x
set -e
QUBES_PY_DIR=/usr/lib64/python2.6/site-packages/qubes
QUBES_PY=$QUBES_PY_DIR/qubes.py
QUBESUTILS_PY=$QUBES_PY_DIR/qubesutils.py
qvm-run -p qubes-devel 'cd qubes-builder/qubes-src/core/dom0; tar c qmemman/qmemman*.py qvm-core/*.py qvm-tools/* misc/vm-template-hvm.conf misc/qubes-start.desktop ../misc/block-snapshot aux-tools ../qrexec' |tar xv
cp $QUBES_PY qubes.py.bak$$
cp $QUBESUTILS_PY qubesutils.py.bak$$
cp /etc/xen/scripts/block-snapshot block-snapshot.bak$$
sudo cp qvm-core/qubes.py $QUBES_PY
sudo cp qvm-core/qubesutils.py $QUBESUTILS_PY
sudo cp qvm-core/guihelpers.py $QUBES_PY_DIR/
sudo cp qmemman/qmemman*.py $QUBES_PY_DIR/
sudo cp misc/vm-template-hvm.conf /usr/share/qubes/
sudo cp misc/qubes-start.desktop /usr/share/qubes/
sudo cp misc/block-snapshot /etc/xen/scripts/
sudo cp aux-tools/qubes-dom0-updates.cron /etc/cron.daily/
# FIXME(Abel Luck): I hope to
~~~
### Apply qvm-tools
TODO: make it more generic
~~~
#!/bin/sh
BAK=qvm-tools.bak$$
mkdir -p $BAK
cp -a /usr/bin/qvm-* /usr/bin/qubes-* $BAK/
sudo cp qvm-tools/qvm-* qvm-tools/qubes-* /usr/bin/
~~~
### Copy from dom0 to an appvm
~~~
#/bin/sh
#
# usage ./cp-domain <vm_name> <file_to_copy>
#
domain=$1
file=$2
fname=`basename $file`
qvm-run $domain 'mkdir /home/user/incoming/dom0 -p'
cat $file| qvm-run --pass-io $domain "cat > /home/user/incoming/dom0/$fname"
~~~

88
en/developers/building/InstallationIsoBuilding.md Normal file
View file

@ -0,0 +1,88 @@
---
layout: doc
title: InstallationIsoBuilding
permalink: /en/doc/installation-iso-building/
redirect_from:
- /doc/InstallationIsoBuilding/
- /wiki/InstallationIsoBuilding/
---
How to build Qubes installation ISO
===================================
Qubes uses [Fedora Unity Revisor](http://revisor.fedoraunity.org/) to build the installation ISO.
You may want to get familiar with [Revisor documentation](http://revisor.fedoraunity.org/documentation).
Build installer packages
------------------------
Get [Qubes Installer repository](http://git.qubes-os.org/?p=smoku/installer) and build its packages:
~~~
cd installer
make rpms
~~~
Packages will be in `rpm/noarch` and `rpm/x86_64`.
Install Revisor
---------------
Next install the freshly built revisor and anaconda:
~~~
yum install rpm/noarch/revisor*.rpm
yum install rpm/x86_64/anaconda*.rpm
~~~
Review configuration files
--------------------------
All configuration files for Qubes Revisor are kept in the ~~~conf/~~~ directory:
- `conf/qubes-install.conf` - Main Revisor configuration file. This configures Revisor to build Qubes Installation image based on Fedora 13. All other configuration files and working directories are pointed here.
- `conf/qubes-x86_64.conf` - This file describes all repositories needed to build Qubes for x86\_64 architecture.
- `conf/qubes-kickstart.cfg` - Fedora Kickstart formatted file describing which packages should land in the ISO `/Packages` repository. This describes basically what will be available for installation. The packages list built using this file will be further filtered by the comps file.
- `conf/comps-qubes.xml` - Repository Comps file for ISO `/Packages` repository, describing packages and package groups of the installer repository. Package groups are used to select which of the packages are mandatory to install, which are optional and which are to be just available on the ISO but not installed by default (not used on Qubes).
Create/Update local repository
------------------------------
Revisor fetches all RPM packages from YUM repositories. We currently use 5 repositories:
- `yum/installer` (installer-related rpms)
- `yum/qubes-dom0` (all the Qubes stuff)
- `yum/dom0-updates` (for select 3rd party packages, e.g. Xorg)
- `yum/fedora13-repo` (local fedora 13 repo, copy from DVD)
- remote fedora repo for extra packages (usually deps for qubes-dom0)
You need to manually copy the Fedora 13 installation DVD contents (`Packages/` and `repodata/` directories) into `build/fedora13-repo`.
Also, you need to copy all the qubes dom0 rpms into `build/yum/qubes-dom0/rpm` and run the `yum/update_repo.sh` script afterwards.
In order to fill the `build/yum/installer` repo one can just use `make update-repo`.
The `build/yum/dom0-updates` is to be used for select rpms that should also be used instead of those from the fedora (loacal and remote) repos.
Update your local repos:
~~~
make update-repo
~~~
Build ISO
---------
Now you're finally ready to build the ISO image:
~~~
make iso
~~~
and wait...
You may add `-d 1` (or `-d 99` if you're a masochist) in the Makefile at the end of the revisor command to get (a ton of) debugging information.

56
en/developers/building/KdeDom0.md Normal file
View file

@ -0,0 +1,56 @@
---
layout: doc
title: KdeDom0
permalink: /en/doc/kde-dom0/
redirect_from:
- /doc/KdeDom0/
- /wiki/KdeDom0/
---
Qubes-customized KDE packages for Dom0
======================================
The Qubes kde-dom0 project (see [Source Code](/en/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

135
en/developers/building/QubesBuilder.md Normal file
View file

@ -0,0 +1,135 @@
---
layout: doc
title: QubesBuilder
permalink: /en/doc/qubes-builder/
redirect_from:
- /doc/QubesBuilder/
- /wiki/QubesBuilder/
---
Building Qubes from scratch
===========================
We have a fully automated build system for Qubes, that downloads, builds and
packages all the Qubes components, and finally should spit out a ready-to-use
installation ISO.
In order to use it one should use an rpm-based distro, like Fedora :) and should ensure the following packages are installed:
- git
- createrepo
- rpm-build
- make
- wget
- rpmdevtools
- python-sh
- dialog
- rpm-sign
Unusually one can install those packages by just issuing:
sudo yum install git createrepo rpm-build make wget rpmdevtools python-sh dialog rpm-sign
The build system creates build environments in chroots and so no other packages are needed on the host. All files created by the build system are contained within the qubes-builder directory. The full build requires some 25GB of free space, so keep that in mind when deciding where to place this directory.
The build system is configured via builder.conf file -- one should copy the attached builder.conf.default, and modify it as needed, e.g.:
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
NO_SIGN=1
One additional useful requirement is that 'sudo root' work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). This is important as the builder needs to switch to root and then back to user several times during the build process.
Additionally, if building with signing enabled (so NO\_SIGN is not set), one must adjust \~/.rpmmacro file so that it point to the GPG key used for package signing, e.g.:
%_signature gpg
%_gpg_path /home/user/.gnupg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
It is also recommended to use an empty passphrase for the private key used for signing. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over, whether you use additional passphrase for the key or not.
So, to build Qubes one would do:
# Import the Qubes master key
gpg --recv-keys 0x36879494
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
wget http://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
cd qubes-builder
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
# NO_SIGN="1"
# Download all components:
make get-sources
# And now to build all Qubes rpms (this will take a few hours):
make qubes
# ... and then to build the ISO
make iso
And this should produce a shiny new ISO.
You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon:
make gui-daemon
Full list you can get from make help. For advanced use and preparing sources
for use with [QubesBuilder](/en/doc/qubes-builder/) take a look at [doc directory
in QubesBuilder](https://github.com/marmarek/qubes-builder/tree/master/doc) or
[QubesBuilderDetails](/en/doc/qubes-builder-details/) page.
Making customized build
-----------------------
### Manual source modification
If you want to somehow modify sources, you can also do it, here are some basic steps:
1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command)
2. Edit builder.conf (still the same as above), some useful additions:
- You can also set GIT\_PREFIX="marmarek/qubes-" to use my repo instead of "mainstream" - it contains newer (but less tested) versions
3. Download unmodified sources
make get-sources
4. **Make your modifications here**
5. Build the Qubes
`make qubes` actually is just meta target which build all required
components in correct order. List of components is configured in
builder.conf. You can also check the current value at the end of `make
help`, or using `make build-info`.
6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
1. build iso installation image
make iso
Code verification keys management
=================================
[QubesBuilder](/en/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:
GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY
# here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder
All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically.
If you are the owner of Master key and want to revoke such signature, use the `revsig` gpg key edit command and update the key in qubes-developers-keys.asc - now the key will be no longer trusted (unless manually set as such).

48
en/developers/building/QubesBuilderDetails.md Normal file
View file

@ -0,0 +1,48 @@
---
layout: doc
title: QubesBuilderDetails
permalink: /en/doc/qubes-builder-details/
redirect_from:
- /doc/QubesBuilderDetails/
- /wiki/QubesBuilderDetails/
---
[QubesBuilder](/en/doc/qubes-builder/) "API"
========================================
Components Makefile.builder file
--------------------------------
[QubesBuilder](/en/doc/qubes-builder/) expects that each component have *Makefile.builder* file in its root directory. This file specifies what should be done to build the package. As name suggests, this is normal makefile, which is included by builder as its configuration. Its main purpose is to set some variables. Generally all available variables/settings are described as comments at the beginning of Makefile.\* in [QubesBuilder](/en/doc/qubes-builder/).
Variables for Linux build:
- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/en/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/en/doc/qubes-builder/) will install all makedepends, then build the package.
Most components uses *archlinux* directory for this purpose, so its good to keep this style.
Variables for Windows build:
- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
- `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
- `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
- `CERT_FILENAME` Path to key file (pfx format)
- `CERT_PASSWORD` Key password
- `CERT_PUBLIC_FILENAME` Certificate path in case of self-signed cert
- `CERT_CROSS_CERT_FILENAME` Certificate path in case of correct autheticode cert
- `SIGNTOOL` Path to signtool
- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/en/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/en/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
builder.conf settings
---------------------
Most settings are documented in *builder.conf.default* file, which can be used as template the actual configuration.
**TODO**

58
en/developers/building/QubesR3Building.md Normal file
View file

@ -0,0 +1,58 @@
---
layout: doc
title: QubesR3Building
permalink: /en/doc/qubes-r3-building/
redirect_from:
- /doc/QubesR3Building/
- /wiki/QubesR3Building/
---
Building Qubes OS 3.0 ISO
=========================
Ensure your system is rpm-based and that you have necessary dependencies installed (see [QubesBuilder](/en/doc/qubes-builder/) for more info):
~~~
sudo yum install git createrepo rpm-build make wget rpmdevtools pandoc
~~~
Get the necessary keys to verify the sources:
~~~
$ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
$ gpg --import qubes-master-signing-key.asc
$ gpg --edit-key 36879494
# Verify fingerprint!, set trust to *ultimate*
$ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
$ gpg --import qubes-developers-keys.asc
~~~
Note we do *not* relay above on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensure they match!
Now lets bootstrap the builder. Unfortunately the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:
~~~
$ git clone git://github.com/QubesOS/qubes-builder.git
$ cd qubes-builder
$ git describe --exact-match HEAD
<some tag>
$ git tag -v <some tag>
~~~
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, as the builder will do that for us, for each component, every time we, even for all aux files (e.g. Xen or Linux kernel sources).
Let's configure the builder first (we can use one of the example configs, either for R2 or "master", which currently means pre-released R3):
~~~
cp example-configs/qubes-os-master.conf builder.conf
~~~
You can take a loot at the `builder.conf.default` for a description of all available options. Nevertheless, the default config should be enough for start:
~~~
$ make get-sources qubes
$ make sign-all # this requires setting SIGN_KEY in the builder.conf, can be skipped for test builds.
$ make iso
~~~
Enjoy your new ISO!

37
en/developers/building/Usbvm.md Normal file
View file

@ -0,0 +1,37 @@
---
layout: doc
title: USBVM
permalink: /en/doc/usbvm/
redirect_from:
- /doc/USBVM/
- /wiki/USBVM/
---
USB Pass through: USBVM
-----------------------
**WARNING:** This is experimental and very broken.
Source: [https://groups.google.com/d/msg/qubes-devel/4AKulABh2Jc/\_R7SRSC4peYJ](https://groups.google.com/d/msg/qubes-devel/4AKulABh2Jc/_R7SRSC4peYJ)
You'll need the patch tagged abb\_e58b432 from [git://github.com/grwl/qubes-core.git](git://github.com/grwl/qubes-core.git).
The rest is in RPMs, yes. I roughly follow this procedure to have pvusb on Qubes 1.0:
- rebuild kernel, core, and xen from marmarek's repo (devel-3.4 branch for kernel),
- make dedicated usbvm domain, passthrough USB controller PCI devices there
- in usbvm: "rpm -Uhv qubes-core-vm-2.1.1-1.fc17.x86\_64.rpm xen-libs-2000:4.1.3-18.fc17.x86\_64.rpm xen-qubes-vm-essentials-2000:4.1.3-18.fc17.x86\_64.rpm"
- in appvm where you want to attach the device to: "rpm -Uhv qubes-core-vm-2.1.1-1.fc17.x86\_64.rpm"
- in dom0 I think the following packages need to be updated, don't have exact list now.qubes-core-dom0 is actually important, the rest are dependencies:
> kernel-qubes-vm-3.4.18-1.pvops.qubes.x86\_64.rpm
> qubes-core-dom0-2.1.1-1.fc13.x86\_64.rpm
> xen-4.1.3-18.fc13.x86\_64.rpm
> xen-hvm-4.1.3gui2.0.9-18.fc13.x86\_64.rpm
> xen-hypervisor-4.1.3-18.fc13.x86\_64.rpm
> xen-libs-4.1.3-18.fc13.x86\_64.rpm
> xen-licenses-4.1.3-18.fc13.x86\_64.rpm
> xen-runtime-4.1.3-18.fc13.x86\_64.rpm
- plug or replug some USB device -- it will be picked up by usbvm, and in dom0 it will appear in the output of qvm-usb

33
en/developers/contributing.md Normal file
View file

@ -0,0 +1,33 @@
---
layout: doc
title: Contributing
permalink: /en/doc/contributing/
redirect_from:
- /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](/en/doc/reporting-bugs/)
- Code audit (e.g. gui-daemon)
- New features
- Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc)
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](/en/doc/qubes-lists/) list), to avoid a situation when two or more independent people would work on the same feature at the same time, doubling each others 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](/en/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.

136
en/developers/debugging/AutomatedTests.md Normal file
View file

@ -0,0 +1,136 @@
---
layout: doc
title: Automated tests
permalink: /en/doc/automated-tests/
redirect_from: /doc/AutomatedTests/
---
Automatic tests
===============
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic
tests of Qubes OS. Regardless of the name, we use it for both [unit
tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration
tests](https://en.wikipedia.org/wiki/Integration_tests). The main purpose is of
course to deliver much more stable releases.
Integration tests are written with assumption to be called on dedicated
hardware. **Do not run those test on machine where you have important data, you
can loose it**. Especially all the VMs with name starting with `test-` are
removed. All the tests are started from dom0, even when testing some VM
component. Those tests will create new VM(s), run the test, then remove the VM(s).
Most of the tests are stored in [core-admin
repository](https://github.com/QubesOS/qubes-core-admin/tree/master/tests) in
`tests` directory. To start them you can use standard python unittest runner:
python -m unittest -v qubes.tests
Or our custom one:
python -m qubes.tests.run -v
Our test runner can be used mostly the same as the standard one, with some nice
additional features like no need to prefix all the tests with "qubes.tests", or
color output. It is also the only way to run only selected template tests.
You can use `python -m qubes.tests.run -h` to get usage information:
[user@dom0 ~]$ python -m qubes.tests.run -h
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
[--do-not-clean] [--do-clean] [--loglevel LEVEL]
[--logfile FILE] [--syslog] [--no-syslog] [--kmsg] [--no-kmsg]
[TESTNAME [TESTNAME ...]]
positional arguments:
TESTNAME list of tests to run named like in description
(default: run all tests)
optional arguments:
-h, --help show this help message and exit
--verbose, -v increase console verbosity level
--quiet, -q decrease console verbosity level
--list, -l list all available tests and exit
--failfast, -f stop on the first fail, error or unexpected success
--no-failfast disable --failfast
--do-not-clean, --dnc, -D
do not execute tearDown on failed tests. Implies
--failfast.
--do-clean, -C do execute tearDown even on failed tests.
--loglevel LEVEL, -L LEVEL
logging level for file and syslog forwarding (one of:
NOTSET, DEBUG, INFO, WARN, WARNING, ERROR, CRITICAL;
default: DEBUG)
--logfile FILE, -o FILE
if set, test run will be also logged to file
--syslog reenable logging to syslog
--no-syslog disable logging to syslog
--kmsg, --very-brave-or-very-stupid
log most important things to kernel ring-buffer
--no-kmsg, --i-am-smarter-than-kay-sievers
do not abuse kernel ring-buffer
When running only specific tests, write their names like in log, in format:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
Example: basic/TC_00_Basic/test_000_create
For example to run only tests for fedora-21 template, you can use `-l` option, then filter the list:
[user@dom0 ~]$ python -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking
network/VmNetworking_fedora-21/test_010_simple_proxyvm
network/VmNetworking_fedora-21/test_020_simple_proxyvm_nm
network/VmNetworking_fedora-21/test_030_firewallvm_firewall
network/VmNetworking_fedora-21/test_040_inter_vm
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_000_start_shutdown
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_010_run_gui_app
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_050_qrexec_simple_eof
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_051_qrexec_simple_eof_reverse
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_052_qrexec_vm_service_eof
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_053_qrexec_vm_service_eof_reverse
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_060_qrexec_exit_code_dom0
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_065_qrexec_exit_code_vm
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_100_qrexec_filecopy
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_110_qrexec_filecopy_deny
vm_qrexec_gui/TC_00_AppVM_fedora-21/test_120_qrexec_filecopy_self
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_000_prepare_dvm
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_010_simple_dvm_run
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
[user@dom0 ~]$ python -m qubes.tests.run -v `python -m qubes.tests.run -l | grep fedora-21`
Example test run:
![snapshot-tests2.png](/attachment/wiki/developers/snapshot-tests2.png)
## Adding a new test to core-admin
After you added a new unit test to [core-admin/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/tests)
you have to make sure of two things:
1. The test will be added to the RPM file created by [QubesBuilder](/en/doc/qubes-builder/)
For this you need to edit [core-admin/tests/Makefile](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/Makefile)
2. The test will be loaded by [core-admin/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/tests/__init__.py)
### Editing the Makefile
Add at the bottom of the file the two lines which will copy your test and its
compiled version to the right directory in the RPM file. I.e. adding `example.py`
cp example.py $(DESTDIR)$(PYTHON_TESTSPATH)
cp example.py[co] $(DESTDIR)$(PYTHON_TESTSPATH)
### Editing \_\_init\_\_.py
Add at the bottom of the file in the method `def load_tests` to the variable
`modname` your test. I.e adding `example.py`.
~~~python
for modname in (
'qubes.tests.basic',
'qubes.tests.dom0_update',
'qubes.tests.network',
'qubes.tests.vm_qrexec_gui',
'qubes.tests.backup',
'qubes.tests.backupcompatibility',
'qubes.tests.regressions',
'qubes.tests.example', # This is our newly added test
):
~~~
[unittest]: https://docs.python.org/2/library/unittest.html

97
en/developers/debugging/Profiling.md Normal file
View file

@ -0,0 +1,97 @@
---
layout: doc
title: Profiling
permalink: /en/doc/profiling/
redirect_from:
- /doc/Profiling/
- /wiki/Profiling/
---
Profiling
=========
This is python profiling primer.
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
Requirements
------------
~~~
yum install gprof2dot graphviz
git clone http://git.woju.eu/qubes/profiling.git
~~~
If you profile something on dom0, move `Upload.sh` from repository to dom0:
~~~
mkdir -p ~/profiling
qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
~~~
- WARNING: this will obviously be running third party code which is not signed by ITL nor Fedora. You have been warned.
Workflow
--------
### Identify function responsible for some slow action
You have to select area in which you suspect less than optimal performance. If you do not narrow the area, graphs may be unreadable.
### Replace suspect function with probe
Replace
def foo(self, bar):
# function content
with
def foo(self, *args, **kwargs):
profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
def real_foo(self, bar):
# function content
### Run application
Beware that some functions may be called often. For example `qubesmanager/main.py:update_table` gets run once per second. This will produce one pstat file per second.
Remember to revert your changes to application afterwards.
### Upload statistics
If you are in dom0:
~~~
cd ~/profiling
./Upload.sh
~~~
### Analyse
~~~
make
~~~
For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG contains call graph. Text file contains list of all functions sorted by cumulative execution time. You may also try `make all-png`.
~~~
make index.html
~~~
This creates `index.html` with all SVG graphics linked to TXT files. Ready for upload.
~~~
make REMOTE=example.com:public_html/qubes/profiling/ upload
~~~
Example
-------
This example is from `qubes-manager` (`qubesmanager/main.py`).
!["update\_table-20140424-170010.svg"](//attachment/wiki/Profiling/update_table-20140424-170010.svg)
It is apparent than problem is around `get_disk_usage` which calls something via `subprocess.call`. It does it 15 times, probably once per VM.

155
en/developers/debugging/TestBench.md Normal file
View file

@ -0,0 +1,155 @@
---
layout: doc
title: TestBench
permalink: /en/doc/test-bench/
redirect_from:
- /doc/TestBench/
- /wiki/TestBench/
---
Test bench for Dom0
===================
This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal.
We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/en/doc/qubes-builder/) and you have it set up and running flawlessly.
Setting up the machine
----------------------
First, do a clean install from ISO you built or grabbed elsewhere.
You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else.
#!/bin/sh
# adjust this for your NIC (run lspci)
BDF=0000:02:00.0
prog=$(basename $0)
pciunbind() {
local path
path=/sys/bus/pci/devices/${1}/driver/unbind
if ! [ -w ${path} ]; then
echo "${prog}: Device ${1} not bound"
return 1
fi
echo -n ${1} >${path}
}
pcibind() {
local path
path=/sys/bus/pci/drivers/${2}/bind
if ! [ -w ${path} ]; then
echo "${prog}: Driver ${2} not found"
return 1
fi
echo ${1} >${path}
}
pciunbind ${BDF}
pcibind ${BDF} e1000e
dhclient
TODO: describe how to run this at every startup
Now configure your DHCP server so your testbench gets static IP and connect your machine to your local network. You should ensure that your testbench can reach the Internet.
Install `openssh-server` on your testbench:
~~~
yum install openssh-server
~~~
Ensure that sudo works without password from your user account (it should by default).
Development VM
--------------
### SSH
Arrange firewall so you can reach the testbench from your `qubes-dev` VM. Generate SSH key in `qubes-dev`:
~~~
ssh-keygen -t ecdsa -b 521
~~~
Add the following section in `.ssh/config` in `qubes-dev`:
~~~
Host testbench
# substitute username in testbench
User user
# substitute address of your testbench
HostName 192.168.123.45
~~~
Then connect to your testbench and paste newly generated `id_ecdsa.pub` to `.ssh/authorized_keys` on testbench so you can log in without entering password every time.
### Scripting
This step is optional, but very helpful. Put these scripts somewhere in your `${PATH}`, like `/usr/local/bin`.
`qtb-runtests`:
#!/bin/sh
ssh testbench python -m qubes.tests.run
`qtb-install`:
#!/bin/sh
TMPDIR=/tmp/qtb-rpms
if [ $# -eq 0 ]; then
echo "usage: $(basename $0) <rpmfile> ..."
exit 2
fi
set -e
ssh testbench mkdir -p "${TMPDIR}"
scp "${@}" testbench:"${TMPDIR}"
while [ $# -gt 0 ]; do
ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"
shift
done
`qtb-iterate`:
#!/bin/sh
set -e
# substitute path to your builder installation
pushd ${HOME}/builder >/dev/null
# the following are needed only if you have sources outside builder
#rm -rf qubes-src/core-admin
#make COMPONENTS=core-admin get-sources
make core-admin
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
qtb-runtests
### Hooking git
I (woju) have those two git hooks. They ensure tests are passing (or are marked as expected failure) when commiting and pushing. For committing it is only possible to run tests that may be executed from git repo (even if the rest were available, I probably wouldn't want to do that). For pushing, I also install RPM and run tests on testbench.
`core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability)
#!/bin/sh
set -e
python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
`core-admin/.git/hooks/pre-push`:
#!/bin/sh
exec qtb-iterate

128
en/developers/debugging/VmInterface.md Normal file
View file

@ -0,0 +1,128 @@
---
layout: doc
title: VMInterface
permalink: /en/doc/vm-interface/
redirect_from:
- /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](/en/doc/qfilecopy/)
- `qubes.OpenInVM` - open a file in called VM. Service receives a single file on stdin (in
[qfile format](/en/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](/en/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](/en/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.

212
en/developers/debugging/WindowsDebugging.md Normal file
View file

@ -0,0 +1,212 @@
---
layout: doc
title: WindowsDebugging
permalink: /en/doc/windows-debugging/
redirect_from:
- /doc/WindowsDebugging/
- /wiki/WindowsDebugging/
---
Debugging Windows HVMs
======================
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
#!/bin/sh
id1=$(xl domid "$1-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
echo $tty1
Pass it a running VM name and it will output the corresponding pty name.
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
#!/bin/sh
id1=$(xl domid "$1-dm")
id2=$(xl domid "$2-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
socat $tty1,raw $tty2,raw
...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- Reboot the *target* VM.
- Run the above shell script in dom0.
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
~~~
Opened \\.\com1
Waiting to reconnect...
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
Kernel Debugger connection established.
Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
Executable search path is:
... Retry sending the same data packet for 64 times.
The transport connection between host kernel debugger and target Windows seems lost.
please try resync with target, recycle the host debugger, or reboot the target Windows.
Unable to read KTHREAD address fffff8000281ccc0
**************************************************************************
Unable to read debugger data block header
**************************************************************************
Unable to read KTHREAD address fffff8000281ccc0
Unable to read PsLoadedModuleList
Unable to read KTHREAD address fffff8000281ccc0
**************************************************************************
Unable to read debugger data block header
**************************************************************************
~~~
...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
#include <errno.h>
#include <stdio.h>
#include <fcntl.h>
#include <termios.h>
int fd1, fd2;
char mark = ' ';
void out(unsigned char c)
{
static int count = 0;
static unsigned char buf[17] = {0};
// relay to ouptput port
write(fd2, &c, 1);
fprintf(stderr, "%c", mark);
/* dump all data going over the line
if (count == 0)
fprintf(stderr, "%c", mark);
fprintf(stderr, "%02x ", c);
if (c >= 0x20 && c < 0x80)
buf[count] = c;
else
buf[count] = '.';
count++;
if (count == 0x10)
{
count = 0;
fprintf(stderr, " %s\n", buf);
}
*/
}
int main(int argc, char* argv[])
{
unsigned char c = 0;
struct termios tio;
ssize_t size;
if (argc < 3)
{
fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
return EINVAL;
}
fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
if (fd1 <= 0)
{
perror("open fd1");
return errno;
}
fd2 = open(argv[2], O_WRONLY | O_NOCTTY);
if (fd2 <= 0)
{
perror("open fd2");
return errno;
}
/*
// This doesn't make any difference which supports the theory
// that it's Xen who corrupts the byte stream.
cfmakeraw(&tio);
if (tcsetattr(fd1, TCSANOW, &tio) < 0)
{
perror("tcsetattr 1");
return errno;
}
if (tcsetattr(fd2, TCSANOW, &tio) < 0)
{
perror("tcsetattr 2");
return errno;
}
*/
if (argc == 4)
mark = argv[3][0];
while (1)
{
size = read(fd1, &c, 1);
if (size <= 0)
break;
parse:
if (c == 0x0d)
{
size = read(fd1, &c, 1);
if (size <= 0)
{
out(0x0d);
break;
}
if (c == 0x0a)
{
out(0x0a);
}
else
{
out(0x0d);
goto parse;
}
}
else
out(c);
}
close(fd1);
close(fd2);
return 0;
}
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
>
> #!/bin/sh
>
> id1=$(xl domid "$1-dm")
> id2=$(xl domid "$2-dm")
> tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
> tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
> ./ptycrlf ${tty1} ${tty2} - &
> ./ptycrlf ${tty2} ${tty1} + &
> With this everything should be good:
>
> ~~~
> Opened \\.\com1
> Waiting to reconnect...
> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
> Kernel Debugger connection established.
> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
> Executable search path is:
> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
> Machine Name:
> Kernel base = 0xfffff800`0261a000 PsLoadedModuleList = 0xfffff800`0285d6d0
> System Uptime: not available
> ~~~
Happy debugging!

58
en/developers/doc-guidelines.md Normal file
View file

@ -0,0 +1,58 @@
---
layout: doc
title: Documentation Guidelines
permalink: /en/doc/doc-guidelines/
redirect_from:
- /doc/doc-guidelines/
- "/wiki/DocStyle/"
- "/doc/DocStyle/"
---
Guidelines for Documentation Contributors
=========================================
All Qubes OS documentation pages are stored as plain text files in the
dedicated [qubes-doc] repository. By cloning and regularly pulling from
this repo, users can maintain their own up-to-date offline copy of all Qubes
documentation rather than relying solely on the Web. Contributions to the
documentation (both new content and edits of existing content) are welcome. To
contribute, please [fork and clone][gh-fork] this repo, make your changes,
then either [submit a pull request][gh-pull] or [send a patch][patch] to the
`qubes-devel` [mailing list][lists]. If you have a GitHub account (free), you
can simply browse the [qubes-doc] repository and edit the files there. The
GitHub interface will automatically guide you through the
[fork and pull request creation process][gh-fork].
Markdown Conventions
--------------------
All the documentation is written in Markdown for maximum accessibility. When
making contributions, please observe the following style conventions:
* Use spaces instead of tabs.
* Hard wrap Markdown lines at 80 characters.
* Hard wrap Git commit message lines at 72 characters.
* This leaves exactly four spaces on each side of the commit message when
viewed in the default `git log` format.)
* If appropriate, make numerals in numbered lists match between Markdown
source and HTML output.
* 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]: http://daringfireball.net/projects/markdown/syntax#link`
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[qubes]: https://github.com/QubesOS
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[patch]: /doc/SourceCode/#sending-a-patch
[lists]: https://www.qubes-os.org/doc/QubesLists/

255
en/developers/fundamentals/GuiDocs.md Normal file
View file

@ -0,0 +1,255 @@
---
layout: doc
title: GUIdocs
permalink: /en/doc/gui-docs/
redirect_from:
- /doc/GUIdocs/
- /wiki/GUIdocs/
---
Qubes GUI protocol
==================
qubes\_gui and qubes\_guid processes
------------------------------------
All AppVM X applications connect to local (running in AppVM) Xorg server, that uses the following "hardware" drivers:
- *dummy\_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
- *qubes\_drv* - it provides a virtual keyboard and mouse (in fact, more, see below)
For each AppVM, there is a pair of *qubes\_gui* (running in AppVM) and *qubes\_guid* (running in dom0) processes, connected over vchan. Main responsibilities of *qubes\_gui* are:
- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer
- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0
- receive information about keyboard and mouse events from dom0, tell *qubes\_drv* to fake appropriate events
- receive information about window size/position change, apply them to the local window
Main responsibilities of *qubes\_guid* are:
- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes\_gui*
- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data)
- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
- receive information about window size/position change, apply them to the local window
Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus. AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only), nor synthetize and pass events to other AppVMs.
Window content updates implementation
-------------------------------------
Typical remote desktop applications, like *vnc*, pass the information on all changed window content in-band (say, over tcp). As the channel has limited throughput, this impacts video performance. In case of Qubes, *qubes\_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes\_gui*
- asks *qubes\_drv* driver for the list of physical memory frames that hold the composition buffer of a window
- pass this information via `MFNDUMP` message to *qubes\_guid* in dom0
Now, *qubes\_guid* has to tell dom0 Xorg server about the location of the buffer. There is no supported way (e.g. Xorg extension) to do this zero-copy style. The following method is used in Qubes:
- in dom0, the Xorg server is started with *LD\_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory.
- *qubes\_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension
- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc\_map\_foreign\_range*
- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this.
The important detail is that *xc\_map\_foreign\_range* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes\_guid*). Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message.
To sum up, this solution has the following benefits:
- window updates at DRAM speed
- no changes to Xorg code
- minimal size of the supporting code
![gui.png](/attachment/wiki/GUIdocs/gui.png)
Security markers on dom0 windows
--------------------------------
It is important that user knows which AppVM a given window belongs to. This prevents an attack when a rogue AppVM paints a window pretending to belong to other AppVM or dom0, and tries to steal e.g. passwords.
In Qubes, the custom window decorator is used, that paints a colourful frame (the colour is determined during AppVM creation) around decorated windows. Additionally, window title always starts with **[name of the AppVM]**. If a window has a *override\_redirect* attribute, meaning that it should not be treated by a window manager (typical case is menu windows), *qubes\_guid* draws a two-pixel colourful frame around it manually.
Clipboard sharing implementation
--------------------------------
Certainly, it would be insecure to allow AppVM to read/write clipboard of other AppVMs unconditionally. Therefore, the following mechanism is used:
- there is a "qubes clipboard" in dom0 - its contents is stored in a regular file in dom0.
- if user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD\_DATA* message followed by clipboard contents.
- user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes\_gui* copies data to the the local clipboard, and then user can paste its contents to local applications normally.
This way, user can quickly copy clipboards between AppVMs. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM.
*qubes\_gui* and *qubes\_guid* code notes
-----------------------------------------
Both applications are structures similarly. They use *select* function to wait for any of the two event sources
- messages from the local X server
- messages from the vchan connecting to the remote party
The XEvents are handled by *handle\_xevent\_eventname* function, messages are handled by *handle\_messagename* function. One should be very careful when altering the actual *select* loop - e.g. both XEvents and vchan messages are buffered, meaning that *select* will not wake for each message.
If one changes the number/order/signature of messages, one should increase the *QUBES\_GUID\_PROTOCOL\_VERSION* constant in *messages.h* include file.
*qubes\_guid* writes debugging information to */var/log/qubes/qubes.domain\_id.log* file; *qubes\_gui* writes debugging information to */var/log/qubes/gui\_agent.log*. Include these files when reporting a bug.
AppVM -\> dom0 messages
-----------------------
Proper handling of the below messages is security-critical. Observe that beside two messages (`CLIPBOARD` and `MFNDUMP`) the rest have fixed size, so the parsing code can be small.
The *override\_redirect* window attribute is explained at [Override Redirect Flag](http://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The *transient\_for* attribute is explained at [Transient\_for attribute](http://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR).
Window manager hints and flags are described at [http://standards.freedesktop.org/wm-spec/latest/](http://standards.freedesktop.org/wm-spec/latest/), especially part about `_NET_WM_STATE`.
Each message starts with the following header
~~~
struct msghdr {
uint32_t type;
uint32_t window;
/* This field is intended for use by gui_agents to skip unknown
* messages from the (trusted) guid. Guid, on the other hand,
* should never rely on this field to calculate the actual len of
* message to be read, as the (untrusted) agent can put here
* whatever it wants! */
uint32_t untrusted_len;
};
~~~
The header is followed by message-specific data.
|Message name|Structure after header|Action|
|:-----------|:---------------------|:-----|
|MSG\_CLIPBOARD\_DATA|amorphic blob (length determined by the "window" field)|Store the received clipboard content (not parsing in any way)|
|MSG\_CREATE|` struct msg_create { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t parent; `
` uint32_t override_redirect; `
` }; `|Create a window with given parameters|
|MSG\_DESTROY|None|Destroy a window|
|MSG\_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
` }; `|Map a window with given parameters|
|MSG\_UNMAP|None|Unmap a window|
|MSG\_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
` }; `|Change window position/size/type|
|MSG\_MFNDUMP|` struct shm_cmd { `
` uint32_t shmid; `
` uint32_t width; `
` uint32_t height; `
` uint32_t bpp; `
` uint32_t off; `
` uint32_t num_mfn; `
` uint32_t domid; `
` uint32_t mfns[0]; `
` }; `|Retrieve the array of mfns that constitute the composition buffer of a remote window.
The "num\_mfn" 32bit integers follow the shm\_cmd structure; "off" is the offset of the composite buffer start in the first frame; "shmid" and "domid" parameters are just placeholders (to be filled by *qubes\_guid*), so that we can use the same structure when talking to *shmoverride.so*|
|MSG\_SHMIMAGE|` struct msg_shmimage { `
` uint32_t x; `
` uint32_t y;`
` uint32_t width;`
` uint32_t height;`
` }; `|Repaint the given window fragment|
|MSG\_WMNAME|` struct msg_wmname { `
` char data[128]; `
` } ; `|Set the window name; only printable characters are allowed|
|MSG\_DOCK|None|Dock the window in the tray|
|MSG\_WINDOW\_HINTS|` struct msg_window_hints { `
` uint32_t flags; `
` uint32_t min_width; `
` uint32_t min_height; `
` uint32_t max_width; `
` uint32_t max_height; `
` uint32_t width_inc; `
` uint32_t height_inc; `
` uint32_t base_width; `
` uint32_t base_height; `
` }; `|Size hints for window manager|
|MSG\_WINDOW\_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
` }; `|Change window state request; fields contains bitmask which flags request to be set and which unset|
Dom0 -\> AppVM messages
-----------------------
Proper handling of the below messages is NOT security-critical.
Each message starts with the following header
~~~
struct msghdr {
uint32_t type;
uint32_t window;
};
~~~
The header is followed by message-specific data.
` KEYPRESS, BUTTON, MOTION, FOCUS ` messages pass information extracted from dom0 XEvent; see appropriate event documentation.
|Message name|Structure after header|Action|
|:-----------|:---------------------|:-----|
|MSG\_KEYPRESS|` struct msg_keypress { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t keycode; `
` }; `|Tell *qubes\_drv* driver to generate a keypress|
|MSG\_BUTTON|` struct msg_button { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t button; `
` }; `|Tell *qubes\_drv* driver to generate mouseclick|
|MSG\_MOTION|` struct msg_motion { `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t is_hint; `
` }; `|Tell *qubes\_drv* driver to generate motion event|
|MSG\_CONFIGURE|` struct msg_configure { `
` uint32_t x; `
` uint32_t y; `
` uint32_t width; `
` uint32_t height; `
` uint32_t override_redirect; `
` }; `|Change window position/size/type|
|MSG\_MAP|` struct msg_map_info { `
` uint32_t transient_for; `
` uint32_t override_redirect; `
` }; `|Map a window with given parameters|
|MSG\_CLOSE|None|send wmDeleteMessage to the window|
|MSG\_CROSSING|` struct msg_crossing { `
` uint32_t type; `
` uint32_t x; `
` uint32_t y; `
` uint32_t state; `
` uint32_t mode; `
` uint32_t detail; `
` uint32_t focus; `
` }; `|Notify window about enter/leave event|
|MSG\_FOCUS|` struct msg_focus { `
` uint32_t type; `
` uint32_t mode; `
` uint32_t detail; `
` }; `|Raise a window, XSetInputFocus|
|MSG\_CLIPBOARD\_REQ|None|Retrieve the local clipboard, pass contents to gui-daemon|
|MSG\_CLIPBOARD\_DATA|amorphic blob|Insert the received data into local clipboard|
|MSG\_EXECUTE|Obsolete|Obsolete, unused|
|MSG\_KEYMAP\_NOTIFY|` unsigned char remote_keys[32]; `|Synchronize the keyboard state (key pressed/released) with dom0|
|MSG\_WINDOW\_FLAGS|` struct msg_window_flags { `
` uint32_t flags_set; `
` uint32_t flags_unset;`
` }; `|Window state change confirmation|

34
en/developers/fundamentals/QubesArchitecture.md Normal file
View file

@ -0,0 +1,34 @@
---
layout: doc
title: QubesArchitecture
permalink: /en/doc/qubes-architecture/
redirect_from:
- /doc/QubesArchitecture/
- /wiki/QubesArchitecture/
---
Qubes Architecture Overview
===========================
Qubes implements a Security by Isolation approach. To do this, Qubes utilizes virtualization technology in order to isolate various programs from each other and even to sandbox many system-level components, such as networking and storage subsystems, so that the compromise of any of these programs or components does not affect the integrity of the rest of the system.
Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course.
[![qubes-arch-diagram-1.png](/attachment/wiki/QubesArchitecture/qubes-arch-diagram-1.png)](/attachment/wiki/QubesArchitecture/qubes-arch-diagram-1.png)
(Note: In the diagram above, "Storage domain" is actually a USB domain.)
Key Architecture features
-------------------------
- Based on a secure bare-metal hypervisor (Xen)
- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d)
- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
- No networking code in the privileged domain (dom0)
- All user applications run in “AppVMs,” lightweight VMs based on Linux
- Centralized updates of all AppVMs based on the same template
- Qubes GUI virtualization presents applications as if they were running locally
- Qubes GUI provides isolation between apps sharing the same desktop
- Secure system boot based (optional)
[Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) (The original 2009 document that started this all...)

57
en/developers/fundamentals/QubesNet.md Normal file
View file

@ -0,0 +1,57 @@
---
layout: doc
title: QubesNet
permalink: /en/doc/qubes-net/
redirect_from:
- /doc/QubesNet/
- /wiki/QubesNet/
---
VM network in Qubes
===================
Overall description
-------------------
In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used.
The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via xenstore to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs.
Routing tables examples
-----------------------
VM routing table is simple:
||
|Destination|Gateway|Genmask|Flags|Metric|Ref|Use|Iface|
|0.0.0.0|0.0.0.0|0.0.0.0|U|0|0|0|eth0|
Network driver domain routing table is a bit longer:
||
|Destination|Gateway|Genmask|Flags|Metric|Ref|Use|Iface|
|10.2.0.16|0.0.0.0|255.255.255.255|UH|0|0|0|vif4.0|
|10.2.0.7|0.0.0.0|255.255.255.255|UH|0|0|0|vif10.0|
|10.2.0.9|0.0.0.0|255.255.255.255|UH|0|0|0|vif9.0|
|10.2.0.8|0.0.0.0|255.255.255.255|UH|0|0|0|vif8.0|
|10.2.0.12|0.0.0.0|255.255.255.255|UH|0|0|0|vif3.0|
|192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0|
|0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0|
Location of the network driver domain
-------------------------------------
Traditionally, the network driver domain is dom0. This design means that a lot of code (networking stack, drivers) running in the all-powerful domain is exposed to potential attack. Although it is supported (one can execute *qvm-set-default-netvm dom0*), it is strongly discouraged.
Instead, a dedicated domain called `netvm` should be used. In order to activate it, one needs to install the `qubes-servicevm-netvm` rpm package, and enable it via command *qvm-set-default-netvm netvm*. This domain will be assigned all PCI devices that are network cards. One can interact with the *Networkmanager* daemon running in `netvm` in the same way as with any other VM GUI application (with one detail that *nm-applet* requires a system tray, thus one needs to start it via "KDEMenu-\>Applications-\>Netvm-\>Show Tray").
Note that in order to isolate `netvm` properly, the platform must support VTd and it must be activated. Otherwise, compromised `netvm` can use DMA to get control over dom0 and even the hypervisor.
When using `netvm`, there is no network connectivity in dom0. This is the desired configuration - it eliminates all network-bourne attacks. Observe that dom0 is meant to be used for administrative tasks only, and (with one exception) they do not need network. Anything not related to system administration should be done in one of AppVMs.
The above-mentioned exception is the system packages upgrade. Again, one must not install random applications in dom0, but there is a need to e.g. upgrade existing packages. While one may argue that the new packages could be downloaded on a separate machine and copied to dom0 via a pendrive, this solution has its own problems. Therefore, the advised method to temporarily grant network connectivity to dom0 is to use *qvm-dom0-network-via-netvm up* command. It will pause all running VMs (so that they can do no harm to dom0) and connect dom0 to netvm network just like another AppVM. Having completed package upgrade, execute *qvm-dom0-network-via-netvm down* to revert to the normal state.
Firewall and Proxy VMs
----------------------
TODO

57
en/developers/fundamentals/SecurityCriticalCode.md Normal file
View file

@ -0,0 +1,57 @@
---
layout: doc
title: SecurityCriticalCode
permalink: /en/doc/security-critical-code/
redirect_from:
- /doc/SecurityCriticalCode/
- /wiki/SecurityCriticalCode/
- /trac/wiki/SecurityCriticalCode/
---
Security-Critical Code in Qubes OS
==================================
Below is a list of security-critical (AKA trusted) code in Qubes OS. A successful attack against any of those might allow to compromise the Qubes OS security. This code can be thought of as of a Trusted Computing Base (TCB) of Qubes OS. The goal of the project has been to minimize the amount of this trusted code to an absolute minimum. The size of the current TCB is of an order of hundreds thousands of lines of C code, which is several orders of magnitude less than in other OSes, such as Windows, Linux or Mac, where it is of orders of tens of millions of lines of C code.
For more information about the security goals of Qubes OS, see [this page](/en/doc/security-goals/).
Security-Critical Qubes-Specific Components
-------------------------------------------
Below is a code produced by the Qubes project that is security-critical.
- Dom0-side of the libvchan library
- Dom0-side of the GUI virtualization code (*qubes-guid*)
- Dom0-side of the sound virtualization code (*pacat-simple-vchan*)
- Dom0-side in qrexec-related code (*qrexec\_daemon*)
- VM memory manager (*qmemman*) that runs in Dom0
- select Qubes RPC servers that run in Dom0: qubes.ReceiveUpdates and qubes.SyncAppMenus
- The qubes.Filecopy RPC server that runs in a VM -- this one is critical because it might allow one VM to compromise another one if user allows file copy operation to be performed between them
Security-Critical 3rd-Party Components
--------------------------------------
These are the components that we haven't written or designed ourselves, yet we still rely on them. At the current project stage, we cannot afford to spend time to thoroughly review and audit them, so we just more or less "blindly" trust they are secure.
- Xen hypervisor
- The Xen's xenstore backend running in Dom0
- The Xen's block backend running in Dom0 kernel
- The rpm program used in Dom0 for verifying Dom0 updates' signatures
- Somehow optional: log viewing software in dom0 that parses VM-influenced logs
Additionally when we consider attacks that originate through a compromised network domain and target the VMs connected to it. Those attacks do not apply to domains connected to other network domains (Qubes allows more than one network domains), or those with networking disabled (Dom0 is not connected to any network by default).
- Xen network PV frontends
- VM's core networking stacks (core TCP/IP code)
Buggy Code vs. Back-doored Code Distinction
-------------------------------------------
There is an important distinction between the buggy code and maliciously trojaned code. We could have the most secure architecture and the most bulletproof TCB that perfectly isolates all domains from each other, but it still would be pretty useless if all the code used within domains, e.g. the actual email clients, word processors, etc, was somehow trojaned. In that case only network-isolated domains could be somehow trusted, while all others could be not.
The above means that we must trust at least some of the vendors (not all, of course, but at least those few that provide the apps that we use in the most critical domains). In practice in Qubes OS we trust the software provided by Fedora project. This software is signed by Fedora distribution keys and so it is also critical that the tools used in domains for software updates (yum and rpm) be trusted.
Cooperative Covert Channels Between Domains
-------------------------------------------
Qubes does not attempt to eliminate all possible *cooperative* covert channels between domains, i.e. such channels that could be established between two *compromised* domains. We don't believe this is possible to achieve on x86 hardware, and we also doubt it makes any sense in practice for most users -- after all if the two domains are compromised, then it's already (almost) all lost anyway.

110
en/developers/fundamentals/TemplateImplementation.md Normal file
View file

@ -0,0 +1,110 @@
---
layout: doc
title: TemplateImplementation
permalink: /en/doc/template-implementation/
redirect_from:
- /doc/TemplateImplementation/
- /wiki/TemplateImplementation/
---
Overview of VM block devices
============================
Every VM has 4 block devices connected:
- **xvda** – base root device (/) – details described below
- **xvdb** – private.img – place where VM always can write.
- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware
private.img (xvdb)
------------------
This is mounted as /rw and here is placed all VM private data. This includes:
- */home* – which is bind mounted to /rw/home
- */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
modules.img (xvdd)
------------------
As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
- *vmlinuz* – actual kernel
- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules
- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware)
Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
Qubes TemplateVM implementation
===============================
TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
- root.img can be modified while there are AppVMs running – without corrupting the filesystem
- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
There are two layers of the device-mapper snapshot device; the first one enables modifying root.img without stopping the AppVMs and the second one, which is contained in the AppVM, enables temporal modifications to its filesystem. These modifications will be discarded after a restart of the AppVM.
![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png)
Snapshot device in Dom0
-----------------------
This device consists of:
- root.img – real template filesystem
- root-cow.img – differences between the device as seen by AppVM and the current root.img
The above is achieved through creating device-mapper snapshots for each version of root.img. When an AppVM is started, a xen hotplug script (/etc/xen/scripts/block-snapshot) reads the inode numbers of root.img and root-cow.img; these numbers are used as the snapshot device's name. When a device with the same name exists the new AppVM will use it – therefore, AppVMs based on the same version of root.img will use the same device. Of course, the device-mapper cannot use the files directly – it must be connected through /dev/loop\*. The same mechanism detects if there is a loop device associated with a file determined by the device and inode numbers – or if creating a new loop device is necessary.
When an AppVM is stopped the xen hotplug script checks whether the device is still in use – if it is not, the script removes the snapshot and frees the loop device.
### Changes to template filesystem
In order for the full potential of the snapshot device to be realized, every change in root.img must save the original version of the modified block in root-cow.img. This is achieved by a snapshot-origin device.
When TemplateVM is started, it receives the snapshot-origin device connected as a root device (in read-write mode). Therefore, every change to this device is immediately saved in root.img – but remains invisible to the AppVM, which uses the snapshot.
When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.old and creates a new one (using the `qvm-template-commit` tool). The snapshot device will remain untouched due to the loop device, which uses an actual file on the disk (by inode, not by name). Linux kernel frees the old root-cow.img files as soon as they are unused by all snapshot devices (to be exact, loop devices). The new root-cow.img file will get a new inode number, and so new AppVMs will get new snapshot devices (with different names).
### Rollback template changes
There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch".
This is done using snapshot-merge device-mapper target (available from 2.6.34 kernel). It requires that no other snapshot device uses underlying block devices (root.img, root-cow.img via loop device). Because of this all AppVMs based on this template must be halted during this operation.
Steps performed by **qvm-revert-template-changes**:
1. Ensure that no other VMs uses this template.
2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
5. Replace *snapshot-merge* d-m target back to *snapshot*.
6. Cleanup snapshot device (if nobody uses it it the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
Snapshot device in AppVM
------------------------
Root device is exposed to AppVM in read-only mode. AppVM can write only in:
- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended
- volatile.img – temporary storage, which is discarded after an AppVM restart
volatile.img is divided into two partitions:
1. changes to root device
2. swap partition
Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
StandaloneVM
------------
Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.
It is implemented just like TemplateVM (has own root.img connected as R/W device), but no other VMs can be based on it.

30
en/developers/license.md Normal file
View file

@ -0,0 +1,30 @@
---
layout: doc
title: License
permalink: /en/doc/license/
redirect_from:
- /doc/license/
- "/doc/QubesLicensing/"
- "/wiki/QubesLicensing/"
---
Qubes OS License
================
Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
The full text of the GPL v2 license can be found [here](http://www.gnu.org/licenses/gpl-2.0.html).
Parts of the Qubes OS under proprietary license
-----------------------------------------------
Some software produced by the Qubes Project is proprietary software of Invisible Things Lab. Those parts are not distributed as part of the Qubes OS installation ISOs, but can be downloaded separately.
The following software is licensed under a proprietary license:
- Qubes Windows Support Tools
Note on rights to double-licensing of the Qubes code
----------------------------------------------------
Invisible Things Lab (ITL), who has funded and run the Qubes project since the beginning, and who has contributed majority of Qubes-specific code (specifically: `core-*`, `gui-*`, and `qubes-*` repositories) would like to have a right to redistribute parts of this code under proprietary licenses. This is especially important for Qubes R3 and later, where the new architecture allows the creation of many editions of Qubes, using different hypervisors, some of which might not be open source. That's why we ask every developer who contributes code to Qubes project to grant ITL permission to reuse the code under a different license, and to express this consent by including the [standard signed-off line](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=HEAD#n358) in the commit.

81
en/developers/reporting-bugs.md Normal file
View file

@ -0,0 +1,81 @@
---
layout: doc
title: Reporting Bugs
permalink: /en/doc/reporting-bugs/
redirect_from:
- /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)

49
en/developers/services/Dom0SecureUpdates.md Normal file
View file

@ -0,0 +1,49 @@
---
layout: doc
title: Dom0SecureUpdates
permalink: /en/doc/dom0-secure-updates/
redirect_from:
- /doc/Dom0SecureUpdates/
- /wiki/Dom0SecureUpdates/
---
Qubes Dom0 secure update procedure
==================================
Reasons for Dom0 updates
------------------------
Normally there should be few reasons for updating software in Dom0. This is because there is no networking in Dom0, which means that even if some bugs will be discovered e.g. in the Dom0 Desktop Manager, this really is not a problem for Qubes, because all the 3rd party software running in Dom0 is not accessible from VMs or network in any way. Some exceptions to the above include: Qubes GUI daemon, Xen store daemon, and disk back-ends (we plan move the disk backends to untrusted domain in Qubes 2.0). Of course we believe this software is reasonably secure and we hope it will not need patching.
However, we anticipate some other situations when updating Dom0 software might be required:
- Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool)
Problems with traditional network-based update mechanisms
---------------------------------------------------------
Dom0 is the most trusted domain on Qubes OS, and for this reason we decided to design Qubes in such a way that Dom0 is not connected to any network. In fact only select domains can be connected to a network via so called network domains. There could also be more than one network domain, e.g. in case the user is connected to more than one physically or logically separated networks.
Secure update mechanism we use in Qubes (starting from Beta 2
-------------------------------------------------------------
Keeping Dom0 not connected to any network makes it hard, however, to provide updates for software in Dom0. For this reason we have come up with the following mechanism for Dom0 updates, which minimizes the amount of untrusted input processed by Dom0 software:
The update process is initiated by [qvm-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qvm-dom0-update). Note that we assume that this script might get compromised and might download a maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qvm-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input.
Once qubes-receive-updates finished unpacking and verifying the updates, the updates are placed in ``qubes-receive-updates`` directory in Dom0 filesystem. Those updates are now trusted. Dom0 is configured (see /etc/yum.conf in Dom0) to use this directory as a default (and only) [yum repository](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-cached.repo).
Finally, qvm-dom0-updates runs ``yum update`` that fetches the rpms from qubes-cached repo and installs them as usual.
Security benefit of our update mechanism
----------------------------------------
The benefit of the above scheme is that one doesn't need to trust the TCP/IP stack, the HTTP stack, and wget implementation in order to safely deliver and install updates in Dom0. One only needs to trust a few hundred lines of code as discussed above, as well as the rpm utility for properly checking digital signature (but this is required in any update scheme).

55
en/developers/services/DvmImpl.md Normal file
View file

@ -0,0 +1,55 @@
---
layout: doc
title: DVMimpl
permalink: /en/doc/dvm-impl/
redirect_from:
- /doc/DVMimpl/
- /wiki/DVMimpl/
---
DisposableVM implementation in Qubes
====================================
DisposableVM image preparation
------------------------------
DisposableVM is not started like other VMs, by executing equivalent of *xl create* - it would be too slow. Instead, DisposableVM are started by restore from a savefile.
Preparing a savefile is done by */usr/lib/qubes/qubes\_prepare\_saved\_domain.sh* script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to "prerun" script. The script executes the following steps:
1. APPVM is started by *qvm-start*
2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created
3. if prerun script was specified, copy it to `qubes_save_script` xenstore key
4. wait for the `qubes_used_mem` key to appear
5. (in APPVM) APPVM boots normally, up to the point in */etc/init.d/qubes\_core* script when the presence of `qubes_save_request` key is tested. If it exists, then
1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key
3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear
6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
7. APPVM private image is detached
8. the domain is saved via *xl save*
9. the COW file volatile.img (cow for for root fs and swap) is packed to `saved_cows.tar` archive
*qubes\_prepare\_saved\_domain.sh* script is somehow lowlevel. It is usually called by *qvm-create-default-dvm* script, that takes care of creating a special AppVM (named template\_name-dvm) to be passed to *qubes\_prepare\_saved\_domain.sh*, as well as copying the savefile to /dev/shm (the latter action is not done if the `/var/lib/qubes/dvmdata/dont_use_shm` file exists).
Restoring a DisposableVM from the savefile
------------------------------------------
Normally, disposable VM is created when qubes rpc request with target *\$dispvm* is received. Then, as a part of rpc connection setup, the *qfile-daemon-dvm* program is executed; it executes */usr/lib/qubes/qubes\_restore* program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are:
1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
2. restore the COW files from the `saved_cows.tar`
3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the */etc/xen/scripts/block* script to bypass some redundant checks and execute as fast as possible.
4. execute "xl restore" in order to restore a domain.
5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`)
6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue.
The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.
Validating the DisposableVM savefile
------------------------------------
DisposableVM savefile contains references to template rootfs and to COW files. The COW files are restored before each DisposableVM start, so they cannot change. On the other hand, if templateVM is started, the template rootfs will change, and it may not be coherent with the COW files.
Therefore, the check for template rootfs modification time being older than DisposableVM savefile modification time is required. It is done in *qfilexchgd* daemon, just before restoring DisposableVM. If necassary, an attempt is made to recreate the DisposableVM savefile, using the last template used (or default template, if run for the first time) and the default prerun script, residing at */var/lib/qubes/vm-templates/templatename/dispvm\_prerun.sh*. Unfortunately, the prerun script takes a lot of time to execute - therefore, after template rootfs modification, the next DisposableVM creation can be longer by about 2.5 minutes.

29
en/developers/services/Qfilecopy.md Normal file
View file

@ -0,0 +1,29 @@
---
layout: doc
title: Qfilecopy
permalink: /en/doc/qfilecopy/
redirect_from:
- /doc/Qfilecopy/
- /wiki/Qfilecopy/
---
InterVM file copy design
========================
There are two cases when we need a mechanism to copy files between VMs:
- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a Disposable VM, edited by user, and possibly a modified file copied back from DispVM to VM.
Prior to Qubes Beta1, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.
This has the following disadvantages:
- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the abovementioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.
The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.
Being a rpc server, *qfile-unpacker* must be coded securely, as it processes potentially untrusted data format. Particularly, we do not want to use external tar or cpio and be prone to all vulnerabilities in them; we want a simplified, small utility, that handles only directory/file/symlink file type, permissions, mtime/atime, and assume user/user ownership. In the current implementation, the code that actually parses the data from srcVM has ca 100 lines of code and executes chrooted to the destination directory. The latter is hardcoded to `~user/incoming/srcVM`; because of chroot, there is no possibility to alter files outside of this directory.

56
en/developers/services/Qfileexchgd.md Normal file
View file

@ -0,0 +1,56 @@
---
layout: doc
title: Qfileexchgd
permalink: /en/doc/qfileexchgd/
redirect_from:
- /doc/Qfileexchgd/
- /wiki/Qfileexchgd/
---
**This mechanism is obsolete as of Qubes Beta 1!**
==================================================
Please see this [page](/en/doc/qfilecopy/) instead.
qfilexchgd, the Qubes file exchange daemon
==========================================
Overview
--------
*qfilexchgd* is a dom0 daemon responsible for managing exchange of block devices ("virtual pendrives") between VMs. It is used for
- copying files between AppVMs
- copying a single file between an AppVM and a DisposableVM
*qfilexchgd* is started after first *qubes\_guid* has been started, so that it has access to X display in dom0 to present dialog messages.
*qfilexchgd* is event driven. The sources of events are:
- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary
- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
Copying files between AppVMs
----------------------------
1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1.
2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it.
3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM.
4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates.
Copying a single file between AppVM and a DisposableVM
------------------------------------------------------
In order to minimize attack surface presented by necessity to process virtual pendrive metadata sent by (potentially compromised and malicious) DisposableVM, AppVM\<-\>DisposableVM file exchange protocol does not use any filesystem.
1. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm*
1. gets a new `/dev/xvdg` (just as described in previous paragraph)
2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents,
3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ`
4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents
5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key.
2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM.
3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself.
4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it.

76
en/developers/services/Qmemman.md Normal file
View file

@ -0,0 +1,76 @@
---
layout: doc
title: Qmemman
permalink: /en/doc/qmemman/
redirect_from:
- /doc/Qmemman/
- /wiki/Qmemman/
---
qmemman, Qubes memory manager
=============================
Rationale
---------
Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the optimal solution, as some VMs may require more memory than assigned initially, while others underutilize memory. Thus, there is a need for solution capable of shifting free memory from VM to another VM.
The [tmem](http://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon. All VMs report their memory usage (via xenstore) to *qmemman*, and it makes decisions on whether to balance memory across domains. The actual mechanism to add/remove memory from a domain (*xc.domain\_set\_target\_mem*) is already supported by both PV Linux guests and Windows guests (the latter via PV drivers).
Similarly, when there is need for Xen free memory (for instance, in order to create a new VM), traditionally the memory is obtained from dom0 only. When *qmemman* is running, it offers interface to obtain memory from all domains.
To sum up, *qmemman* pros and cons. Pros:
- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
- works well in practice, with less than 1% CPU consumption in the idle case
- simple, concise implementation
Cons:
- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
- *qmemman* is notified by a VM about memory usage change not more often than 10 times per seconds (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements
- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
Interface
---------
*qmemman* listens for the following events:
- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data
- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol.
- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed.
Algorithms basics
-----------------
The core VM property is `prefmem`. It denotes the amount of memory that should be enough for a domain to run efficiently in the nearest future. All *qmemman* algorithms will never shrink domain memory below `prefmem`. Currently, `prefmem` is simply 130% of current memory usage in a domain (without buffers and cache, but including swap). Naturally, `prefmem` is calculated by *qmemman* based on the information passed by *meminfo-writer*.
Whenever *meminfo-writer* running in domain A provides new data on memory usage to *qmemman*, the `prefmem` value for A is updated and the following balance algorithm (*qmemman\_algo.balance*) is triggered. Its output is the list of (domain\_id, new\_memory\_target\_to\_be\_set) pairs:
1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains
2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory
3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem`
2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem`
In order to avoid too frequent memory redistribution, it is actually executed only if one of the below conditions hold:
- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB)
- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it
Additionally, the balance algorithm is tuned so that XEN\_FREE\_MEM\_LEFT (50MB) is always left as Xen free memory, to make coherent memory allocations in driver domains work.
Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, the following algorithm (*qmemman\_algo.balloon*) is executed:
1. find all domains ("donors") whose actual memory is greater than its `prefmem`
2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If is is less than X, return error.
3. shrink donors, proportionally to their `prefmem`, so that X MB should become free
4. wait BALOON\_DELAY (0.1s)
5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).

164
en/developers/services/Qrexec.md Normal file
View file

@ -0,0 +1,164 @@
---
layout: doc
title: Qrexec
permalink: /en/doc/qrexec/
redirect_from:
- /doc/Qrexec/
- /wiki/Qrexec/
---
Command execution in VM (and Qubes RPC)
=======================================
Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM) services. It offers a mechanism to start programs in VMs, redirect their stdin/stdout, and a policy framework to control this all.
Basic Dom0-VM command execution
-------------------------------
During each domain creation a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM. They are connected over `vchan` channel.
Typically, the first thing that a `qrexec-client` instance does is to send a request to `qrexec-agent` to start a process in the VM. From then on, the stdin/stdout/stderr from this remote process will be passed to the `qrexec-client` process.
E.g., to start a primitive shell in a VM type the following in Dom0 console:
~~~
[user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d <vm name> user:bash
~~~
The string before first semicolon specifies what user to run the command as.
Adding `-e` on the `qrexec-client` command line results in mere command execution (no data passing), and `qrexec-client` exits immediately after sending the execution request.
There is also the `-l <local program>` flag, which directs `qrexec-client` to pass stdin/stdout of the remote program not to its stdin/stdout, but to the (spawned for this purpose) `<local program>`.
The `qvm-run` command is heavily based on `qrexec-client`. It also takes care of additional activities (e.g., starting the domain, if it is not up yet, and starting the GUI daemon). Thus, it is usually more convenient to use `qvm-run`.
There can be almost arbitrary number of `qrexec-client` processes for a domain (i.e., `qrexec-client` processes connected to the same `qrexec-daemon`); their data is multiplexed independently.
There is a similar command line utility avilable inside Linux AppVMs (note the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent sections.
Qubes Inter-VM Services (Qubes RPC)
-----------------------------------
Apart from simple Dom0-\>VM command executions, as discussed above, it is also useful to have more advanced infrastructure for controlled inter-VM RPC/services. This might be used for simple things like inter-VM file copy operations, as well as more complex tasks like starting a DispVM, and requesting it to do certain operations on a handed file(s).
Instead of implementing complex RPC-like mechanisms for inter-VM communication, Qubes takes a much simpler and pragmatic approach and aims to only provide simple *pipes* between the VMs, plus ability to request *pre-defined* programs (servers) to be started on the other end of such pipes, and a centralized policy (enforced by the `qrexec-policy` process running in dom0) which says which VMs can request what services from what VMs.
Thanks to the framework and automatic stdin/stdout redirection, RPC programs are very simple; both the client and server just use their stdin/stdout to pass data. The framework does all the inner work to connect these file descriptors to each other via `qrexec-daemon` and `qrexec-agent`. Additionally, DispVMs are tightly integrated; RPC to a DispVM is a simple matter of using a magic `$dispvm` keyword as the target VM name.
All services in Qubes are identified by a single string, which by convention takes a form of `qubes.ServiceName`. Each VM can provide handlers for each of the known services by providing a file in `/etc/qubes-rpc/` directory with the same name as the service it is supposed to handle. This file will then be executed by the qrexec service, if the dom0 policy allowed the service to be requested (see below). Typically, the files in `/etc/qubes-rpc/` contain just one line, which is a path to the specific binary that acts as a server for the incoming request, however they might also be the actual executable themselves. Qrexec framework is careful about connecting the stdin/stdout of the server process with the corresponding stdin/stdout of the requesting process in the requesting VM (see example Hello World service described below).
Qubes Services (RPC) policy
---------------------------
Besides each VM needing to provide explicit programs to serve each supported service, the inter-VM service RPC is also governed by a central policy in Dom0.
In dom0, there is a bunch of files in `/etc/qubes-rpc/policy/` directory, whose names describe the available RPC actions; their content is the RPC access policy database. Some example of the default services in Qubes are:
- qubes.Filecopy
- qubes.OpenInVM
- qubes.ReceiveUpdates
- qubes.SyncAppMenus
- qubes.VMShell
- qubes.ClipboardPaste
- qubes.Gpg
- qubes.NotifyUpdates
- qubes.PdfConvert
These files contain lines with the following format:
~~~
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
~~~
You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`, `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the `$anyvm` pattern; all other names do). Only `$anyvm` keyword makes sense in the `srcvm` field (service calls from dom0 are currently always allowed, `$dispvm` means "new VM created for this particular request" - so it is never a source of request). Currently, there is no way to specify source VM by type, but this is planned for Qubes R3.
Whenever a RPC request for service named "XYZ" is received, the first line in `/etc/qubes-rpc/policy/XYZ` that matches the actual `srcvm`/`destvm` is consulted to determine whether to allow RPC, what user account the program should run in target VM under, and what VM to redirect the execution to. If the policy file does not exits, user is prompted to create one *manually*; if still there is no policy file after prompting, the action is denied.
On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file name of the program that will be invoked.
Requesting VM-VM (and VM-Dom0) services execution
-------------------------------------------------
In a src VM, one should invoke the qrexec client via the following command:
~~~
/usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]`
~~~
Note that only stdin/stdout is passed between RPC server and client - notably, no cmdline argument are passed.
The source VM name can be accessed in the server process via QREXEC\_REMOTE\_DOMAIN environment variable. (Note the source VM has *no* control over the name provided in this variable--the name of the VM is provided by dom0, and so is trusted.)
By default, stderr of client and server is logged to respective `/var/log/qubes/qrexec.XID` files, in each of the VM.
Be very careful when coding and adding a new RPC service! Any vulnerability in a RPC server can be fatal to security of the target VM!
Requesting VM-VM (and VM-Dom0) services execution (without cmdline helper)
--------------------------------------------------------------------------
Connect directly to `/var/run/qubes/qrexec-agent-fdpass` socket as described [here](/doc/Qrexec2Implementation#Allthepiecestogetheratwork).
### Revoking "Yes to All" authorization
Qubes RPC policy supports an "ask" action, that will prompt the user whether a given RPC call should be allowed. It is set as default for services such as inter-VM file copy. A prompt window launches in dom0, that gives the user option to click "Yes to All", which allows the action and adds a new entry to the policy file, which will unconditionally allow further calls for given (service, srcVM, dstVM) tuple.
In order to remove such authorization, issue this command from a Dom0 terminal (example below for qubes.Filecopy service):
~~~
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
~~~
and then remove any line(s) ending in "allow" (before the first \#\# comment) which are the "Yes to All" results.
A user might also want to set their own policies in this section. This may mostly serve to prevent the user from mistakenly copying files or text from a trusted to untrusted domain, or vice-versa.
### Qubes RPC "Hello World" service
We will show the necessary files to create a simple RPC call that adds two integers on the target VM and returns back the result to the invoking VM.
- Client code on source VM (`/usr/bin/our_test_add_client`)
~~~
#!/bin/sh
echo $1 $2 # pass data to rpc server
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
~~~
- Server code on target VM (`/usr/bin/our_test_add_server`)
~~~
#!/bin/sh
read arg1 arg2 # read from stdin, which is received from the rpc client
echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
~~~
- Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`)
~~~
$anyvm $anyvm ask
~~~
- Server path definition on target VM (`/etc/qubes-rpc/test.Add`)
~~~
/usr/bin/our_test_add_server
~~~
- To test this service, run the following in the source VM:
~~~
/usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2
~~~
and we should get "3" as answer, provided dom0 policy allows the call to pass through, which would happen after we click "Yes" in the popup that should appear after the invocation of this command. If we changed the policy from "ask" to "allow", then no popup should be presented, and the call will always be allowed.
More high-level RPCs?
---------------------
As previously noted, Qubes aims to provide mechanisms that are very simple and thus with very small attack surface. This is the reason why the inter-VM RPC framework is very primitive and doesn't include any serialization or other function arguments passing, etc. We should remember, however, that users/app developers are always free to run more high-level RPC protocols on top of qrexec. Care should be taken, however, to consider potential attack surfaces that are exposed to untrusted or less trusted VMs in that case.
Qubes RPC internals
-------------------
The internal implementation of qrexec in Qubes R2 is described [here](/en/doc/qrexec2-implementation/), and in Qubes R3 [here](/en/doc/qrexec3-implementation/).

74
en/developers/services/Qrexec2Implementation.md Normal file
View file

@ -0,0 +1,74 @@
---
layout: doc
title: Qrexec2Implementation
permalink: /en/doc/qrexec2-implementation/
redirect_from:
- /doc/Qrexec2Implementation/
- /wiki/Qrexec2Implementation/
---
Implementation of qrexec in Qubes R2
====================================
This page describes implementation of the [qrexec framework](/en/doc/qrexec/) in Qubes OS R2. Note that the implementation has changed significantly in Qubes R3 (see [Qrexec3Implementation](/en/doc/qrexec3-implementation/)), although the user API reminded backwards compatible (i.e. qrexec apps written for Qubes R2 should run without modifications on Qubes R3).
Dom0 tools implementation
-------------------------
Players:
- `/usr/lib/qubes/qrexec-daemon` \<- started by mgmt stack (qubes.py) when a VM is started.
- `/usr/lib/qubes/qrexec-policy` \<- internal program used to evaluate the policy file and making the 2nd half of the connection.
- `/usr/lib/qubes/qrexec-client` \<- raw command line tool that talks to the daemon via unix socket (`/var/run/qubes/qrexec.XID`)
Note: none of the above tools are designed to be used by users.
Linux VMs implementation
------------------------
Players:
- `/usr/lib/qubes/qrexec-agent` \<- started by VM bootup scripts, a daemon.
- `/usr/lib/qubes/qubes-rpc-multiplexer` \<- executes the actual service program, as specified in VM's `/etc/qubes-rpc/qubes.XYZ`.
- `/usr/lib/qubes/qrexec-client-vm` \<- raw command line tool that talks to the agent.
Note: none of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
Windows VMs implemention
------------------------
%QUBES\_DIR% is the installation path (`c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools` by default).
- `%QUBES_DIR%\bin\qrexec-agent.exe` \<- runs as a system service. Responsible both for raw command execution and interpreting RPC service requests.
- `%QUBES_DIR%\qubes-rpc` \<- directory with `qubes.XYZ` files that contain commands for executing RPC services. Binaries for the services are contained in `%QUBES_DIR%\qubes-rpc-services`.
- `%QUBES_DIR%\bin\qrexec-client-vm` \<- raw command line tool that talks to the agent.
Note: neither of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
All the pieces together at work
-------------------------------
Note: this section is not needed to use qrexec for writing Qubes apps. Also note the qrexec framework implemention in Qubes R3 significantly differs from what is described in this section.
The VM-VM channels in Qubes R2 are made via "gluing" two VM-Dom0 and Dom0-VM vchan connections:
![qrexec2-internals.png](/attachment/wiki/Qrexec2Implementation/qrexec2-internals.png)
Note: Dom0 never examines the actual data flowing in neither of the two vchan connections.
When a user in a source VM executes `qrexec-client-vm` utility, the following steps are taken:
- `qrexec-client-vm` connects to `qrexec-agent`'s `/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from each of them, which is the fd number of the accepted socket in agent. These 3 integers, in text, concatenated, form "connection identifier" (CID)
- `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob, consisting of target vmname, rpc action, and CID
- `qrexec-client-vm` executes the rpc client, passing the above mentioned unix sockets as process stdin/stdout, and optionally stderr (if the PASS\_LOCAL\_STDERR env variable is set)
- `qrexec-agent` passes the blob to `qrexec-daemon`, via MSG\_AGENT\_TO\_SERVER\_TRIGGER\_CONNECT\_EXISTING message over vchan
- `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target vmname, rpc action, and CID as cmdline arguments
- `qrexec-policy` evaluates the policy file. If successful, creates a pair of `qrexec-client` processes, whose stdin/stdout are cross-connencted.
- The first `qrexec-client` connects to the src VM, using the `-c ClientID` parameter, which results in not creating a new process, but connecting to the existing process file descriptors (these are the fds of unix socket created in step 1).
- The second `qrexec-client` connects to the target VM, and executes `qubes-rpc-multiplexer` command there with the rpc action as the cmdline argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server on the target.
- In the above step, if the target VM is `$dispvm`, the DispVM is created via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client` process to exit, and then destroys the DispVM.
Protocol description ("wire-level" spec)
----------------------------------------
TODO

129
en/developers/services/Qrexec3.md Normal file
View file

@ -0,0 +1,129 @@
---
layout: doc
title: Qrexec3
permalink: /en/doc/qrexec3/
redirect_from:
- /doc/Qrexec3/
- /wiki/Qrexec3/
---
Command execution in VM (and Qubes RPC)
=======================================
*[Note: this documents describes Qrexec v3 (Odyssey)]*
Qrexec framework is used by core Qubes components to implement communication between domains. Qubes domains are isolated by design but there is a need for a mechanism to allow administrative domain (dom0) to force command execution in another domain (VM). For instance, when user selects an application from KDE menu, it should be started in the selected VM. Also it is often useful to be able to pass stdin/stdout/stderr from an application running in VM to dom0 (and the other way around). In specific circumstances Qubes allows VMs to be initiators of such communication (so for example a VM can notify dom0 that there are updates available for it).
Qrexec basics
-------------
Qrexec is built on top of vchan (a library providing data links between VMs). During domain creation a process named *qrexec-daemon* is started in dom0, and a process named *qrexec-agent* is started in the VM. They are connected over *vchan* channel. *qrexec-daemon* listens for connections from dom0 utility named *qrexec-client*. Typically, the first thing that a *qrexec-client* instance does is to send a request to *qrexec-daemon* to start a process (let's name it VMprocess) with a given command line in a specified VM (someVM). *qrexec-daemon* assigns unique vchan connection details and sends them both to *qrexec-client* (in dom0) and *qrexec-agent* (in someVM). *qrexec-client* starts a vchan server which *qrexec-agent* connects to. Since then, stdin/stdout/stderr from the VMprocess is passed via vchan between *qrexec-agent* and the *qrexec-client* process.
So, for example, executing in dom0
`qrexec-client -d someVM user:bash`
allows to work with the remote shell. The string before the first semicolon specifies what user to run the command as. Adding `-e` on the *qrexec-client* command line results in mere command execution (no data passing), and *qrexec-client* exits immediately after sending the execution request and receiving status code from *qrexec-agent* (whether the process creation succeeded). There is also the `-l local_program` flag -- with it, *qrexec-client* passes stdin/stdout of the remote process to the (spawned for this purpose) *local\_program*, not to its own stdin/stdout.
The `qvm-run` command is heavily based on *qrexec-client*. It also takes care of additional activities, e.g. starting the domain if it is not up yet and starting the GUI daemon. Thus, it is usually more convenient to use `qvm-run`.
There can be almost arbitrary number of *qrexec-client* processes for a domain (so, connected to the same *qrexec-daemon*, same domain) -- their data is multiplexed independently. Number of available vchan channels is the limiting factor here, it depends on the underlying hypervisor.
Qubes RPC services
------------------
Some tasks (like intervm file copy) share the same rpc-like structure: a process in one VM (say, file sender) needs to invoke and send/receive data to some process in other VM (say, file receiver). Thus, the Qubes RPC framework was created, facilitating such actions.
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control over other, possibly more privileged, VM. Therefore the design decision was made to pass all control communication via dom0, that can enforce proper authorization. Then, it is natural to reuse the already-existing qrexec framework.
Also, note that bare qrexec provides VM\<-\>dom0 connectivity, but the command execution is always initiated by dom0. There are cases when VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed .desktop files). Thus, the framework allows dom0 to be the rpc target as well.
Thanks to the framework, RPC programs are very simple -- both rpc client and server just use their stdin/stdout to pass data. The framework does all the inner work to connect these processes to each other via *qrexec-daemon* and *qrexec-agent*. Additionally, disposable VMs are tightly integrated -- rpc to a disposableVM is identical to rpc to a normal domain, all one needs is to pass "\$dispvm" as the remote domain name.
Qubes RPC administration
------------------------
[TODO: fix for non-linux dom0]
In dom0, there is a bunch of files in */etc/qubes-rpc/policy* directory, whose names describe the available rpc actions; their content is the rpc access policy database. Currently defined actions are:
- qubes.Filecopy
- qubes.OpenInVM
- qubes.ReceiveUpdates
- qubes.SyncAppMenus
- qubes.VMShell
- qubes.ClipboardPaste
- qubes.Gpg
- qubes.NotifyUpdates
- qubes.PdfConvert
These files contain lines with the following format:
srcvm destvm (allow|deny|ask)[,user=user\_to\_run\_as][,target=VM\_to\_redirect\_to]
You can specify srcvm and destvm by name, or by one of "\$anyvm", "\$dispvm", "dom0" reserved keywords (note string "dom0" does not match the \$anyvm pattern; all other names do). Only "\$anyvm" keyword makes sense in srcvm field (service calls from dom0 are currently always allowed, "\$dispvm" means "new VM created for this particular request" - so it is never a source of request). Currently there is no way to specify source VM by type. Whenever a rpc request for action X is received, the first line in /etc/qubes-rpc/policy/X that match srcvm/destvm is consulted to determine whether to allow rpc, what user account the program should run in target VM under, and what VM to redirect the execution to. If the policy file does not exits, user is prompted to create one; if still there is no policy file after prompting, the action is denied.
In the target VM, the */etc/qubes-rpc/RPC\_ACTION\_NAME* must exist, containing the file name of the program that will be invoked.
In the src VM, one should invoke the client via
`/usr/lib/qubes/qrexec-client-vm target_vm_name RPC_ACTION_NAME rpc_client_path client arguments`
Note that only stdin/stdout is passed between rpc server and client -- notably, no command line argument are passed. Source VM name is specified by QREXEC\_REMOTE\_DOMAIN environment variable. By default, stderr of client and server is logged to respective /var/log/qubes/qrexec.XID files.
Be very careful when coding and adding a new rpc service. Unless the offered functionality equals full control over the target (it is the case with e.g. qubes.VMShell action), any vulnerability in a rpc server can be fatal to qubes security. On the other hand, this mechanism allows to delegate processing of untrusted input to less privileged (or throwaway) AppVMs, thus wise usage of it increases security.
### Revoking "Yes to All" authorization
Qubes RPC policy supports "ask" action. This will prompt the user whether given RPC call should be allowed. That prompt window has also "Yes to All" option, which will allow the action and add new entry to the policy file, which will unconditionally allow further calls for given service-srcVM-dstVM tuple.
In order to remove such authorization, issue this command from a Dom0 terminal (for qubes.Filecopy service):
`sudo nano /etc/qubes-rpc/policy/qubes.Filecopy`
and then remove the first line/s (before the first \#\# comment) which are the "Yes to All" results.
### Qubes RPC example
We will show the necessary files to create rpc call that adds two integers on the target and returns back the result to the invoker.
- rpc client code (*/usr/bin/our\_test\_add\_client*)
~~~
#!/bin/sh
echo $1 $2 # pass data to rpc server
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
~~~
- rpc server code (*/usr/bin/our\_test\_add\_server*)
~~~
#!/bin/sh
read arg1 arg2 # read from stdin, which is received from the rpc client
echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
~~~
- policy file in dom0 (*/etc/qubes-rpc/policy/test.Add* )
~~~
$anyvm $anyvm ask
~~~
- server path definition ( */etc/qubes-rpc/test.Add*)
~~~
/usr/bin/our_test_add_server
~~~
- invoke rpc via
~~~
/usr/lib/qubes/qrexec-client-vm target_vm test.Add /usr/bin/our_test_add_client 1 2
~~~
and we should get "3" as answer, after dom0 allows it.
Qubes RPC internals
-------------------
See [QrexecProtocol?](/doc/QrexecProtocol/).

184
en/developers/services/Qrexec3Implementation.md Normal file
View file

@ -0,0 +1,184 @@
---
layout: doc
title: Qrexec3Implementation
permalink: /en/doc/qrexec3-implementation/
redirect_from:
- /doc/Qrexec3Implementation/
- /wiki/Qrexec3Implementation/
---
Implementation of qrexec in Qubes R3
====================================
This page describes implementation of the [qrexec framework](/en/doc/qrexec/) in Qubes OS R3.
Qrexec framework consists of a number of processes communicating with each other using common IPC protocol (described in detail below). Components residing in the same domain use pipes as the underlying transport medium, while components in separate domains use vchan link.
Dom0 tools implementation
-------------------------
- `/usr/lib/qubes/qrexec-daemon` \<- one instance is required for every active domain. Responsible for:
- Handling execution and service requests from **dom0** (source: `qrexec-client`).
- Handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`).
> Command line: `qrexec-daemon domain-id domain-name [default user]`
> *domain-id*: numeric Qubes ID assigned to the associated domain.
> *domain-name*: associated domain name.
> *default user*: optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one.
- `/usr/lib/qubes/qrexec-policy` \<- internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed.
- `/usr/lib/qubes/qrexec-client` \<- used to pass execution and service requests to `qrexec-daemon`. Command line parameters:
> `-d target-domain-name` Specifies the target for the execution/service request.
> `-l local-program` Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer.
> `-e` Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received.
> `-c <request-id,src-domain-name,src-domain-id>` Used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example.
> `cmdline` Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example.
Note: none of the above tools are designed to be used by users directly.
VM tools implementation
-----------------------
- `qrexec-agent` \<- one instance runs in each active domain. Responsible for:
- Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in **dom0**.
- Executing associated `qrexec-daemon` execution/service requests.
> Command line parameters: none.
- `qrexec-client-vm` \<- runs in an active domain. Used to pass service requests to `qrexec-agent`.
> Command line: `qrexec-client-vm target-domain-name service-name local-program [local program arguments]`
> `target-domain-name` Target domain for the service request. Source is the current domain.
> `service-name` Requested service name.
> `local-program` **local-program** is executed locally and its stdin/stdout are connected to the remote service endpoint.
Qrexec protocol details
-----------------------
Qrexec protocol is message-based. All messages share a common header followed by an optional data packet.
~~~
/* uniform for all peers, data type depends on message type */
struct msg_header {
uint32_t type; /* message type */
uint32_t len; /* data length */
};
~~~
When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
~~~
struct peer_info {
uint32_t version; /* qrexec protocol version */
};
~~~
The client then should reply with its own `MSG_HELLO` and `peer_info`. If protocol versions don't match, the connection is closed. TODO: fallback for backwards compatibility, don't do handshake in the same domain?.
Details of all possible use cases and the messages involved are described below.
### dom0: request execution of some\_command in domX and pass stdin/stdout
- **dom0**: `qrexec-client` is invoked in **dom0** as follows:
> `qrexec-client -d domX [-l local_program] user:some_command`
> `user` may be substituted with the literal `DEFAULT`. In that case, default Qubes user will be used to execute `some_command`.
- **dom0**: `qrexec-client` sets `QREXEC_REMOTE_DOMAIN` environment variable to **domX**.
- **dom0**: If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.
- **dom0**: `qrexec-client` connects to **domX**'s `qrexec-daemon`.
- **dom0**: `qrexec-daemon` sends `MSG_HELLO` header followed by `peer_info` to `qrexec-client`.
- **dom0**: `qrexec-client` replies with `MSG_HELLO` header followed by `peer_info` to `qrexec-daemon`.
- **dom0**: `qrexec-client` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to `qrexec-daemon`
~~~
/* variable size */
struct exec_params {
uint32_t connect_domain; /* target domain id */
uint32_t connect_port; /* target vchan port for i/o exchange */
char cmdline[0]; /* command line to execute, size = msg_header.len - sizeof(struct exec_params) */
};
~~~
In this case, `connect_domain` and `connect_port` are set to 0.
- **dom0**: `qrexec-daemon` replies to `qrexec-client` with `MSG_EXEC_CMDLINE` header followed by `exec_params`, but with empty `cmdline` field. `connect_domain` is set to Qubes ID of **domX** and `connect_port` is set to a vchan port allocated by `qrexec-daemon`.
- **dom0**: `qrexec-daemon` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to the associated **domX** `qrexec-agent` over vchan. `connect_domain` is set to 0 (**dom0**), `connect_port` is the same as sent to `qrexec-client`. `cmdline` is unchanged except that the literal `DEFAULT` is replaced with actual user name, if present.
- **dom0**: `qrexec-client` disconnects from `qrexec-daemon`.
- **dom0**: `qrexec-client` starts a vchan server using the details received from `qrexec-daemon` and waits for connection from **domX**'s `qrexec-agent`.
- **domX**: `qrexec-agent` receives `MSG_EXEC_CMDLINE` header followed by `exec_params` from `qrexec-daemon` over vchan.
- **domX**: `qrexec-agent` connects to `qrexec-client` over vchan using the details from `exec_params`.
- **domX**: `qrexec-agent` executes `some_command` in **domX** and connects the child's stdin/stdout to the data vchan. If the process creation fails, `qrexec-agent` sends `MSG_DATA_EXIT_CODE` to `qrexec-client` followed by the status code (**int**) and disconnects from the data vchan.
- Data read from `some_command`'s stdout is sent to the data vchan using `MSG_DATA_STDOUT` by `qrexec-agent`. `qrexec-client` passes data received as `MSG_DATA_STDOUT` to its own stdout (or to `local_program`'s stdin if used).
- `qrexec-client` sends data read from local stdin (or `local_program`'s stdout if used) to `qrexec-agent` over the data vchan using `MSG_DATA_STDIN`. `qrexec-agent` passes data received as `MSG_DATA_STDIN` to `some_command`'s stdin.
- `MSG_DATA_STDOUT` or `MSG_DATA_STDIN` with data `len` field set to 0 in `msg_header` is an EOF marker. Peer receiving such message should close the associated input/output pipe.
- When `some_command` terminates, **domX**'s `qrexec-agent` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**). `qrexec-agent` then disconnects from the data vchan.
### domY: invoke execution of qubes service qubes.SomeRpc in domX and pass stdin/stdout
- **domY**: `qrexec-client-vm` is invoked as follows:
> `qrexec-client-vm domX qubes.SomeRpc local_program [params]`
- **domY**: `qrexec-client-vm` connects to `qrexec-agent` (via local socket/named pipe).
- **domY**: `qrexec-client-vm` sends `trigger_service_params` data to `qrexec-agent` (without filling the `request_id` field):
~~~
struct trigger_service_params {
char service_name[64];
char target_domain[32];
struct service_params request_id; /* service request id */
};
struct service_params {
char ident[32];
};
~~~
- **domY**: `qrexec-agent` allocates a locally-unique (for this domain) `request_id` (let's say `13`) and fills it in the `trigger_service_params` struct received from `qrexec-client-vm`.
- **domY**: `qrexec-agent` sends `MSG_TRIGGER_SERVICE` header followed by `trigger_service_params` to `qrexec-daemon` in **dom0** via vchan.
- **dom0**: **domY**'s `qrexec-daemon` executes `qrexec-policy`: `qrexec-policy domY_id domY domX qubes.SomeRpc 13`.
- **dom0**: `qrexec-policy` evaluates if the RPC should be allowed or denied. If the action is allowed it returns `0`, if the action is denied it returns `1`.
- **dom0**: **domY**'s `qrexec-daemon` checks the exit code of `qrexec-policy`.
- If `qrexec-policy` returned **not** `0`: **domY**'s `qrexec-daemon` sends `MSG_SERVICE_REFUSED` header followed by `service_params` to **domY**'s `qrexec-agent`. `service_params.ident` is identical to the one received. **domY**'s `qrexec-agent` disconnects its `qrexec-client-vm` and RPC processing is finished.
- If `qrexec-policy` returned `0`, RPC processing continues.
- **dom0**: if `qrexec-policy` allowed the RPC, it executed `qrexec-client -d domX -c 13,domY,domY_id user:QUBESRPC qubes.SomeRpc domY`.
- **dom0**: `qrexec-client` sets `QREXEC_REMOTE_DOMAIN` environment variable to **domX**.
- **dom0**: `qrexec-client` connects to **domX**'s `qrexec-daemon`.
- **dom0**: **domX**'s `qrexec-daemon` sends `MSG_HELLO` header followed by `peer_info` to `qrexec-client`.
- **dom0**: `qrexec-client` replies with `MSG_HELLO` header followed by `peer_info` to **domX**'s`qrexec-daemon`.
- **dom0**: `qrexec-client` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to **domX**'s`qrexec-daemon`
~~~
/* variable size */
struct exec_params {
uint32_t connect_domain; /* target domain id */
uint32_t connect_port; /* target vchan port for i/o exchange */
char cmdline[0]; /* command line to execute, size = msg_header.len - sizeof(struct exec_params) */
};
~~~
In this case, `connect_domain` is set to id of **domY** (from the `-c` parameter) and `connect_port` is set to 0. `cmdline` field contains the RPC to execute, in this case `user:QUBESRPC qubes.SomeRpc domY`.
- **dom0**: **domX**'s `qrexec-daemon` replies to `qrexec-client` with `MSG_EXEC_CMDLINE` header followed by `exec_params`, but with empty `cmdline` field. `connect_domain` is set to Qubes ID of **domX** and `connect_port` is set to a vchan port allocated by **domX**'s `qrexec-daemon`.
- **dom0**: **domX**'s `qrexec-daemon` sends `MSG_EXEC_CMDLINE` header followed by `exec_params` to **domX**'s `qrexec-agent`. `connect_domain` and `connect_port` fields are the same as in the step above. `cmdline` is set to the one received from `qrexec-client`, in this case `user:QUBESRPC qubes.SomeRpc domY`.
- **dom0**: `qrexec-client` disconnects from **domX**'s `qrexec-daemon` after receiving connection details.
- **dom0**: `qrexec-client` connects to **domY**'s `qrexec-daemon` and exchanges MSG\_HELLO as usual.
- **dom0**: `qrexec-client` sends `MSG_SERVICE_CONNECT` header followed by `exec_params` to **domY**'s `qrexec-daemon`. `connect_domain` is set to ID of **domX** (received from **domX**'s `qrexec-daemon`) and `connect_port` is the one received as well. `cmdline` is set to request ID (`13` in this case).
- **dom0**: **domY**'s `qrexec-daemon` sends `MSG_SERVICE_CONNECT` header followed by `exec_params` to **domY**'s `qrexec-agent`. Data fields are unchanged from the step above.
- **domY**: `qrexec-agent` starts a vchan server on the port received in the step above. It acts as a `qrexec-client` in this case because this is a VM-VM connection.
- **domX**: `qrexec-agent` connects to the vchan server of **domY**'s `qrexec-agent` (connection details were received before from **domX**'s `qrexec-daemon`).
- After that, connection follows the flow of the previous example (dom0-VM).

152
en/doc.md Normal file
View file

@ -0,0 +1,152 @@
---
layout: doc
title: Documentation
permalink: /en/doc/
redirect_from:
- /doc/
- "/doc/UserDoc/"
- "/wiki/UserDoc/"
- "/doc/QubesDocs/"
- "/wiki/QubesDocs/"
---
Qubes OS Documentation
======================
The Basics
----------
* [A Simple Introduction to Qubes](/en/intro/)
* [Getting Started](/en/doc/getting-started/)
* [Users' FAQ](/en/doc/user-faq/)
* [Mailing Lists](/en/doc/mailing-lists/)
* [Further reading: How is Qubes different from...?](http://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html)
* [Further reading: Why Qubes is more than a collection of VMs](http://www.invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf)
Choosing Your Hardware
----------------------
* [System Requirements](/en/doc/system-requirements/)
* [Hardware Compatibility List (HCL)](/en/hcl)
* Qubes Certified Laptops ([coming soon!](https://twitter.com/Puri_sm/status/644963433293717504))
Installing Qubes
----------------
* [Use Qubes without installing: Qubes Live USB (alpha)](https://groups.google.com/d/msg/qubes-users/IQdCEpkooto/iyMh3LuzCAAJ)
* [How to Install Qubes](/en/doc/installation-guide/)
* [Qubes Downloads](/en/downloads/)
* [Why and How to Verify Signatures](/en/doc/verifying-signatures/)
* [Security Considerations when Installing](/en/doc/install-security/)
Common Tasks
------------
* [Copying and Pasting Text Between Domains](/en/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/en/doc/copying-files/)
* [Copying Files to and from dom0](/en/doc/copy-to-dom0/)
* [Mounting USB Drives to AppVMs](/en/doc/stick-mounting/)
* [Updating Software in dom0](/en/doc/software-update-dom0/)
* [Updating and Installing Software in VMs](/en/doc/software-update-vm/)
* [Backup, Restoration, and Migration](/en/doc/backup-restore/)
* [Disposable VMs](/en/doc/dispvm/)
* [Managing Application Shortcuts](/en/doc/managing-appvm-shortcuts/)
* [Enabling Fullscreen Mode](/en/doc/full-screen-mode/)
Managing Operating Systems within Qubes
---------------------------------------
* [TemplateVMs](/en/doc/templates/)
* [Templates: Fedora - minimal](/en/doc/templates/fedora-minimal/)
* [Templates: Debian](/en/doc/templates/debian/)
* [Templates: Archlinux](/en/doc/templates/archlinux/)
* [Templates: Ubuntu](/en/doc/templates/ubuntu/)
* [Templates: Whonix](/en/doc/templates/whonix/)
* [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/en/doc/windows-appvms/)
* [Creating and Using HVM and Windows Domains (Qubes R2+)](/en/doc/hvm-create/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/en/doc/windows-tools-3/)
* [Advanced options and troubleshooting of Qubes Tools for Windows (R2)](/en/doc/windows-tools-2/)
* [Uninstalling Qubes Tools for Windows 2.x](/en/doc/uninstalling-windows-tools-2/)
* [Upgrading the Fedora 20 Template](/en/doc/fedora-template-upgrade-20/)
* [Upgrading the Fedora 18 Template](/en/doc/fedora-template-upgrade-18/)
* [Tips for Using Linux in an HVM](/en/doc/linux-hvm-tips/)
* [Creating NetBSD VM](https://groups.google.com/group/qubes-devel/msg/4015c8900a813985)
Security Guides
---------------
* [General Security Information](/en/doc/qubes-security/)
* [Security Guidelines](/en/doc/security-guidelines/)
* [Understanding Qubes Firewall](/en/doc/qubes-firewall/)
* [Understanding and Preventing Data Leaks](/en/doc/data-leaks/)
* [Installing Anti Evil Maid](/en/doc/anti-evil-maid/)
* [Using Multi-factor Authentication with Qubes](/en/doc/multifactor-authentication/)
* [Using GPG more securely in Qubes: Split GPG](/en/doc/split-gpg/)
* [Configuring YubiKey for user authentication](/en/doc/yubi-key/)
* [Note regarding password-less root access in VM](/en/doc/vm-sudo/)
Configuration Guides
--------------------
* [Configuration Files](/en/doc/config-files/)
* [How to Install a Transparent Tor ProxyVM (TorVM)](/en/doc/torvm/)
* [How to set up a ProxyVM as a VPN Gateway](/en/doc/vpn/)
* [Storing AppVMs on Secondary Drives](/en/doc/secondary-storage/)
* [Where are my external storage devices mounted?](/en/doc/external-device-mount-point/)
* [Resizing AppVM and HVM Disk Images](/en/doc/resize-disk-image/)
* [Extending `root.img` Size](/en/doc/resize-root-disk-image/)
* [Installing ZFS in Qubes](/en/doc/zfs/)
* [Mutt Guide](/en/doc/mutt/)
* [Postfix Guide](/en/doc/postfix/)
* [Fetchmail Guide](/en/doc/fetchmail/)
* [Creating Custom NetVMs and ProxyVMs](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
* [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
* [HTTP filtering proxy in Qubes firewall VM](https://groups.google.com/group/qubes-devel/browse_thread/thread/5252bc3f6ed4b43e/d881deb5afaa2a6c#39c95d63fccca12b)
* [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/en/doc/network-bridge-support/)
* [Assigning PCI Devices to AppVMs](/en/doc/assigning-devices/)
* [Enabling TRIM for SSD disks](/en/doc/disk-trim/)
* [Configuring a Network Printer](/en/doc/network-printer/)
* [Using External Audio Devices](/en/doc/external-audio/)
* [Booting with GRUB2 and GPT](https://groups.google.com/group/qubes-devel/browse_thread/thread/e4ac093cabd37d2b/d5090c20d92c4128#d5090c20d92c4128)
* [Rxvt Guide](/en/doc/rxvt/)
Customization Guides
--------------------
* [DispVM Customization](/en/doc/dispvm-customization/)
* [XFCE Installation in dom0](/en/doc/xfce/)
* [Customizing the GUI experience with KDE](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)
* [Language Localization](/en/doc/language-localization/)
Troubleshooting
---------------
* [Home directory is out of disk space error](/en/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](/en/doc/install-nvidia-driver/)
* [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69)
* [Getting Sony Vaio Z laptop to work with Qubes](/en/doc/sony-vaio-tinkering/)
* [Getting Lenovo 450 to work with Qubes](/en/doc/lenovo450-tinkering/)
Reference Pages
---------------
* [Dom0 Command-Line Tools](/en/doc/dom0-tools/)
* [DomU Command-Line Tools](/en/doc/vm-tools/)
* [Glossary of Qubes Terminology](/en/doc/glossary/)
* [Qubes Service Framework](/en/doc/qubes-service/)
* [Command Execution in VMs (and Qubes RPC)](/en/doc/qrexec/)
For Developers
--------------
* [System Documentation](/en/doc/system-doc/)
* [Developers' FAQ](/en/doc/devel-faq/)
* [How to Contribute to the Qubes OS Project](/en/doc/contributing/)
* [Bug Reporting Guide](/en/doc/reporting-bugs/)
* [Source Code](/en/doc/source-code/)
* [Qubes OS Version Scheme](/en/doc/version-scheme/)
* [Coding Guidelines](/en/doc/coding-style/)
* [Documentation Guidelines](/en/doc/doc-guidelines/)
* [Books for Developers](/en/doc/devel-books/)
* [Research Papers](/en/doc/qubes-research/)
* [Licensing](/en/doc/license/)

45
en/hardware/Hcl.md Normal file
View file

@ -0,0 +1,45 @@
---
layout: doc
title: HCL
permalink: /en/doc/hcl/
redirect_from:
- /doc/HCL/
- /wiki/HCL/
- /wiki/HCLR1/
- /wiki/HCL-R2B2/
---
Hardware Compatibility List (HCL) for All Qubes OS Releases
===========================================================
The [HCL](/hcl) is a compilation of reports generated and submitted by users across various Qubes versions.
**Note:**
Except in the case of developer-reported entries, the Qubes team has not independently verified the accuracy of these reports.
Please first consult the data sheets (CPU, chipset, motherboard) prior to buying new hardware for Qubes.
Meet the [SystemRequirements](/en/doc/system-requirements/) and search particular for support of:
- HVM ("AMD virtualization (AMD-V)", "Intel virtualization (VT-x)", "VIA virtualization (VIA VT)")
- IOMMU ("AMD I/O Virtualization Technology (AMD-Vi)", "Intel Virtualization Technology for Directed I/O (VT-d)")
- TPM ("Trusted Platform Module (TPM)" connected to a "20-pin TPM header" on motherboards.)
Test the hardware yourself, if possible.
If using the list to make a purchasing decision, we recommend that you choose hardware with:
- the best achievable Qubes security level (green columns in HVM, IOMMU, TPM)
- and general machine compatibility (green columns in Qubes version, dom0 kernel, remarks).
Generating and Submitting New Reports
-------------------------------------
In order to generate a HCL report in Qubes, simply open a terminal in dom0 (KDE: start-menu -\> System Tools -\> Konsole or Terminal Emulator)
and run `qubes-hcl-report <vm-name>`, where `<vm-name>` is the name of the VM to which the generated HCL files will be saved.
(Note: If you are working with a new Qubes installation, you may need to update your system in order to download this script.)
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** `.txt` file to [\`qubes-users@googlegroups.com\`](/en/doc/qubes-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.
**Please note:**
The **HCL Support Files** may contain numerous hardware details, including serial numbers. If, for privacy or security reasons, you do not wish to make this information public, please **do not** send the `.cpio.gz` file to the public mailing list.

40
en/hardware/SystemRequirements.md Normal file
View file

@ -0,0 +1,40 @@
---
layout: doc
title: SystemRequirements
permalink: /en/doc/system-requirements/
redirect_from:
- /doc/SystemRequirements/
- /wiki/SystemRequirements/
---
System Requirements
===================
Minimum
-------
- 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
- 4 GB RAM
- 32 GB disk space
- legacy boot mode ([UEFI not supported yet](https://github.com/QubesOS/qubes-issues/issues/794))
Recommended
-----------
- Fast SSD (strongly recommended)
- Intel GPU (strongly preferred)
- Nvidia GPUs may require significant [troubleshooting](/en/doc/install-nvidia-driver/).
- ATI GPUs have not been formally tested (but see the [Hardware Compatibility List](/hcl/)).
- Intel VT-x or AMD-v technology (required for running HVM domains, such as Windows-based AppVMs)
- Intel VT-d or AMD IOMMU technology (required for effective isolation of network VMs)
- TPM with proper BIOS support (required for [Anti Evil Maid](http://theinvisiblethings.blogspot.com/2011/09/anti-evil-maid.html))
Important Notes
---------------
- Qubes **can** be installed on systems which do not meet the recommended requirements. Such systems will still offer significant security improvements over traditional operating systems, since things like GUI isolation and kernel protection do not require special hardware.
- Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this. (As a reminder, its capacity must be at least 32 GB.) Simply plug the flash drive into the computer before booting into the Qubes installer from a separate installation medium, choose the flash drive as the target installation disk, and proceed with the installation normally. After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes. In addition to the convenience of having a portable copy of Qubes, this allows users to test for hardware compatibility on multiple machines (e.g., at a brick-and-mortar computer store) before deciding on which computer to purchase. (See [here](/doc/HCL/#generating-and-submitting-new-reports) for advice on hardware compatibility testing.) Keep in mind to also change assigned devices for your netvm and usbvm, if you move between different machines.
- Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).
- Macintosh PCs are not currently supported due to keyboard and mouse problems - details in \#230. (Patches welcome!)
- [Advice on finding a VT-d capable notebook](https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J).

75
en/installing/InstallSecurity.md Normal file
View file

@ -0,0 +1,75 @@
---
layout: doc
title: InstallSecurity
permalink: /en/doc/install-security/
redirect_from:
- /doc/InstallSecurity/
- /wiki/InstallSecurity/
---
# Installation Security Considerations #
## Verifying the Qubes ISO ##
You should [verify][] the PGP signature on your Qubes ISO before you install
from it. However, if the machine on which you attempt the verification process
is already compromised, it could falsely claim that a malicious ISO has a good
signature. Therefore, in order to be certain that your Qubes ISO is trustworthy,
you require a trustworthy machine. But how can you be certain *that* machine is
trustworthy? Only by using another trusted machine, and so forth. This is a
[classic problem][trusting-trust]. While various [solutions][countering] have
been proposed, the point is that each user must ultimately make a choice about
whether to trust that a file is non-malicious.
## Choosing an Installation Medium ##
So, after taking some measures to verify its integrity and authenticity, you've
decided to trust your Qubes ISO. Great! Now you must decide what sort of medium
on which to write it so that you can install from it. From a Qubes-specific
security perspective, each has certain pros and cons.
### USB Drives ###
Pros:
* Works via USB, including with a [USBVM][].
* Non-fixed capacity. (Easy to find one on which the ISO can fit.)
Cons:
* Rewriteable. (If the drive is mounted to a compromised machine, the ISO could
be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware. (Firmware can be malicious even if the drive is new.
Plugging a drive with rewriteable firmware into a compromised machine can
also [compromise the drive][BadUSB]. Installing from a compromised drive
could compromise even a brand new Qubes installation.)
### Optical Discs ###
Pros:
* Read-only available. (If you use read-only media, you don't have to worry
about the ISO being maliciously altered after it has been written to the
disc. You then have the option of verifying the signature on multiple
different machines.)
Cons:
* Fixed capacity. (If the size of the ISO is larger than your disc, it will be
inconvenient.)
* Passthrough burning is not supported by Xen. (This mainly applies if you're
upgrading from a previous version of Qubes.) Currently, the only options for
burning optical discs in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign
this secondary SATA controller to an AppVM.
3. Use a SATA optical drive attached to dom0.
(Option 3 violates the Qubes security model since it entails transferring
an untrusted ISO to dom0 in order to burn it to disc, which leaves only
the other two options.)
[verify]: https://www.qubes-os.org/doc/VerifyingSignatures/
[trusting-trust]: http://www.acm.org/classics/sep95/
[countering]: http://www.dwheeler.com/trusting-trust/
[USBVM]: https://www.qubes-os.org/doc/SecurityGuidelines/#creating-and-using-a-usbvm
[BadUSB]: https://srlabs.de/badusb/

99
en/installing/InstallationGuide.md Normal file
View file

@ -0,0 +1,99 @@
---
layout: doc
title: Installation Guide
permalink: /en/doc/installation-guide/
redirect_from:
- /doc/InstallationGuide/
- /wiki/InstallationGuide/
redirect_from:
-
- /doc/InstallationGuideR1/
redirect_from:
-
- /doc/InstallationGuideR2B1/
redirect_from:
-
- /doc/InstallationGuideR2B2/
redirect_from:
-
- /doc/InstallationGuideR2B3/
redirect_from:
-
- /doc/InstallationGuideR2rc1/
redirect_from:
-
- /doc/InstallationGuideR2rc2/
redirect_from:
-
- /doc/InstallationGuideR3.0rc1/
redirect_from:
-
- /doc/InstallationGuideR3.0rc2/
---
Installation Guide
========================================
1. [Hardware Requirements](#hardware-requirements)
2. [Download installer ISO](#download-installer-iso)
3. [Burning the ISO onto a DVD or USB stick](#burning-the-iso-onto-a-dvd-or-usb-stick)
4. [Upgrading](#upgrading)
5. [Troubleshooting problems with the installer](#troubleshooting-problems-with-the-installer)
6. [Getting Help](#getting-help)
Hardware Requirements
---------------------
Please see the [Hardware Compatibility List](/hcl/) page for more information on required and recommended hardware.
Note: We don't recommend installing Qubes in a virtual machine! It will likely not work. Don't send emails asking about it. However, you can install it on an external USB hard drive and run from it, at least for testing (normally such disks are *orders* of magnitude slower than even the slowest internal hard drives).
Download installer ISO
----------------------
See [this page](/doc/QubesDownloads/) for ISO downloads. Remember, we have absolutely no control over those servers, and so you should be assuming that they might be compromised, or just be serving a compromised ISOs because their operators decided so, for whatever reason. Always verify the digital signature on the downloaded ISO. See this [page](/en/doc/verifying-signatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
gpg -v Qubes-R2-x86_64-DVD.iso.asc
Adjust filename to the version you're installing.
Burning the ISO onto a DVD or USB stick
---------------------------------------
Once you verify this is an authentic ISO, you should burn it on a DVD.
If you prefer to use USB as a source for installation, then you just need to copy the ISO onto the USB device, e.g. using dd:
dd if=Qubes-R2-x86_64-DVD.iso of=/dev/sdX
Adjust filename to the version you're installing. **Be sure to use a correct device as the target in the dd command above (instead of sdX)'''**
On windows you can use [Rufus](http://rufus.akeo.ie/) tool. Be sure to select "DD image" mode (you need to do that **after** selecting Qubes iso image):
<img src="/attachment/wiki/InstallationGuide/rufus-main-boxed.png" height="350">
Before proceeding with the installation, you are encouraged to first read all the information on this page, especially the *Known Issues* paragraph.
Then, when finally ready, boot your system from the installer DVD and follow the instructions on screen. The installer is very simple and asks very few questions -- it's actually easier to install Qubes right now than most other Linux distributions!
The installer loads Xen right at the beginning, so chances are high that if you can see the installer's graphical screen, Qubes will work on your system :)
Upgrading
---------
See [release notes](/doc/releases/) of appropriate version.
Getting Help
------------
- **User manuals are [here](/en/doc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/en/doc/system-doc/)
- If you don't find answer in the sources given above, write to the *qubes-users* mailing list (you don't need to be subscribed to the list, just send email to the address given below):
- [https://groups.google.com/group/qubes-users](https://groups.google.com/group/qubes-users)
- `qubes-users@googlegroups.com`
- Please do not write email to individual developers (Marek, Joanna, etc) asking questions about installation or other problems. Please send all such questions to the mailing list.

65
en/installing/UpgradeToR2.md Normal file
View file

@ -0,0 +1,65 @@
---
layout: doc
title: UpgradeToR2
permalink: /en/doc/upgrade-to-r2/
redirect_from:
- /doc/UpgradeToR2/
- /doc/UpgradeToR2rc1/
redirect_from:
-
- /wiki/UpgradeToR2rc1/
---
Upgrading Qubes R2 Beta 3 to R2
===================================
Current Qubes R2 Beta 3 (R2B3) systems can be upgraded in-place to the latest R2 (R2) release by following the procedure below.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/en/doc/backup-restore/).**
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/).
- **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.
While technically it is possible to use old Fedora 18 template on R2, it is strongly recommended to upgrade all the Template VMs and Standalone VMs, because Fedora 18 no longer receive security updates.
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. If more than one template and/or Standalone VMs are used, then it is recommended to upgrade/replace all of them. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/en/doc/software-update-vm/).
Upgrading dom0
--------------
Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous release, so this operation will upgrade a lot of packages.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
1. Install all the updates for Dom0:
~~~
sudo qubes-dom0-update
~~~
After this step you should have `qubes-release-2-5` in your Dom0. Important: if you happen to have `qubes-release-2-6*` then you should downgrade to `qubes-release-2-5`! The `qubes-release-2-6*` packages have been uploaded to the testing repos and were kept there for a few hours, until we realized they bring incorrect repo definitions and so we removed them and also have changed the update procedure a bit (simplifying it).
1. Upgrade dom0 to R2:
Note: be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest qubes packages, specifically `qubes-core-vm-2.1.33` or later. This doesn't imply that the VM must already be upgraded to fc20 -- for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there.
~~~
sudo qubes-dom0-update qubes-dom0-dist-upgrade
sudo qubes-dom0-update
~~~
1. If above step completed successfully you should have `qubes-release-2-9` or later. If not, repeat above step with additional `--clean` option.
4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing:
~~~
sudo qubes-dom0-update qubes-template-fedora-20-x64
~~~
1. Reboot the system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

76
en/installing/UpgradeToR2b1.md Normal file
View file

@ -0,0 +1,76 @@
---
layout: doc
title: UpgradeToR2B1
permalink: /en/doc/upgrade-to-r2b1/
redirect_from:
- /doc/UpgradeToR2B1/
- /wiki/UpgradeToR2B1/
---
Upgrading Qubes R1 to R2 Beta 1
===============================
**Note: Qubes R2 Beta 1 is no longer supported! Please install or upgrade to a newer Qubes R2.**
**Note: This page is kept for historical reasons only! Do not follow the instructions below'''**
Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the latest R2 beta release by following the procedure below. As usual, it is advisable to backup the system before proceeding with the upgrade
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [SoftwareUpdateVM here]. The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
sudo yum install qubes-upgrade-vm
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
~~~
sudo yum update
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
1. Shut down the VM.
Upgrade Dom0
------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 packages:
~~~
sudo qubes-dom0-update --releasever=2
~~~
4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

108
en/installing/UpgradeToR2b2.md Normal file
View file

@ -0,0 +1,108 @@
---
layout: doc
title: UpgradeToR2B2
permalink: /en/doc/upgrade-to-r2b2/
redirect_from:
- /doc/UpgradeToR2B2/
- /wiki/UpgradeToR2B2/
---
Upgrading Qubes R1 to R2 (beta2)
================================
Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the latest R2 beta release by following the procedure below. As usual, it is advisable to backup the system before proceeding with the upgrade. While it is possible to upgrade the system **it is strongly recommended to reinstall it**. You will preserve all your data and settings thanks to [backup and restore tools](/en/doc/backup-restore/).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
**If you have already R2 Beta1 installed, follow standard template update procedure (e.g. "Update VM" buttom in Qubes Manager) and skip the rest of this section**
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [SoftwareUpdateVM here]. The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
sudo yum install qubes-upgrade-vm
~~~
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
~~~
sudo yum update
~~~
The installer (yum) will prompt to accept the new Qubes R2 signing key:
~~~
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
Fingerprint: 3f01 def4 9719 158e f862 66f8 0c73 b9d4 0a40 e458
Package : qubes-upgrade-vm-1.0-1.fc17.x86_64 (@qubes-vm-current)
From : /etc/pki/rpm-gpg/RPM-GPG-KEY-upgrade-qubes-2-primary
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).
1. Shut down the VM.
Installing new template
-----------------------
Qubes R2 Beta2 brings new fedora-18-x64 template (based on Fedora 18). You can install it from Qubes installation DVD. Insert installation DVD into your drive and issue following commmands:
~~~
$ sudo -s
# mkdir -p /mnt/cdrom
# mount /dev/cdrom /mnt/cdrom # you can also use ISO image instead of /dev/cdrom; then add -o loop option
# yum install /mnt/cdrom/Packages/q/qubes-template-fedora-18-x64*rpm
# umount /mnt/cdrom
~~~
If you already have fedora-17-x64, you can also upgrade it to fedora-18-x64 following [standard Fedora upgrade procedure](http://fedoraproject.org/wiki/Upgrading_Fedora_using_yum) (only "yum" method will work in Qubes VM).
Upgrade Dom0
------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-1-6` in your Dom0.
3. Install R2 upgrade package:
~~~
sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
~~~
4. Start upgrade process:
~~~
sudo qubes-dist-upgrade
~~~
5. Follow instructions on screen, first stage of upgrade should end up with reboot request.
6. Reboot your system, ensure that you choose "Qubes Upgrade" boot option.
7. When system starts up, login and start start
~~~
sudo qubes-dist-upgrade
~~~
again. This will start second stage of upgrade, here most packages will be upgraded, so this will take a while.
8. You will be prompted to install new bootloader. If you haven't changed anything in this matter from initial installation, just accept the default.
9. Reboot your system. System shutdown may hung because some running system components no longer match that installed on disk; just wait a few minutes and hard reset the system in such case.
10. This is end of upgrade process, you should now have Qubes R2 system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

76
en/installing/UpgradeToR2b3.md Normal file
View file

@ -0,0 +1,76 @@
---
layout: doc
title: UpgradeToR2B3
permalink: /en/doc/upgrade-to-r2b3/
redirect_from:
- /doc/UpgradeToR2B3/
- /wiki/UpgradeToR2B3/
---
Upgrading Qubes R2 Beta 2 to R2 Beta 3
======================================
Current Qubes R2 Beta 2 (R2B2) systems can be upgraded in-place to the latest R2 Beta 3 (R2B3) release by following the procedure below. However, upgrading in-place is riskier than performing a clean installation, since there are more things which can go wrong. For this reason, **we strongly recommended that users perform a [clean installation](/en/doc/installation-guide/) of Qubes R2 Beta 3**.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/en/doc/backup-restore/).**
Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/en/doc/backup-restore/) correctly!).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/en/doc/software-update-vm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely ends with unusable system.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Proceed with normal update in the template:
~~~
sudo yum update
~~~
3. Ensure that you've got qubes-core-vm package version 2.1.13-3.fc18:
~~~
rpm -q qubes-core-vm
~~~
4. Update the system to R2 beta3 packages:
~~~
sudo yum --enablerepo=qubes-vm-r2b3-current update
~~~
5. **Do not** shutdown the VM.
Upgrading dom0
--------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm, fedora-18-x64 (or to be more precise: template which your netvm and firewallvm is based on).
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
~~~
sudo qubes-dom0-update qubes-release
~~~
This should install `qubes-release-2-3.1` in your Dom0.
3. Upgrade dom0 to R2 beta3:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
~~~
4. If above step completed successfully you should have qubes-core-dom0 at least 2.1.34. If not, repeat above step with additional `--clean` option.
5. Now is the time to shutdown all the VMs:
~~~
qvm-shutdown --all --wait
~~~
6. Reboot the system.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

145
en/installing/UpgradeToR3.0.md Normal file
View file

@ -0,0 +1,145 @@
---
layout: doc
title: Upgrade to R3.0
permalink: /en/doc/upgrade-to-r3.0/
redirect_from:
- /doc/UpgradeToR3.0/
- /doc/UpgradeToR3.0rc1/
---
Upgrading Qubes R2 to R3.0
======================================
**This instruction is highly experimental, the official way to upgrade from R2 is to backup the data and reinstall the system. Use at your own risk!**
Current Qubes R3.0 (R3.0) systems can be upgraded in-place to the latest R3.0 by following the procedure below. However, upgrading in-place is riskier than performing a clean installation, since there are more things which can go wrong. For this reason, **we strongly recommended that users perform a [clean installation](/en/doc/installation-guide/) of Qubes R3.0**.
**Before attempting either an in-place upgrade or a clean installation, we strongly recommend that users back up the system by using the built-in [backup tool](/en/doc/backup-restore/).**
Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/en/doc/backup-restore/) correctly!).
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/en/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely end with unusable system.
### Upgrade Fedora template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package:
sudo yum install qubes-upgrade-vm
3. Proceed with normal update in the template:
sudo yum update
You'll need to accept "Qubes Release 3 Signing Key" - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don't need to manually verify it.
4. Shutdown the template VM.
### Upgrade Debian template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Update repository definition:
sudo cp /etc/apt/sources.list.d/qubes-r2.list
/etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with normal update in the template:
sudo apt-get update
sudo apt-get dist-upgrade
There will be some error messages during the process, but our tests does
not revealed any negative consequences.
Update of `qubesdb-vm` package will restart the service, which will fail
(after 3min timeout), but you can ignore this problem for now. After
completing the whole upgrade the service will be properly restarted.
4. Shutdown the template VM.
Upgrading dom0
--------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm - you will not be able to start them again.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
sudo qubes-dom0-update qubes-release
This should install `qubes-release-2-12` in your Dom0.
3. Upgrade dom0 to R3.0:
sudo qubes-dom0-update --releasever=3.0
After this step, until you reboot the system, most of the qvm-* tools will not work.
4. If above step completed successfully you should have `qubes-core-dom0` at least 3.0.8. If not, repeat above step with additional `--clean` option.
5. Enable Xen services:
sudo systemctl enable xenconsoled.service xenstored.service
6. Reboot the system.
It may happen that the system hang during the reboot. Hard reset the system in such case, all the filesystems are unmounted at this stage.
Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.
Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template:
sudo qubes-dom0-update qubes-template-fedora-21
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
Because of above limitations, you will need to configure some of those manually. The instruction assumes the VM name is `custom-template`, but the same instructions can be applied to a standalone VM.
1.Check the VM network parameters, you will need them later:
[user@dom0 ~]$ qvm-ls -n custom-template
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
name | on | state | updbl | type | netvm | label | ip | ip back | gateway/DNS |
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
[custom-template] | | Halted | Yes | Tpl | *firewallvm | black | 10.137.1.53 | n/a | 10.137.1.1 |
2.Start the VM from command line:
[user@dom0 ~]$ qvm-start custom-template
--> Loading the VM (type = TemplateVM)...
--> Starting Qubes DB...
--> Setting Qubes DB info for the VM...
--> Updating firewall rules...
--> Starting the VM...
--> Starting the qrexec daemon...
Waiting for VM's qrexec agent.............................................................Cannot connect to 'custom-template' qrexec agent for 60 seconds, giving up
ERROR: Cannot execute qrexec-daemon!
You can interrupt with Ctrl-C that qrexec waiting process.
3.Access VM console:
[user@dom0 ~]$ virsh -c xen:/// console custom-template
4.Configure network according to parameters retrieved in first step:
ip addr add 10.137.1.53/32 dev eth0
ip route add 10.137.1.1/32 dev eth0
ip route add via 10.137.1.1
echo nameserver 10.137.1.1 > /etc/resolv.conf
5.Proceed with normal upgrade instruction described on this page.

200
en/installing/VerifyingSignatures.md Normal file
View file

@ -0,0 +1,200 @@
---
layout: doc
title: VerifyingSignatures
permalink: /en/doc/verifying-signatures/
redirect_from:
- /doc/VerifyingSignatures/
- /wiki/VerifyingSignatures/
---
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.
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).
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.
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.
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)).
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.,
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,
$ gpg --import ./qubes-master-signing-key.asc
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:
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](/en/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.
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:
$ gpg --edit-key 0x36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct
unless you restart the program.
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.
For example: Qubes OS Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-signing-key.asc)) is used for all Release 2 ISO images.
$ gpg --recv-keys 0x3F01DEF49719158EF86266F80C73B9D40A40E458
gpg: requesting key 0A40E458 from hkp server keys.gnupg.net
gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 1 signed: 1 trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: depth: 1 valid: 1 signed: 0 trust: 1-, 0q, 0n, 0m, 0f, 0u
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](/en/doc/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.
You can now verify the ISO image (`Qubes-R2-x86_64-DVD.iso`) matches its signature (`Qubes-R2-x86_64-DVD.iso.asc`):
$ gpg -v --verify Qubes-R2-x86_64-DVD.iso.asc
gpg: armor header: Version: GnuPG v1
gpg: assuming signed data in `Qubes-R2-x86_64-DVD.iso'
gpg: Signature made Tue Sep 23 08:38:40 2014 UTC using RSA key ID 0A40E458
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 2 Signing Key"
gpg: binary signature, digest algorithm SHA1
The Release 2 Signing Key ([`0x0A40E458`](https://keys.qubes-os.org/keys/qubes-release-2-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)):
$ gpg --list-sig 0A40E458
pub 4096R/0A40E458 2012-11-15
uid Qubes OS Release 2 Signing Key
sig 36879494 2012-11-15 Qubes Master Signing Key
sig 3 0A40E458 2012-11-15 Qubes OS Release 2 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-R2-x86_64-DVD.iso` is accompanied by `Qubes-R2-x86_64-DVD.iso.DIGESTS` which has the following content:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
6f6ff24f2edec3a7607671001e694d8e *Qubes-R2-x86_64-DVD.iso
0344e04a98b741c311936f3e2bb67fcebfc2be08 *Qubes-R2-x86_64-DVD.iso
1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3 *Qubes-R2-x86_64-DVD.iso
a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772 *Qubes-R2-x86_64-DVD.iso
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAEBCAAGBQJVvUfGAAoJEAxzudQKQORYhj0P/1TTtDn0WtlfwvSOQ5m3ybeT
CiEv/wWZmZR2hfTOs1chlwt5PZFUCkAk6hbr7+AbJU3HurnmyK97ORtak0WcuBiO
3MWKGiDaBGjKfYcv7YZWDcMRCjN69I4gq7lhXB2JC5pSnOkciD8xzSMAnyFz8Dnh
sHSGJIrOIeLhj0Jt90NGm2CKeQgKrbCGQWWqn/BRf40GXjkyGDSAj+Bsbnpn3LjE
kWOblX631PRi8eclD27/b5hsK/ur7RlpA0KKn7dJoTO2PikEZRoT7QgcIMxYWOja
GZhDi/5gWyttVmF1EszkwaYLAH3uqkZbgKHIsLwweTwXYxMqjobQ5dFkm0RCaXXg
wf/ayfyAIHCWYK0GvyHyAe7hs30UQ4Ssw0LDnnTsOwJYzxZpZqWhcg89EBMGdNgu
5sghcj97VHjDI/zpRyTOAi1+8ZoG1FMsvmnlpghojXPcFGM1nldKs2k1XfGHdVrH
ucJfhQilhsGo65EiN+v9VS6tz5dDtX5+NnkkpR5mOx1+xwUf4n+F6cWyIiLKY6Se
byIN0dPtErZpq47w6bhLZ3Dd/frReG8Egmr7yLAqGHKmuwvmEUA6w6a2VzWQy5G4
Smcj5kPHKWJ9SvAQHc7SoUmYqt2GEAKBi6CYb5Oeknf3vc4QUSPxF8KRiebUhTxc
ruycSbLkLklsDjfH0caD
=NVWj
-----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 is by using `openssl` from the command line:
$ openssl dgst -md5 Qubes-R2-x86_64-DVD.iso
MD5(Qubes-R2-x86_64-DVD.iso)= 6f6ff24f2edec3a7607671001e694d8e
$ openssl dgst -sha1 Qubes-R2-x86_64-DVD.iso
SHA1(Qubes-R2-x86_64-DVD.iso)= 0344e04a98b741c311936f3e2bb67fcebfc2be08
$ openssl dgst -sha256 Qubes-R2-x86_64-DVD.iso
SHA256(Qubes-R2-x86_64-DVD.iso)= 1fa056b73d8e2e93acdf3dcaface2515d61335e723d1d7d338241209119c10a3
$ openssl dgst -sha512 Qubes-R2-x86_64-DVD.iso
SHA512(Qubes-R2-x86_64-DVD.iso)= a49ff19c1ad8c51a50198ac51670cf7c71972b437fa59f2e9fc9432cce76f4529f10de1d576ac777cdd49b9325eb2f32347fd13e0f9b04f823a73e84c6ddd772
(Notice that the outputs match the values from the `.DIGESTS` file.)
However, it is possible that an attacker replaced `Qubes-R2-x86_64-DVD.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-R2-x86_64-DVD.iso.DIGESTS` with his own set of values. Therefore, ideally, we should also verify the authenticity of the listed hash values. Since `Qubes-R2-x86_64-DVD.iso.DIGESTS` is a clearsigned PGP file, we can use `gpg` to verify it from the command line:
$ gpg -v --verify Qubes-R2-x86_64-DVD.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v1
gpg: original file name=''
gpg: Signature made 2015-08-01T22:27:18 UTC using RSA key ID 0A40E458
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release 2 Signing Key"
gpg: textmode signature, digest algorithm SHA256
The signature is good. Assuming our copy of the `Qubes OS Release 2 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!
To verify a signature on a git tag, you can use:
$ git tag -v <tag name>

73
en/managing-os/FedoraTemplateUpgrade-18.md Normal file
View file

@ -0,0 +1,73 @@
---
layout: doc
title: FedoraTemplateUpgrade
permalink: /en/doc/fedora-template-upgrade-18/
redirect_from:
- /doc/FedoraTemplateUpgrade18/
- /wiki/FedoraTemplateUpgrade/
---
Upgrade of Fedora template
==========================
(**Note:** There is a [newer version of this page for upgrading from Fedora 20 to Fedora 21](/en/doc/fedora-template-upgrade-20/).)
This instruction in simplified version of [official Fedora instruction](https://fedoraproject.org/wiki/Upgrading_Fedora_using_yum). Note that only "yum" method will work in Qubes template VM (if you are curious why: mostly because template VM does not have own bootloader).
Upgrading Fedora 18 to Fedora 20
--------------------------------
Commands to run in dom0 console (you can do the same from Qubes Manager):
~~~
qvm-clone fedora-18-x64 fedora-20-x64
qvm-run -a fedora-20-x64 gnome-terminal
~~~
Commands to run in new fedora-20-x64 template:
~~~
sudo yum --releasever=20 distro-sync
poweroff
~~~
If you have installed a lot of software in your template, it may happen that you don't have enough disk space for upgrade. Yum will tell you this just after confirming the operation (before it change anything to your system). In that case you need to provide some "external" place for yum cache (uses about 2GB during upgrade). For example attach virtual disk stored in some file. Prepare the file in dom0:
~~~
truncate -s 5GB /var/tmp/template-upgrade-cache.img
qvm-block -A fedora-20-x64 dom0:/var/tmp/template-upgrade-cache.img
~~~
Then use it in template:
~~~
sudo mkfs.ext4 /dev/xvdi
sudo mount /dev/xvdi /mnt/removable
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.
**If you have at least `qubes-core-dom0-2.1.68` installed, you can use `qvm-trim-template` tool. Otherwise use instructions below.**
You can compact root.img in the "old way", you'll need about 15GB (template's max size + really used space there) in dom0 for this operation: Start the template, fill all the free space with zeros, for example with:
~~~
dd if=/dev/zero of=/var/tmp/zero
(wait for "No space left on device" error)
rm -f /var/tmp/zero
~~~
Then shutdown template and all VMs based on it. Go into template directory in dom0 (/var/lib/qubes/vm-templates/fedora-20-x64 or so) and issue:
~~~
cp --sparse=always root.img root.img.new
mv root.img.new root.img
~~~
Done.

223
en/managing-os/FedoraTemplateUpgrade-20.md Normal file
View file

@ -0,0 +1,223 @@
---
layout: doc
title: FedoraTemplateUpgrade
permalink: /en/doc/fedora-template-upgrade-20/
redirect_from:
- /doc/FedoraTemplateUpgrade20/
- /wiki/FedoraTemplateUpgrade20/
---
How to Upgrade Fedora Templates
===============================
Summary: Upgrading the Standard Fedora 20 Template to Fedora 21
---------------------------------------------------------------
[user@dom0 ~]$ qvm-clone fedora-20-x64 fedora-21
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-21 gnome-terminal
[user@dom0 ~]$ qvm-block -A fedora-21 dom0:/var/tmp/template-upgrade-cache.img
[user@fedora-21 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-21 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-21 ~]$ sudo mkdir /mnt/removable/modules
[user@fedora-21 ~]$ sudo cp -rp /usr/lib/modules /mnt/removable/modules
[user@fedora-21 ~]$ sudo mount --bind /mnt/removable/modules /usr/lib/modules
[user@fedora-21 ~]$ sudo yum erase nautilus-actions libcacard
[user@fedora-21 ~]$ sudo yum clean all
[user@fedora-21 ~]$ sudo yum --releasever=21 --setopt=cachedir=/mnt/removable distro-sync
[user@fedora-21 ~]$ sudo cp /usr/lib/qubes/init/ip* /etc/sysconfig/
(Shut down TemplateVM via Qubes VM Manager; may need to be killed.)
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-run -a fedora-21 gnome-terminal
[user@fedora-21 ~]$ sudo yum -y update
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-21
Detailed: Upgrading the Standard Fedora 20 Template to Fedora 21
----------------------------------------------------------------
These instructions will show you how to upgrade the standard Fedora 20
TemplateVM to Fedora 21. The same general procedure may be used to upgrade any
template based on the standard Fedora 20 template.
1. Clone the existing template and start a terminal in the new template.
[user@dom0 ~]$ qvm-clone fedora-20-x64 fedora-21
[user@dom0 ~]$ qvm-run -a fedora-21 gnome-terminal
2. Attempt the upgrade process in the new template.
[user@fedora-21 ~]$ sudo yum erase nautilus-actions libcacard
[user@fedora-21 ~]$ sudo yum clean all
[user@fedora-21 ~]$ sudo yum --releasever=21 distro-sync
[user@fedora-21 ~]$ sudo cp /usr/lib/qubes/init/ip* /etc/sysconfig/
(Shut down TemplateVM via Qubes VM Manager; may need to be killed.)
If you encounter no errors, proceed to step 7.
3. If `yum` 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-21 dom0:/var/tmp/template-upgrade-cache.img
Then reattempt the upgrade process, but this time using the virtual disk as
a cache.
[user@fedora-21 ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-21 ~]$ sudo mount /dev/xvdi /mnt/removable
[user@fedora-21 ~]$ sudo yum erase nautilus-actions libcacard
[user@fedora-21 ~]$ sudo yum clean all
[user@fedora-21 ~]$ sudo yum --releasever=21 --setopt=cachedir=/mnt/removable distro-sync
[user@fedora-21 ~]$ sudo cp /usr/lib/qubes/init/ip* /etc/sysconfig/
(Poweroff via Qubes VM Manager. May need to be killed.)
4. If `yum` complains that there is not enough free space in `/usr/lib/modules`,
do this before reattempting the upgrade:
[user@fedora-21 ~]$ sudo mkdir /mnt/removable/modules
[user@fedora-21 ~]$ sudo cp -rp /usr/lib/modules /mnt/removable/modules
[user@fedora-21 ~]$ sudo mount --bind /mnt/removable/modules /usr/lib/modules
5. `yum` 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](/doc/ResizeDiskImage/) before reattempting the upgrade process.
(See **Additional Information** below for other options.)
6. After the upgrade process is finished, remove the cache file, if you
created one.
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
7. Ensure your new template is fully updated.
[user@dom0 ~]$ qvm-run -a fedora-21 gnome-terminal
[user@fedora-21 ~]$ sudo yum -y update
8. Trim the new template (see **Compacting the Upgraded Template** for details
and other options).
[user@dom0 ~]$ qvm-trim-template fedora-21
9. (Optional) Remove the old default template.
[user@dom0 ~]$ sudo yum remove qubes-template-fedora-20-x64
Summary: Upgrading the Minimal Fedora 20 Template to Fedora 21
--------------------------------------------------------------
[user@dom0 ~]$ qvm-clone fedora-20-x64-minimal fedora-21-minimal
[user@dom0 ~]$ qvm-run -a fedora-21-minimal xterm
[user@fedora-21-minimal ~]$ su -
[root@fedora-21-minimal ~]# yum clean all
[user@fedora-21-minimal ~]# yum --releasever=21 distro-sync
[user@fedora-21-minimal ~]# cp /usr/lib/qubes/init/ip* /etc/sysconfig/
(Shut down the TemplateVM via Qubes VM Manager. May need to be killed.)
[user@dom0 ~]$ qvm-run -a fedora-21-minimal xterm
[user@fedora-21-minimal ~]$ su -
[root@fedora-21-minimal ~]# yum -y update
(Shut down TemplateVM by any normal means.)
[user@dom0 ~]$ qvm-trim-template fedora-21-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. `nautilus-actions` and `libcacard` are not installed by default, so do not
try to erase them (unless you've installed them).
3. `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.
If you have at least `qubes-core-dom0-2.1.68` installed and are on Qubes R2,
you can use the `qvm-trim-template` tool:
[user@dom0 ~]$ qvm-trim-template fedora-21
If you do not have `qubes-core-dom0-2.1.68` or are on Qubes R3-rc1, you can
compact the `root.img` manually. To do this, you will need about 15GB (the
TemplateVM's max size + the actually used space there) free space in dom0.
1. Start the template and fill all the free space with zeros, for example
with:
[user@fedora-21 ~]$ dd if=/dev/zero of=/var/tmp/zero
2. Wait for the "No space left on device" error. Then:
[user@fedora-21 ~]$ rm -f /var/tmp/zero
3. Shut down the template and all VMs based on it. Then:
[user@dom0 ~]$ cd /var/lib/qubes/vm-templates/fedora-21
[user@dom0 ~]$ cp --sparse=always root.img root.img.new
[user@dom0 ~]$ mv root.img.new root.img
Additional Information
======================
As mentioned above, you may encounter the following `yum` 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](/en/doc/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`. It should be easy to
extend the `qvm-grow-root` tool in order to support PV (and not only HVM)
VMs. However, someone would need to do this (patches welcome).
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)
Known issues with Fedora 21
===========================
* [The "Update VM" command in Qubes Manager does not work](https://github.com/QubesOS/qubes-issues/issues/982).

311
en/managing-os/HvmCreate.md Normal file
View file

@ -0,0 +1,311 @@
---
layout: doc
title: HvmCreate
permalink: /en/doc/hvm-create/
redirect_from:
- /doc/HvmCreate/
- /wiki/HvmCreate/
---
Creating and using HVM (fully virtualized) domains in Qubes 2
=============================================================
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.
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).
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):
~~~
qvm-create win7 --hvm --label green
~~~
(Of course, the name of the domain ("win7"), as well as it's label ("green"), are just exemplary).
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):
~~~
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`:
~~~
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.
[![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:
~~~
--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):
~~~
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).
![r2b1-installing-ubuntu-1.png](/attachment/wiki/HvmCreate/r2b1-installing-ubuntu-1.png)
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).
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.
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.
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.
Now, one should configure the networking within the HVM according to those settings (IP/netmask/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).
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.
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:
~~~
[joanna@dom0 ~]$ qvm-prefs win7
name : win7
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7
config : /var/lib/qubes/appvms/win7/win7.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7/root.img
private img : /var/lib/qubes/appvms/win7/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
[joanna@dom0 ~]$ qvm-clone win7 win7-copy
/.../
[joanna@dom0 ~]$ qvm-prefs win7-copy
name : win7-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7-copy
config : /var/lib/qubes/appvms/win7-copy/win7-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7-copy/root.img
private img : /var/lib/qubes/appvms/win7-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:01 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
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:
~~~
[joanna@dom0 ~]$ qvm-ls -n
/.../
win7-copy | | Halted | Yes | | *firewallvm | green | 10.137.2.3 | n/a | 10.137.2.1 |
win7 | | Halted | Yes | | *firewallvm | green | 10.137.2.7 | n/a | 10.137.2.1 |
/.../
~~~
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
[joanna@dom0 ~]$ qvm-prefs win7-copy
name : win7-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/win7-copy
config : /var/lib/qubes/appvms/win7-copy/win7-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/win7-copy/root.img
private img : /var/lib/qubes/appvms/win7-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
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~~ (only for R2 Beta 2)
------------------------------------------------------------------------
Note: the R2 Beta 3 (which is coming soon) has automated most of the actions described below -- please see [this page instead](/en/doc/windows-appvms/).
Qubes support tools for Windows VMs is a set of programs and drivers that provide integration of Windows VMs with the rest of the Qubes system. Currently the following features become available for Windows VMs after installation of those tools:
- Support for [secure clipboard copy/paste](/en/doc/copy-paste/) between the Windows VM and other AppVMs
- Support for [secure file exchange](/en/doc/copying-files/) between the Windows VM and other AppVMs
- Support for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- Xen PV drivers for Windows that increase performance compared to qemu emulated devices
Features that are currently not supported, but are planned for future releases (as soon as R2 Beta 2):
- Video driver for Windows allowing custom resolutions (arbitrary HVM window resizing) and VM's mouse cursor hiding
- Seamless app window mode, in which application windows are extracted and composed onto a common desktop just like it's currently done for Linux AppVMs. Currently Windows HVMs run in a window that contains the whole desktop of the VM.
Qubes Windows Support Tools are not open source and are distributed under a commercial license and their source code is not publicly available.
Because the Windows Support Tools are not licensed under a GPL license they are not distributed with Qubes installation ISO. Instead, one can download them when needed using the standard Qubes command for installing software in Dom0:
~~~
sudo qubes-dom0-update qubes-windows-tools
~~~
This should install `qubes-windows-tools-*.rpm` in your system, a package that brings an ISO with Windows Support Tools:
~~~
[joanna@dom0 ~]$ rpm -ql qubes-windows-tools-1-201211301354.noarch
/usr/lib/qubes/qubes-windows-tools-201211301354.iso
~~~
Now, in order to install the tools in a Windows VM one should start the VM with the ISO attached:
~~~
qvm-start lab-win7 --cdrom=/usr/lib/qubes/qubes-windows-tools-201211301354.iso
~~~
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:
[![r2b1-win7-installing-qubes-tools-1.png](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-1.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-1.png)
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently the drivers we provide as part of the Windows Support 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, and also to accept a few scary looking warning windows during the installation process, as shown below.
[![r2b1-win7-installing-qubes-tools-2.png](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-2.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-2.png)
[![r2b1-win7-installing-qubes-tools-4.png](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-4.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-4.png)
[![r2b1-win7-installing-qubes-tools-5.png](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-5.png)](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-5.png)
After successful installation, the Windows VM must be shut down.
Additionally, once should inform Qubes that tools have been installed in this VM by setting the `qrexec_installed` flag in the VM's properties -- this can be done using the `qvm-prefs` command in Dom0, e.g.:
~~~
qvm-prefs lab-win7 -s qrexec_installed true
~~~
Also, by default Qubes assumes that the default user in the Windows VM is named `user` -- if one has chosen a different user during Windows installation, Qubes should be informed about this by setting the `default_user` property for the VM, e.g.:
~~~
qvm-prefs lab-win7 -s default_user joanna
~~~
If everything went fine (please remember about the need to reboot the Windows VM after installation of the tools), one can run some simple tests to see if qrexec service runs fine with this VM, e.g.:
~~~
qvm-run lab-win7 calc
~~~
... or something more fancy (a "networkless" telnet to Windows ;):
~~~
[joanna@dom0 ~]$ qvm-run lab-win7 -p cmd.exe
Microsoft Windows [Version 6.1.7601]
Copyright (c) 2009 Microsoft Corporation. All rights reserved.
C:\Windows\system32>dir c:\
dir c:\
Volume in drive C has no label.
Volume Serial Number is 64FB-0198
Directory of c:\
08/26/2012 12:06 PM <DIR> DRIVERS
12/12/2012 03:36 PM <DIR> Program Files
10/25/2012 12:12 PM <DIR> Program Files (x86)
03/22/2012 02:50 PM <DIR> SWTOOLS
03/02/2012 12:22 AM <DIR> Users
12/12/2012 03:40 PM <DIR> Windows
0 File(s) 0 bytes
6 Dir(s) 1,432,260,608 bytes free
C:\Windows\system32>exit
exit
~~~
Another things to check are if clipboard copy/paste and file copy works fine with this VM. If it doesn't, then perhaps one more VM reboot is necessary (seriously, hey this is Windows!).
And the screenshot below illustrates the Send To entries in a Windows VM that can be used to copy/send files to other Qubes domains:
[![win7-sendto-another-vm.png](/attachment/wiki/HvmCreate/win7-sendto-another-vm.png)](/attachment/wiki/HvmCreate/win7-sendto-another-vm.png)
Assigning PCI devices to HVM domains
------------------------------------
HVM domains (including Windows VMs) can be [assigned PCI devices](/en/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:
[![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
Further reading
---------------
Other documents related to HVM:
- [LinuxHVMTips](/en/doc/linux-hvm-tips/)

58
en/managing-os/LinuxHvmTips.md Normal file
View file

@ -0,0 +1,58 @@
---
layout: doc
title: LinuxHVMTips
permalink: /en/doc/linux-hvm-tips/
redirect_from:
- /doc/LinuxHVMTips/
- /wiki/LinuxHVMTips/
---
Tips for Linux in HVM domain
============================
Screen resolution
-----------------
Some kernel/Xorg combination use only 640x480 in HVM, which is quite small. To enable maximum resolution, some changes in Xorg configuration are needed:
1. Force "vesa" video driver
2. Provide wide horizontal synchronization range
To achieve it (all commands run as root):
1. Generate XOrg configuratio (if you don't have it):
~~~
X -configure :1 && mv ~/xorg.conf.new /etc/X11/xorg.conf
~~~
2. Add HorizSync line to Monitor section, it should look something like:
~~~
Section "Monitor"
Identifier "Monitor0"
VendorName "Monitor Vendor"
ModelName "Monitor Model"
HorizSync 30.0 - 60.0
EndSection
~~~
3. Change driver to "vesa" in Device section:
~~~
Section "Device"
# (...)
Identifier "Card0"
Driver "vesa"
VendorName "Technical Corp."
BoardName "Unknown Board"
BusID "PCI:0:2:0"
EndSection
~~~
Now you should get at least 1280x1024 and be able to choose other modes.
Qubes agents
------------
Linux Qubes agents are written with PV domain in mind, but it looks to be possible to run them also in HVM domain. However some work is required to achieve it. Check [this thread](https://groups.google.com/group/qubes-devel/browse_thread/thread/081df4a43e49e7a5).

52
en/managing-os/Templates.md Normal file
View file

@ -0,0 +1,52 @@
---
layout: doc
title: Templates
permalink: /en/doc/templates/
redirect_from:
- /doc/Templates/
- /wiki/Templates/
---
Templates
=========
Every AppVM in Qubes is based on some template, this is where all the software
available for AppVMs is installed. Default template is based on Fedora, but
there are additional templates based on other Linux distributions, or with some
additional software installed by default. This concept is described
[here](/doc/GettingStarted/#appvms-domains-and-templatevms).
Some templates are available in ready to use binary form, but some of them are
only as a source code, which can be built using [Qubes Builder](/en/doc/qubes-builder/).
Especially some templates "flavors" are available in source code form only.
Take a look at [Qubes Builder
documentation](https://github.com/QubesOS/qubes-builder/blob/master/README.md)
how to compile them.
ITL Supported templates
-----------------------
For those templates ITL is responsible for build and releasing updates,
especially ITL guarantees that the binary updates are compiled from exactly
the source code we publish.
- Fedora
- [Fedora - Minimal](/doc/Templates/FedoraMinimal)
- [Debian](/en/doc/templates/debian/)
Community Supported templates
-----------------------------
Those templates are supported by Qubes Community. Some of them are available in
ready to use binary package (built by ITL), some are only in source code form.
In any case ITL does not provide updates for those templates, but such updates
can be provided by template maintainer.
In short - by installing those templates, you trust not only ITL and
distribution maintainers, but also the template maintainer. It can also happen
that those templates are somehow less stable, because we do not test them.
- [Whonix](/en/doc/templates/whonix/)
- [Ubuntu](/en/doc/templates/ubuntu/)
- [Archlinux](/en/doc/templates/archlinux/)

41
en/managing-os/Templates/Archlinux.md Normal file
View file

@ -0,0 +1,41 @@
---
layout: doc
title: Archlinux template
permalink: /en/doc/templates/archlinux/
redirect_from:
- /doc/Templates/Archlinux/
- /wiki/Templates/Archlinux/
---
Archlinux template
===============
Archlinux template is one of the templates made by Qubes community. It should
be considered experimental as Qubes developers team use mainly Fedora-based VMs
to test new features/updates.
Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
He also provides binary updates for the template, which are signed using this
key:
pub 2048R/C1833B9C 2014-03-27 [expires: 2016-03-26]
Key fingerprint = D85E E12F 9678 51CC F433 515A 2043 E7AC C183 3B9C
uid Olivier MEDOC (Qubes-OS signing key) <o_medoc@yahoo.fr>
Install
-------
Currently we do not ship ready to use binary package. It can be compiled using
[this instructions](/en/doc/building-archlinux-template/).
Olivier provides binary package build by himself, you can get it for:
* Qubes R2 [here](https://groups.google.com/d/msgid/qubes-devel/54CE3FB1.3050708%40yahoo.fr).
* Qubes R3 [here](https://groups.google.com/d/msg/qubes-users/RI3KQVEEc30/h5nsNw_SHTQJ)
Known issues
------------
If you want to help in improving the template, feel free to [contribute](/en/doc/contributing/).

47
en/managing-os/Templates/Debian.md Normal file
View file

@ -0,0 +1,47 @@
---
layout: doc
title: Debian
permalink: /en/doc/templates/debian/
redirect_from:
- /doc/Templates/Debian/
- /wiki/Templates/Debian/
---
Debian template(s)
===============
If you like to use Debian Linux distribution in your AppVMs, you can install one of available Debian templates.
Updates for this template are provided by ITL and are signed by this key:
pub 4096R/47FD92FA 2014-07-27
Key fingerprint = 2D43 E932 54EE EA7C B31B 6A77 5E58 18AB 47FD 92FA
uid Qubes OS Debian Packages Signing Key
The key is already installed when you install (signed) template package. You
can also obtain the key from [git
repository](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes-archive-keyring.gpg),
which is also integrity-protected using signed git tags.
Install
-------
It can be installed via the following command:
Debian 7 (wheezy) - old stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-7
Debian 8 (jessie) - stable:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-8
Debian 9 (stretch) - testing:
A prebuilt template is not yet available, but you can build an experimental stretch template from source.
Known issues
------------
If you want to help in improving the template, feel free to [contribute](/wiki/ContributingHowto).

78
en/managing-os/Templates/FedoraMinimal.md Normal file
View file

@ -0,0 +1,78 @@
---
layout: doc
title: FedoraMinimal
permalink: /en/doc/templates/fedora-minimal/
redirect_from:
- /doc/Templates/FedoraMinimal/
- /wiki/Templates/FedoraMinimal/
---
Fedora - minimal
================
We have uploaded a new "minimal" template to our templates-itl repo. The template weighs only 150MB and has most of the stuff cut off, except for minimal X and xterm.
More into in ticket \#828
Install
-------
It can be installed via the following command:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-21-minimal
~~~
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-21-minimal <your new template name>
~~~
The sudo package is not installed by default, so let's install it:
~~~
[user@F21-Minimal ~]$ su -
[user@F21-Minimal ~]$ yum 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 yum install NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tar tinyproxy
~~~
And maybe some more optional but useful packages as well:
~~~
[user@F21-Minimal ~]$ sudo yum 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; yum 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 ready to use for a standard firewall VM.
#### VPN
The needed packages depend on the VPN technology. The `yum search "NetworkManager VPN plugin"` command may help you to choose the right one.
[More details about setting up a VPN Gateway](/wiki/VPN#ProxyVM)
#### TOR
[UserDoc/TorVM](/wiki/UserDoc/TorVM)

35
en/managing-os/Templates/Ubuntu.md Normal file
View file

@ -0,0 +1,35 @@
---
layout: doc
title: Ubuntu
permalink: /en/doc/templates/ubuntu/
redirect_from:
- /doc/Templates/Ubuntu/
- /wiki/Templates/Ubuntu/
---
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
available in ready to use binary packages, because Canonical does not allow
to redistribute 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).
Install
-------
It can built using [Qubes Builder](/en/doc/qubes-builder/). You can also access its
documentation in the [source code
repository](https://github.com/QubesOS/qubes-builder/blob/master/README.md).
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
------------
If you want to help in improving the template, feel free to
[contribute](/wiki/ContributingHowto).

20
en/managing-os/Templates/Whonix.md Normal file
View file

@ -0,0 +1,20 @@
---
layout: doc
title: Whonix template
permalink: /en/doc/templates/whonix/
redirect_from:
- /doc/Templates/Whonix/
- /wiki/Templates/Whonix/
---
Whonix template(s)
==================
Whonix is an operating system focused on anonymity, privacy and security. It's
based on the Tor anonymity network, Debian GNU/Linux and security by isolation.
Its primary isolation mechanism is VirtualBox, but now it is also possible to
run it on top of Qubes OS!
Whonix template(s) are another Qubes community contribution. Currently Whonix actively maintains those templates.
More details, including installation instructions on [Whonix Qubes web page](https://www.whonix.org/wiki/Qubes).

125
en/managing-os/UninstallingWindowsTools-2.md Normal file
View file

@ -0,0 +1,125 @@
---
layout: doc
title: UninstallingWindowsTools2
permalink: /en/doc/uninstalling-windows-tools-2/
redirect_from:
- /doc/UninstallingWindowsTools2/
- /wiki/UninstallingWindowsTools2/
---
Uninstalling Qubes Tools for Windows v2.x
=========================================
**Do not try to uninstall Qubes Tools for Windows (QTW) 2.x from Windows Control Panel. It will render your HVM unbootable and will require manual fixing.**
Preface
-------
Version 2.x of QTW (used for Windows HVMs in Qubes R2) is difficult to uninstall due to issues with the Xen GPL PV drivers package that is used. However, uninstalling QTW version 2.x is required to migrate the HVM to Qubes R3.
HVMs with QTW 2.x *will not boot normally in Qubes R3* due to Xen drivers failing. They will boot in Safe Mode. It's easier to uninstall QTW 2.x from Qubes R2, but if that's not an option it's also possible in Qubes R3 (just a bit more complicated). Details below.
Uninstalling QTW 2.x in Qubes R2
--------------------------------
1. Copy the uninstall script posted at the end of this document and save it in the HVM as a .BAT file.
2. Reboot the HVM in Safe Mode: type `bcdedit /set safeboot minimal` in a command prompt with admin privileges then restart normally. The OS will now always start in Safe Mode until the setting is reverted.
3. In Safe Mode execute the uninstall script from step 1.
4. Open Device Manager. Manually uninstall Qubes Video device (in 'Display adapters') and Xen PCI driver (in 'System devices'). This will prevent the (already removed) devices from showing up.
5. Type `bcdedit /deletevalue safeboot` in a command prompt to disable Safe Mode boot.
6. Reboot. Open Device Manager and verify that there are no active Xen PV devices:
- There should be one unidentified PCI device in System devices (this is the Xen PV device, not functioning because PV drivers are inactive).
- Disk drives should be QEMU (emulated).
- Network adapter should be Realtek (emulated).
Now you can backup the HVM, migrate it to Qubes R3 and install QTW 3.x there.
Uninstalling QTW 2.x in Qubes R3
--------------------------------
HVMs with QTW 2.x will not boot normally in Qubes R3 due to the old Xen drivers failing. If removing QTW from Qubes R2 is not an option (see above) then you will need to boot the HVM in Safe Mode.
### Preparation in dom0
Disable VM tools in VM's preferences:
* `qvm-prefs -s vmname qrexec_installed false`
* `qvm-prefs -s vmname guiagent_installed false`
### Enabling Safe Mode
* If you're quick you can mash F8 just as the HVM boots to access Windows' advanced boot options. The timing for it is very tight though. If you manage to get the boot menu, select Safe Mode boot.
* Alternatively, allow the HVM to (try to) boot. It will crash with a BSOD.
* After the crash start the HVM again. Now Windows will display the recovery menu which, for some unknown reason, does not include Safe Mode boot option. We need to try harder.
* Select **Launch Startup Repair**.
* If you're prompted to try System Restore, **don't**. Hit cancel.
* Grab a drink or read a book while Windows tries to do something but ultimately the repair process fails.
* *Now* you're presented with a choice of *advanced options* that include a command prompt. Why isn't this available from the start?
* Launch the command prompt, log in and type `bcdedit /set {default} safeboot minimal`. The OS will now always start in Safe Mode until the setting is reverted.
* Reboot and proceed with the uninstallation instructions from the previous paragraph (*Uninstalling QTW 2.x in Qubes R2*).
If you need network access to copy the uninstall script to the HVM, use *Safe Mode with Networking* instead of pure Safe Mode (replace `minimal` with `network` in the bcdedit commands above). Disable the Xen PV network device first. You may need to manually configure IP settings for the emulated Realtek adapter.
The uninstall script
====================
Save it as a .BAT file in the HVM and run in Safe Mode.
~~~
@echo off
:: This batch file uninstalls Qubes Tools for Windows version 2.x
:: Needs to be run in safe mode
:: Registry cleanup
reg delete "HKLM\Software\Invisible Things Lab" /f
:: services/drivers
reg delete HKLM\System\CurrentControlSet\Services\ShutdownMon /f
reg delete HKLM\System\CurrentControlSet\Services\QrexecAgent /f
reg delete HKLM\System\CurrentControlSet\Services\QTWHelper /f
reg delete HKLM\System\CurrentControlSet\Services\QubesNetworkSetup /f
reg delete HKLM\System\CurrentControlSet\Services\QVideo /f
reg delete HKLM\System\CurrentControlSet\Services\XenNet /f
reg delete HKLM\System\CurrentControlSet\Services\XenPCI /f
reg delete HKLM\System\CurrentControlSet\Services\XenVbd /f
:: xenpci filter entries
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E96A-E325-11CE-BFC1-08002BE10318} /v UpperFilters /f
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002bE10318} /v UpperFilters /f
reg delete HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E97B-E325-11CE-BFC1-08002BE10318} /v UpperFilters /f
:: files
rmdir /q /s "%ProgramFiles%\Invisible Things Lab"
rmdir /q /s "%ProgramFiles%\Xen PV Drivers"
del /q /s "%windir%\system32\move-profiles.exe"
del /q /s "%windir%\system32\windows-utils.dll"
del /q /s "%windir%\system32\qvgdi.dll"
del /q /s "%windir%\system32\drivers\qvmini.sys"
del /q /s "%windir%\system32\drivers\xennet.sys"
del /q /s "%windir%\system32\drivers\xenpci.sys"
del /q /s "%windir%\system32\drivers\xenvbd.sys"
:: driver store entries
FOR /F "delims=. tokens=1" %%I IN ('DIR /B "%SYSTEMROOT%\INF\OEM*.INF"') DO (
TYPE "%SYSTEMROOT%\INF\%%I.inf" | FIND /c /i "Xen GPL PV" >%TEMP%\qtwuninstall
FOR /f %%c IN (%TEMP%\qtwuninstall) DO (
IF /I %%c NEQ 0 (
DEL "%SYSTEMROOT%\INF\%%I.inf"
DEL "%SYSTEMROOT%\INF\%%I.pnf"
)
)
)
FOR /F "delims=. tokens=1" %%I IN ('DIR /B "%SYSTEMROOT%\INF\OEM*.INF"') DO (
TYPE "%SYSTEMROOT%\INF\%%I.inf" | FIND /c /i "Qubes" >%TEMP%\qtwuninstall
FOR /f %%c IN (%TEMP%\qtwuninstall) DO (
IF /I %%c NEQ 0 (
DEL "%SYSTEMROOT%\INF\%%I.inf"
DEL "%SYSTEMROOT%\INF\%%I.pnf"
)
)
)
echo.
echo Cleanup finished. Please manually uninstall Qubes Video and Xen devices from the Device Manager.
~~~

117
en/managing-os/WindowsAppvms.md Normal file
View file

@ -0,0 +1,117 @@
---
layout: doc
title: WindowsAppVms
permalink: /en/doc/windows-appvms/
redirect_from:
- /doc/WindowsAppVms/
- /wiki/WindowsAppVms/
---
Installing and using Windows-based AppVMs
=========================================
Qubes provides special support for running Windows-based AppVMs. This requires the user to install Windows 7 x64 in a Qubes VM and subsequently install Qubes Windows Support tools inside the VM. This page describes this process in detail.
Qubes support tools for Windows is a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools:
- Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop (available on Qubes R2 Beta 3 and later)
- Support for [secure clipboard copy/paste](/en/doc/copy-paste/) between the Windows VM and other AppVMs
- Support for [secure file exchange](/en/doc/copying-files/) between the Windows VM and other AppVMs
- Support for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- Xen PV drivers for Windows that increase performance compared to qemu emulated devices
Qubes Windows Support Tools are not open source and are distributed under a commercial license and their source code is not publicly available. Current status is: **Beta**.
NOTE: Currently only 64-bit versions of Windows 7 are support by Qubes Windows Tools.
Installing Windows OS in a Qubes VM
-----------------------------------
Please refer to [this page](/en/doc/hvm-create/) for instructions on how to install Windows in a Qubes VM.
Installing Qubes support tools in Windows 7 VMs
-----------------------------------------------
First, make sure that `qubes-windows-tools` is installed in your system:
~~~
sudo qubes-dom0-update qubes-windows-tools
~~~
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 even though the Qubes Windows Tools are proprietary, 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.
To install the Qubes Windows support tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
~~~
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 Support 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, and also to accept a few scary looking warning windows during the installation process, as shown below.
![r2b1-win7-installing-qubes-tools-5.png](/attachment/wiki/HvmCreate/r2b1-win7-installing-qubes-tools-5.png)
After successful installation, the Windows VM must be shut down and started again.
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:
~~~
qvm-prefs <your-appvm-name>
~~~
Using Windows AppVMs in seamless mode (Qubes R2 Beta 3 and later)
-----------------------------------------------------------------
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
~~~
qvm-run -a my-win7-appvm explorer.exe
~~~
![windows-seamless-4.png](/attachment/wiki/WindowsAppVms/windows-seamless-4.png) ![windows-seamless-1.png](/attachment/wiki/WindowsAppVms/windows-seamless-1.png)
Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM:
~~~
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
~~~
~~~
[user@work ~]$ qvm-open-in-vm work-win7 http://www.invisiblethingslab.com
~~~
... just like in case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy
Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM.
To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground.
![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png)
Forcing Windows AppVM into full desktop mode
--------------------------------------------
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager.
Using template-based Windows AppVMs (Qubes R2 Beta 3 and later)
---------------------------------------------------------------
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just like it is done for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM). In order to create a HVM TemplateVM one can use the following command:
~~~
qvm-create --hvm-template win7-x64-template -l green
~~~
... and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see [this page](/en/doc/hvm-create/) instructions. However, it would make lots of sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs. This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically. To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`. It's a selectable feature of the installer, enabled by default. If that feature is selected during installation, completion of the process requires two reboots:
- 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).
Once the template has been created and installed it is easy to create AppVMs based on:
~~~
qvm-create --hvm <new windows appvm name> --template <name of template vm> --label <label color>
~~~

103
en/managing-os/WindowsTools-2.md Normal file
View file

@ -0,0 +1,103 @@
---
layout: doc
title: WindowsTools2
permalink: /en/doc/windows-tools-2/
redirect_from:
- /doc/WindowsTools2/
- /wiki/WindowsTools2/
---
Qubes Tools for Windows: advanced settings and troubleshooting
==============================================================
**This document only applies to Qubes R2 (tools version 2.x)**
*Only 64-bit Windows 7 (any edition) is supported currently. Windows 8+ support is under development.*
Installable components
----------------------
Qubes Tools for Windows (QTW for short) contain several components than can be enabled or disabled during installation:
- Xen GPL PV drivers (required): drivers for the hardware exposed by Xen.
- Core Windows Agent: qrexec agent and services. Needed for proper integration with Qubes.
- Move user profiles: User profiles directory (c:\\Users) will be moved into the private disk backed by private.img. This disk will be initialized/formatted automatically if needed. This feature is useful for Windows-based HVM templates, so child AppVMs can have their separate user profiles.
- GUI Windows Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
- Disable UAC: disables User Account Control prompts. *Is this still needed/wanted? Gui agent can handle UAC prompts now.*
**In testing VMs only** it's probably a good idea to install a VNC server before installing QTW. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
Verbose installation
--------------------
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):
`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt`
Uninstalling
------------
See [this page](/en/doc/uninstalling-windows-tools-2/).
Configuration
-------------
Starting from version 2.2.\* various aspects of Qubes Tools for Windows can be configured through registry. Main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QTW components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes OS Windows Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
||
|0|Error|Serious errors that most likely cause irrecoverable failures|
|1|Warning|Unexpected but non-fatal events|
|2|Info|Useful information|
|3|Debug|Internal state dumps for troubleshooting|
|4|Verbose|Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension. For example, to change qrexec-agent's log level to Debug, set it like this:
![qtw-log-level.png](/attachment/wiki/WindowsTools/qtw-log-level.png)
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|wga|UseDirtyBits|DWORD|Enable experimental feature of the gui agent/qvideo driver: use page table dirty bits to determine changed display regions. This can improve performance but may impact display responsiveness (some changes may not be detected resulting in "stale" image). Needs VM restart to apply change.|0|
|wga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since wga is restarted on desktop change).|1|
Troubleshooting
---------------
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `qvm-start --debug vmname`
- mash F8 on the boot screen to enable boot options and select Safe Mode (optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QTW version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events.
If a specific component is malfunctioning, you can increase it's log verbosity as explained above to get more troubleshooting information. Below is a list of components:
||
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|wga|Gui agent.|
|QTWHelper|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (ctrl-alt-del).|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QTW setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|move-profiles|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `c:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
Updates
-------
When we publish new QTW version (which is announced on `qubes-users` Google Group) it's usually pushed to the `current-testing` repository first. To use versions from current-testing, run this in dom0:
`qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools`
That command will download a new QTW .iso from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.

109
en/managing-os/WindowsTools-3.md Normal file
View file

@ -0,0 +1,109 @@
---
layout: doc
title: WindowsTools
permalink: /en/doc/windows-tools-3/
redirect_from:
- /doc/WindowsTools3/
- /wiki/WindowsTools/
redirect_from:
-
- /doc/WindowsTools/
---
Qubes Tools for Windows: advanced settings and troubleshooting
==============================================================
**This document only applies to Qubes R3 (tools version 3.x)**
*Only 64-bit Windows 7 (any edition) is supported currently. Windows 8+ support is under development.*
*HVM templates are not supported yet. Specifically, user profiles are not yet moved to a VM's private image (fix incoming).*
Installable components
----------------------
Qubes Tools for Windows (QTW for short) contain several components than can be enabled or disabled during installation:
- Shared components (required): common libraries used by QTW components.
- Xen PV drivers: drivers for the virtual hardware exposed by Xen.
- Base Xen PV Drivers (required): paravirtual bus and interface drivers.
- Xen PV Disk Drivers: paravirtual storage drivers.
- Xen PV Network Drivers: paravirtual network drivers.
- Qubes Core Agent: qrexec agent and services. Needed for proper integration with Qubes.
- Qubes GUI Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
**In testing VMs only** it's probably a good idea to install a VNC server before installing QTW. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
Verbose installation
--------------------
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):
`msiexec /i path-to-qubes-tools.msi /lv path-to-log-file.txt`
Uninstalling QTW 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.
Configuration
-------------
Starting from version 2.2.\* various aspects of Qubes Tools for Windows can be configured through registry. Main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QTW components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
||
|0|Error|Serious errors that most likely cause irrecoverable failures|
|1|Warning|Unexpected but non-fatal events|
|2|Info|Useful information|
|3|Debug|Internal state dumps for troubleshooting|
|4|Verbose|Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension. For example, to change qrexec-agent's log level to Debug, set it like this:
![qtw-log-level.png](/attachment/wiki/WindowsTools/qtw-log-level.png)
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|qga|UseDirtyBits|DWORD|Enable experimental feature of the gui agent/qvideo driver: use page table dirty bits to determine changed display regions. This can improve performance but may impact display responsiveness (some changes may not be detected resulting in "stale" image). Needs VM restart to apply change.|0|
|qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
Troubleshooting
---------------
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `qvm-start --debug vmname`
- mash F8 on the boot screen to enable boot options and select Safe Mode (optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QTW version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from c:\Windows.
Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
If a specific component is malfunctioning, you can increase it's log verbosity as explained above to get more troubleshooting information. Below is a list of components:
||
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|qga|Gui agent.|
|QgaWatchdog|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (ctrl-alt-del).|
|qubesdb-daemon|Service for accessing Qubes configuration database.|
|network-setup|Service that sets up network parameters according to VM's configuration.|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QTW setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|move-profiles|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `c:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
Updates
-------
When we publish new QTW version (which is announced on `qubes-users` Google Group) it's usually pushed to the `current-testing` or `unstable` repository first. To use versions from current-testing, run this in dom0:
`qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools`
That command will download a new QTW .iso from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.

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