Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'upstream'

Browse Source
This commit is contained in:
Brennan Novak 2015-10-20 21:29:20 -07:00
commit 25a2fc02e7
207 changed files with 5430 additions and 4351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
BackupEmergencyRestoreV3.md
View File

@ -1,94 +0,0 @@
---
layout: doc
title: Emergency Backup Recovery - format version 3
permalink: /doc/BackupEmergencyRestoreV3/
---
Emergency Backup Recovery without Qubes - format version 3
==========================================================
This page describes how to perform emergency restore of backup created on Qubes R2 or later (which uses backup format 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 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 `backup-header` file contains basic information about your backup.
[user@restore ~]$ cd vm1/
[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. A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
1. Read the `backup-header`. You'll need some of this information later. The file will look similar to this:
version=3
hmac-algorithm=SHA512
crypto-algorithm=aes-256-cbc
encrypted=True
compressed=True
If you see `version=2` here, go to [Emergency Backup Recovery - format version 2](/doc/BackupEmergencyRestoreV2/) page instead.
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`. You can check `backup-header` file for the hash used to create the backup.
1. Decrypt the `private.img` file.
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. A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`. You can check `backup-header` file to get that information.
1. Decompress the decrypted `private.img` file.
[user@restore vm1]$ zforce private.img.dec
[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. `backup-header` file contains name of program used to compress the data.
1. Untar the decrypted and decompressed `private.img` file.
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
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

16
ContributorsList.md
View File

@ -1,16 +0,0 @@
---
layout: doc
title: ContributorsList
permalink: /doc/ContributorsList/
redirect_from: /wiki/ContributorsList/
---
List of Qubes developers
------------------------
- Joanna Rutkowska (Invisible Things Lab) - initial idea, architecture, core, packaging
- Rafal Wojtczuk (Invisible Things Lab) - architecture, gui virtualization, core
- Tomasz Sterna (TLS) - installer

52
DevelFaq.md
View File

@ -1,52 +0,0 @@
---
layout: doc
title: DevelFaq
permalink: /doc/DevelFaq/
redirect_from: /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 do 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 a few things that are KDE-specific, but generally it should not be a big problem to also add Gnome support to Qubes (in Dom0 of course). Those KDE-specific things are:
- Qubes requires KDM (KDE Login Manager), rather than GDM, for the very simple reason that GDM doesn't obey standards and start `/usr/bin/Xorg` instead of `/usr/bin/X`. This is important for Qubes, because we need to load a special "X wrapper" (to make it possible to use Linux usermode shared memory to access Xen shared memory pages in our App Viewers -- see the sources [here](https://github.com/QubesOS/qubes-gui-daemon/tree/master/shmoverride)). So, Qubes makes the `/usr/bin/X` to be a symlink to the Qubes X Wrapper, which, in turn, executes the `/usr/bin/Xorg`. This works well with KDM (and would probably also work with other X login managers), but not with GDM. If somebody succeeded in makeing GDM to execute `/usr/bin/X` instead of `/usr/bin/Xorg`, we would love to hear about it!
- We maintain a special [repository](/doc/KdeDom0/) 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](/doc/QubesBuilder/)
### Q: How do I submit a 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.
1. 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).
1. Test your changes NOW: check if RPMs build fine, etc.
1. 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.
1. Send your patch to qubes-devel. Start the message subject with the '[PATCH]' string.

24
DocStyle.md
View File

@ -1,24 +0,0 @@
---
layout: doc
title: DocStyle
permalink: /doc/DocStyle/
redirect_from: /wiki/DocStyle/
---
Guidelines for Documentation Contributors
=========================================
* 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 `[reference-style][ref]` links.
`[ref]: http://daringfireball.net/projects/markdown/syntax#link`

34
DomZeroTools.md
View File

@ -1,34 +0,0 @@
---
layout: doc
title: DomZeroTools
permalink: /doc/DomZeroTools/
redirect_from: /wiki/DomZeroTools/
---
QVM-tools:
- [qubes-dom0-update](/doc/Dom0Tools/QubesDom0Update/)
- [qubes-prefs](/doc/Dom0Tools/QubesPrefs/)
- [qvm-add-appvm](/doc/Dom0Tools/QvmAddAppvm/)
- [qvm-add-template](/doc/Dom0Tools/QvmAddTemplate/)
- [qvm-backup-restore](/doc/Dom0Tools/QvmBackupRestore/)
- [qvm-backup](/doc/Dom0Tools/QvmBackup/)
- [qvm-block](/doc/Dom0Tools/QvmBlock/)
- [qvm-clone](/doc/Dom0Tools/QvmClone/)
- [qvm-create-default-dvm](/doc/Dom0Tools/QvmCreateDefaultDvm/)
- [qvm-create](/doc/Dom0Tools/QvmCreate/)
- [qvm-firewall](/doc/Dom0Tools/QvmFirewall/)
- [qvm-grow-private](/doc/Dom0Tools/QvmGrowPrivate/)
- [qvm-ls](/doc/Dom0Tools/QvmLs/)
- [qvm-kill](/doc/Dom0Tools/QvmKill/)
- [qvm-pci](/doc/Dom0Tools/QvmPci/)
- [qvm-prefs](/doc/Dom0Tools/QvmPrefs/)
- [qvm-remove](/doc/Dom0Tools/QvmRemove/)
- [qvm-revert-template-changes](/doc/Dom0Tools/QvmRevertTemplateChanges/)
- [qvm-run](/doc/Dom0Tools/QvmRun/)
- [qvm-service](/doc/Dom0Tools/QvmService/)
- [qvm-shutdown](/doc/Dom0Tools/QvmShutdown/)
- [qvm-start](/doc/Dom0Tools/QvmStart/)
- [qvm-sync-appmenus](/doc/Dom0Tools/QvmSyncAppmenus/)
- [qvm-template-commit](/doc/Dom0Tools/QvmTemplateCommit/)

56
Donations.md
View File

@ -1,56 +0,0 @@
---
layout: doc
title: Donations
permalink: /doc/Donations/
redirect_from: /wiki/Donations/
---
Donating to the Qubes Project
=============================
The Qubes project is now accepting donations in Bitcoins. You can use the following address to send Bitcoins to the project (but you might want to read the short FAQ below first):
{% highlight trac-wiki %}
14zockMSKKp5MK6X2cHJ3mQwm9MwYsJ39j
{% endhighlight %}
This address can also be found in a message posted to Qubes mailing list, which can be viewed via Google Groups Web interface over SSL [here](https://groups.google.com/d/msg/qubes-devel/u3wAzm1dB5Y/s5CiUGDebL4J), for double verification. For additional verification, you can verify the digital signature on the message, which should come from Joanna Rutkowska.
You can check how much others have donated already (over the entire time) via [blockexplorer](https://blockexplorer.com/address/14zockMSKKp5MK6X2cHJ3mQwm9MwYsJ39j) and [blockchain](https://blockchain.info/address/14zockMSKKp5MK6X2cHJ3mQwm9MwYsJ39j).
FAQ
---
### How are you going to spend the donated Bitcoins?
Our primary intention is to fund development of additional Qubes features, such as Split GPG (\#474), Qubes MIME handlers, USB PV backend, IPv6 routing between VMs, etc. Those additional features, although often very cool and appealing, are often being postponed because we need to focus on the more mainstream features, including the commercial branches for our paying customers.
But we cannot promise we won't spend your donated Bitcoins in some other way. Frankly, I (JR) don't believe that the income from public donations could sustain ITL in operation for even a month. If, however, ITL were in financial trouble, we would use those donations in an attempt to extend our agony ;) Generally, our goal is to make Qubes/ITL survive -- even if that means we must spend your donated Bitcoins on things other than cool open-source features. Hopefully though, this will not be necessary.
### I have donated X number of Bitcoins. Can I request that a special feature be implemented?
The simple answer is: No. If everybody were to decide, then nothing would get implemented. However, if you make a substantial donation (e.g., an amount which you believe could be used to pay for several months of a developer's work), then please contact us in person or via the mailing list. You can attach a digitally signed message using the Bitcoin address you used to donate in order to prove that who made a particular donation. In that case, we will listen carefully and, in the worst case, explain to you why we can't or don't want to implement your requested feature.
### Who actually owns the above Bitcoin address?
Joanna Rutkowska (JR), the founder of Invisible Things Lab (ITL) and the Qubes project. Technically, she can do whatever she wants with the donated Bitcoins. Also, if she were to die accidentally, all the Bitcoins would probably be lost.
### How much do Joanna Rutkowska and the other guys actually earn? I've heard a rumour that she's totally spoiled and lives a pretty luxurious life. Isn't it unfair to accept donations in that case?
All Qubes developers are paid good salaries, and presently ITL is doing pretty well. JR is spoiled to no end, arrogant beyond comprehension, and generally not nice to people, especially on mailing lists. But you should realize that:
1. Nobody forces or specifically asks you to donate. Qubes will (probably) survive without any donations.
2. The main reason to donate is to encourage the creation of additional features, i.e., to make Qubes OS more secure and/or easier to use. This should benefit most Qubes users.
3. Another reason to donate is to say "Thank you," as we're releasing Qubes under GPL (excluding the Windows support) and generally trying to make the world a better place. (Oh, right, I had to made this plug somewhere here;)
### Are you going to provide a financial report on how you spend our donated Bitcoins?
Nope.
### Are you going to verify that the donated Bitcoins are not coming from some illegal activity, e.g., Bitcoin thefts?
Nope. In real life, when you go to a shop to buy a loaf of bread, or a brand new BMW, the shop is not responsible for running a background check on you and checking your financial history (which they can't do in fact).
### Why use Bitcoins and not some normal currency?
Bitcoin is an ideologically attractive currency due to its distributed nature (no central authority to control it) and due to the fact that it relies on cryptography for its security. Bitcoin is another tool that can be used to empower an individual against the system. While Bitcoin is about protecting your wealth, Qubes is about protecting your digital life (against an adversary that could also be "the system"). Of course it makes perfect sense to use Qubes OS to secure your Bitcoin wallet by, e.g., running it in a dedicated AppVM (or even more).

14
ExternalDeviceMountPoint.md
View File

@ -1,14 +0,0 @@
---
layout: doc
title: ExternalDeviceMountPoint
permalink: /doc/ExternalDeviceMountPoint/
redirect_from: /wiki/ExternalDeviceMountPoint/
---
All external storage devices connected to an AppVM using the Fedora template can be found under
{% highlight trac-wiki %}
/run/media/user/
{% endhighlight %}
...of that AppVM's filesystem.

105
InstallationGuide.md
View File

@ -1,105 +0,0 @@
---
layout: doc
title: InstallationGuide
permalink: /doc/InstallationGuide/
redirect_from: /wiki/InstallationGuide/
---
Installation Guide (for Qubes Release 1)
========================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading from Qubes 1.0-rc1](#UpgradingfromQubes1.0-rc1)
5. [Migrating from Qubes Beta 3](#MigratingfromQubesBeta3)
6. [Installing Updates](#InstallingUpdates)
7. [Known Issues](#KnownIssues)
8. [Getting Help](#GettingHelp)
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.
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v <iso>.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R1-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX)'''**
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 from Qubes 1.0-rc1
----------------------------
If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). The easiest way for doing this is to click on the Update Button in the Qubes Manger -- one click when you selected Dom0, and one click for each of your template VM (by default there is just one template).
Migrating from Qubes Beta 3
---------------------------
If you have Qubes Beta 3 currently installed on your system, you must reinstall from scratch, as we offer no direct upgrade option in the installer (sorry). However, we do offer tools for smooth migration of your AppVMs. In order to do that, please backup your AppVMs using the `qvm-backup` tool [as usual](/doc/BackupRestore/). Then, after you install Qubes 1.0 rc1, you can restore them using `qvm-backup-restore` tool. However, because we have changed the default template in RC1, you should tell qvm-back-restore about that by passing `--replace-template` option:
{% highlight trac-wiki %}
qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64
{% endhighlight %}
Installing Updates
------------------
Installing updates is very easy and can be done using the "Update" button in the Qubes Manager. Alternatively it can also be done from command prompt -- see the following for more details:
- For installing updates for Dom0 -- see instructions [here](/doc/SoftwareUpdateDom0/).
- For installing updates for you domains (VMs) -- see instructions [here](/doc/SoftwareUpdateVM/).
Known Issues
------------
- Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected).
- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get somehow ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
- On systems with more than 8GB of RAM there is problem with Disposable VM. To fix it, limit maximum memory allocation for DispVM to 3GB
{% highlight trac-wiki %}
qvm-prefs -s fedora-17-x64-dvm maxmem 3072
qvm-create-default-dvm --default-template --default-script
{% endhighlight %}
- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- If you don't find answer in the sources given above, write to the *qubes-devel* mailing list:
- [http://groups.google.com/group/qubes-devel](http://groups.google.com/group/qubes-devel)
- `qubes-devel@googlegroups.com`

107
InstallationGuideR2.md
View File

@ -1,107 +0,0 @@
---
layout: doc
title: InstallationGuideR2
permalink: /doc/InstallationGuideR2/
redirect_from: /wiki/InstallationGuideR2/
---
Installation Guide for Qubes Release 2
======================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading](#Upgrading)
5. [Troubleshooting problems with the installer](#Troubleshootingproblemswiththeinstaller)
6. [Known Issues](#KnownIssues)
7. [Getting Help](#GettingHelp)
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v Qubes-R2-x86_64-DVD.iso.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
On windows you can use [this](http://www.chrysocome.net/dd) tool. Example command would be (as Administrator):
{% highlight trac-wiki %}
dd if=Qubes-R2-x86_64-DVD.iso of=\\?\Device\Harddisk1\Partition0 bs=1M --size --progress
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX or Harddisk1)**
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 :)
![qubes-r2-installer-welcome.png](/attachment/wiki/InstallationGuideR2/qubes-r2-installer-welcome.png)
Upgrading
---------
Upgrading from Qubes R2 rc1 should be a simple matter of installing updates for [dom0](/doc/SoftwareUpdateDom0/) and [VMs](/doc/SoftwareUpdateVM/).
Users of R2 beta 3 should follow instructions on how to upgrade to Qubes R2 rc1 [here](/doc/UpgradeToR2rc1/).
Troubleshooting problems with the installer
-------------------------------------------
If the installer fails for some reason, typically because of the graphics card not being correctly supported, it is possible to try booting the installer with a different kernel -- to do that, choose Troubleshooting menu in the Installer Welcome screen, and later choose an option to proceed with one of the kernels provided:
![qubes-r2-installer-troubleshooting.png](/attachment/wiki/InstallationGuideR2/qubes-r2-installer-troubleshooting.png)
The installer ships with 4 different kernels (3.12, 3.11, 3.9 and 3.7) and all those kernel will be installed (regardless of which is selected to run the installer) so it is later always possible to boot the Qubes OS using any of those kernels.
Known Issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
- Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually.
- System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first.
- For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority)
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- 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.

99
InstallationGuideR2B1.md
View File

@ -1,99 +0,0 @@
---
layout: doc
title: InstallationGuideR2B1
permalink: /doc/InstallationGuideR2B1/
redirect_from: /wiki/InstallationGuideR2B1/
---
Installation Guide (for Qubes Release 2 Beta 1)
===============================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading from Qubes R1](#UpgradingfromQubesR1)
5. [Installing Updates](#InstallingUpdates)
6. [Known Issues](#KnownIssues)
7. [Getting Help](#GettingHelp)
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v <iso>.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-Beta-1-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX)'''**
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 from Qubes R1
-----------------------
If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here?](/doc/UpgradeToR2/).
Installing Updates
------------------
Installing updates is very easy and can be done using the "Update" button in the Qubes Manager. Alternatively it can also be done from command prompt -- see the following for more details:
- For installing updates for Dom0 -- see instructions [here](/doc/SoftwareUpdateDom0/).
- For installing updates for you domains (VMs) -- see instructions [here](/doc/SoftwareUpdateVM/).
Known Issues
------------
- Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected).
- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get somehow ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
- On systems with more than 8GB of RAM there is problem with Disposable VM. To fix it, limit maximum memory allocation for DispVM to 3GB
{% highlight trac-wiki %}
qvm-prefs -s fedora-17-x64-dvm maxmem 3072
qvm-create-default-dvm --default-template --default-script
{% endhighlight %}
- Qubes installer/system won't boot from a USB3-attached disks due to missing modules in initramfs (\#691). Please use USB2 port/device instead for now.
- Systems with AMD graphics needs additional firmware (missing in default installation), details [here](http://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76).
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- If you don't find answer in the sources given above, write to the *qubes-devel* mailing list (you don't need to be subscribed to the list, just send email to the address given below):
- [http://groups.google.com/group/qubes-devel](http://groups.google.com/group/qubes-devel)
- `qubes-devel@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.

90
InstallationGuideR2B2.md
View File

@ -1,90 +0,0 @@
---
layout: doc
title: InstallationGuideR2B2
permalink: /doc/InstallationGuideR2B2/
redirect_from: /wiki/InstallationGuideR2B2/
---
Installation Guide for Qubes Release 2 Beta 2
=============================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading from Qubes R1 or R2 Beta 1](#UpgradingfromQubesR1orR2Beta1)
5. [Installing Updates](#InstallingUpdates)
6. [Known Issues](#KnownIssues)
7. [Getting Help](#GettingHelp)
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v <iso>.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-Beta2-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX)**
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 from Qubes R1 or R2 Beta 1
------------------------------------
Because of the distribution change in R2B2 (from fc13 to fc18) it's preferred that users reinstall Qubes R2B2 from scratch, and use [qubes backup and restore tools](/doc/BackupRestore/) for migrating of all of the user VMs.
Advanced users (and advanced users only) can also try a manual upgrade procedure that has been described [here](/doc/UpgradeToR2B2/). It's advisable to backup your VMs before proceeding anyway!
Installing Updates
------------------
Installing updates is very easy and can be done using the "Update" button in the Qubes Manager. Alternatively it can also be done from command prompt -- see the following for more details:
- For installing updates for Dom0 -- see instructions [here](/doc/SoftwareUpdateDom0/).
- For installing updates for you domains (VMs) -- see instructions [here](/doc/SoftwareUpdateVM/).
Known Issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2 B2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- When restoring service VMs from a backup (such as custom netvms, firewallvms, etc) their icons might not be preserved in the "Start Menu".
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- If you don't find answer in the sources given above, write to the *qubes-devel* mailing list (you don't need to be subscribed to the list, just send email to the address given below):
- [http://groups.google.com/group/qubes-devel](http://groups.google.com/group/qubes-devel)
- `qubes-devel@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.

120
InstallationGuideR2B3.md
View File

@ -1,120 +0,0 @@
---
layout: doc
title: InstallationGuideR2B3
permalink: /doc/InstallationGuideR2B3/
redirect_from: /wiki/InstallationGuideR2B3/
---
Installation Guide for Qubes Release 2 Beta 3
=============================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading from Qubes R1 or R2 Beta 2](#UpgradingfromQubesR1orR2Beta2)
5. [Installing Updates](#InstallingUpdates)
6. [Troubleshooting problems with the installer](#Troubleshootingproblemswiththeinstaller)
7. [Known Issues](#KnownIssues)
8. [Getting Help](#GettingHelp)
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v <iso>.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-Beta3-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
On windows you can use [this](http://www.chrysocome.net/dd) tool. Example command would be (as Administrator):
{% highlight trac-wiki %}
dd if=Qubes-R2-Beta3-x86_64-DVD.iso of=\\?\Device\Harddisk1\Partition0 bs=1M --size --progress
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX or Harddisk1)**
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 :)
![r2b3-installer-welcome.png](/attachment/wiki/InstallationGuideR2B3/r2b3-installer-welcome.png)
Upgrading from Qubes R1 or R2 Beta 2
------------------------------------
The easiest and safest way to upgrade to Qubes R2B3 is to install it from scratch and use [qubes backup and restore tools](/doc/BackupRestore/) for migrating of all of the user VMs.
Users can also try a manual upgrade procedure that has been described [here](/doc/UpgradeToR2B3/).
Note: if the user has custom Template VMs (i.e. other than the default template, e.g. created from it by cloning), or Standalone VMs, then the user should perform manual upgrade from R2B2 to R2B3, as described under the link given above.
Installing Updates
------------------
NOTE: Updates has been released after R2B3 ISO has been built -- it is recommended to install Dom0 updates shortly after installation to resolve some of the issues mentioned in the section below (Known Issues).
Installing updates is very easy and can be done using the "Update" button in the Qubes Manager. Alternatively it can also be done from command prompt -- see the following for more details:
- For installing updates for Dom0 -- see instructions [here](/doc/SoftwareUpdateDom0/).
- For installing updates for you domains (VMs) -- see instructions [here](/doc/SoftwareUpdateVM/).
Troubleshooting problems with the installer
-------------------------------------------
If the installer fails for some reason, typically because of the graphics card not being correctly supported, it is possible to try booting the installer with a different kernel -- to do that, choose Troubleshooting menu in the Installer Welcome screen, and later choose an option to proceed with one of the kernels provided:
![r2b3-installer-troubleshooting.png](/attachment/wiki/InstallationGuideR2B3/r2b3-installer-troubleshooting.png)
The installer ships with 3 different kernels (3.11, 3.9 and 3.7) and all those kernel will be installed (regardless of which is selected to run the installer) so it is later always possible to boot the Qubes OS using any of those kernels.
Known Issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2 B2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- When restoring service VMs from a backup (such as custom netvms, firewallvms, etc) their icons might not be preserved in the "Start Menu".
- If you're GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
- For HVMs without Qubes Tools installed the GUI window will not be shown unless 'debug' flag is enabled for the VM. This has been fixed in `qubes-core-dom0` package \>= 2.1.35 -- please ensure you install updates after installation to resolve this issue.
- Clocks might not get syncs in the VMs for up to several minutes after resume from sleep. This has been fixed in `qubes-core-dom0-linux` package \>= 2.0.4 -- please ensure you install updates after installation to resolve this issue.
- Gnome terminal window sometimes shrinks to minimal size (especially when opening new tab). The workaround is to disable its menubar and scrollbar.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- 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):
- [http://groups.google.com/group/qubes-users](http://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.

105
InstallationGuideR2rc1.md
View File

@ -1,105 +0,0 @@
---
layout: doc
title: InstallationGuideR2rc1
permalink: /doc/InstallationGuideR2rc1/
redirect_from: /wiki/InstallationGuideR2rc1/
---
Installation Guide for Qubes Release 2 rc1
==========================================
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. [Known Issues](#known-issues)
7. [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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v <iso>.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-rc1-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
On windows you can use [this](http://www.chrysocome.net/dd) tool. Example command would be (as Administrator):
{% highlight trac-wiki %}
dd if=Qubes-R2-rc1-x86_64-DVD.iso of=\\?\Device\Harddisk1\Partition0 bs=1M --size --progress
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX or Harddisk1)**
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 :)
![qubes-r2-rc1-installer-welcome.png](/attachment/wiki/InstallationGuideR2rc1/qubes-r2-rc1-installer-welcome.png)
Upgrading
---------
The easiest and safest way to upgrade to Qubes R2rc1 (especially from older releases) is to install it from scratch and use [qubes backup and restore tools](/doc/BackupRestore/) for migrating of all of the user VMs.
Users of R2 beta 3 can upgrade using procedure that has been described [here](/doc/UpgradeToR2rc1/).
Note: if the user has custom Template VMs (i.e. other than the default template, e.g. created from it by cloning), or Standalone VMs, then the user should perform manual upgrade from R2B3 to R2rc1, as described under the link given above.
Troubleshooting problems with the installer
-------------------------------------------
If the installer fails for some reason, typically because of the graphics card not being correctly supported, it is possible to try booting the installer with a different kernel -- to do that, choose Troubleshooting menu in the Installer Welcome screen, and later choose an option to proceed with one of the kernels provided:
![qubes-r2-rc1-installer-troubleshooting.png](/attachment/wiki/InstallationGuideR2rc1/qubes-r2-rc1-installer-troubleshooting.png)
The installer ships with 4 different kernels (3.12, 3.11, 3.9 and 3.7) and all those kernel will be installed (regardless of which is selected to run the installer) so it is later always possible to boot the Qubes OS using any of those kernels.
Known Issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
- HVMs with Qubes Tools installed will not have access to the network if firewallvm uses 3.12 kernel (the default). The workaround is to use older (3.11) kernel for firewallvm. You need to [install kernel-qubes-vm-3.11.10 package](/doc/SoftwareUpdateDom0/#how-to-downgrade-a-specific-package), then ensure that it is used for firewallvm (for example using Qubes Manager - advanced tab of VM settings).
- Just after installation, applications menu will not contain colorful application icons (new feature), only padlock in VM color. To get colorful icons, you need to start template VM (fedora-20-x64) and call `qvm-sync-appmenus fedora-20-x64` in dom0 terminal. If you have other Template VMs or Standalone VMs, repeat the steps for them too.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- 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.

99
InstallationGuideR2rc2.md
View File

@ -1,99 +0,0 @@
---
layout: doc
title: InstallationGuideR2rc2
permalink: /doc/InstallationGuideR2rc2/
redirect_from: /wiki/InstallationGuideR2rc2/
---
Installation Guide for Qubes Release 2 rc2
==========================================
1. [Hardware Requirements](#HardwareRequirements)
2. [Download installer ISO](#DownloadinstallerISO)
3. [Burning the ISO onto a DVD or USB stick](#BurningtheISOontoaDVDorUSBstick)
4. [Upgrading](#Upgrading)
5. [Troubleshooting problems with the installer](#Troubleshootingproblemswiththeinstaller)
6. [Known Issues](#KnownIssues)
7. [Getting Help](#GettingHelp)
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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
{% highlight trac-wiki %}
gpg -v Qubes-R2-rc2-x86_64-DVD.iso.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
dd if=Qubes-R2-rc2-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
On windows you can use [this](http://www.chrysocome.net/dd) tool. Example command would be (as Administrator):
{% highlight trac-wiki %}
dd if=Qubes-R2-rc2-x86_64-DVD.iso of=\\?\Device\Harddisk1\Partition0 bs=1M --size --progress
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX or Harddisk1)**
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 :)
![qubes-r2-rc2-installer-welcome.png](/attachment/wiki/InstallationGuideR2rc2/qubes-r2-rc2-installer-welcome.png)
Upgrading
---------
Upgrading from Qubes R2 rc1 should be a simple matter of installing updates for [dom0](/doc/SoftwareUpdateDom0/) and [VMs](/doc/SoftwareUpdateVM/).
Users of R2 beta 3 should follow instructions on how to upgrade to Qubes R2 rc1 [here](/doc/UpgradeToR2rc1/).
Troubleshooting problems with the installer
-------------------------------------------
If the installer fails for some reason, typically because of the graphics card not being correctly supported, it is possible to try booting the installer with a different kernel -- to do that, choose Troubleshooting menu in the Installer Welcome screen, and later choose an option to proceed with one of the kernels provided:
![qubes-r2-rc2-installer-troubleshooting.png](/attachment/wiki/InstallationGuideR2rc2/qubes-r2-rc2-installer-troubleshooting.png)
The installer ships with 4 different kernels (3.12, 3.11, 3.9 and 3.7) and all those kernel will be installed (regardless of which is selected to run the installer) so it is later always possible to boot the Qubes OS using any of those kernels.
Known Issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- 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.

93
InstallationGuideR3.0rc1.md
View File

@ -1,93 +0,0 @@
---
layout: doc
title: Installation Guide for Qubes 3.0 rc1
permalink: /doc/InstallationGuideR3.0rc1/
---
Installation Guide for Qubes Release 3.0 rc1
============================================
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. [Known Issues](#known-issues)
7. [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](/doc/VerifyingSignatures/) for more info about how to download and verify our GPG keys, and then verify the downloaded ISO:
gpg -v Qubes-R3.0-rc1-x86_64-DVD.iso.asc
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-R3.0-rc1-x86_64-DVD.iso of=/dev/sdX
On windows you can use [this](http://www.chrysocome.net/dd) tool. Example command would be (as Administrator):
dd if=Qubes-R3.0-rc1-x86_64-DVD.iso of=\\?\Device\Harddisk1\Partition0 bs=1M --size --progress
**Be sure to use a correct device as the target in the dd command above (instead of sdX or Harddisk1)**
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
---------
The easiest and safest way to upgrade to Qubes R3.0rc1 is to install it from scratch and use [qubes backup and restore tools](/doc/BackupRestore/) for migrating of all of the user VMs.
Users or Qubes R2 can upgrade using experimental procedure that has been described [here](/doc/UpgradeToR3.0rc1/).
Troubleshooting problems with the installer
-------------------------------------------
If the installer fails for some reason, typically because of the graphics card not being correctly supported, it is possible to try booting the installer with a different kernel -- to do that, choose Troubleshooting menu in the Installer Welcome screen, and later choose an option to proceed with one of the kernels provided.
The installer ships with 4 different kernels (3.12, 3.11, 3.9 and 3.7) and all those kernel will be installed (regardless of which is selected to run the installer) so it is later always possible to boot the Qubes OS using any of those kernels.
Known Issues
------------
- There is no Qubes Windows Tools for Qubes R3.0 yet. We are working on this
- UEFI is not supported, you need to enable "legacy boot" in BIOS before installing Qubes OS
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
- For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3%22+label%3Abug)
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Getting Help
------------
- **User manuals are [here](/doc/UserDoc/).** (Strongly recommended!)
- Developers documentation (normally not needed by users) is [here](/doc/SystemDoc/)
- 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.

86
InstallationIsoBuilding.md
View File

@ -1,86 +0,0 @@
---
layout: doc
title: InstallationIsoBuilding
permalink: /doc/InstallationIsoBuilding/
redirect_from: /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:
{% highlight trac-wiki %}
cd installer
make rpms
{% endhighlight %}
Packages will be in `rpm/noarch` and `rpm/x86_64`.
Install Revisor
---------------
Next install the freshly built revisor and anaconda:
{% highlight trac-wiki %}
yum install rpm/noarch/revisor*.rpm
yum install rpm/x86_64/anaconda*.rpm
{% endhighlight %}
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:
{% highlight trac-wiki %}
make update-repo
{% endhighlight %}
Build ISO
---------
Now you're finally ready to build the ISO image:
{% highlight trac-wiki %}
make iso
{% endhighlight %}
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.

17
QubesContacts.md
View File

@ -1,17 +0,0 @@
---
layout: doc
title: QubesContacts
permalink: /doc/QubesContacts/
redirect_from: /wiki/QubesContacts/
---
Contacting the Qubes OS Team
============================
**Note:** Please send all the questions regarding Qubes to the [mailing list](/doc/QubesLists/). This way, your questions, as well as answers to those questions, could be also shared with other users.
Press & business contact
------------------------
- Joanna Rutkowska `joanna at invisiblethingslab dot com`

46
QubesDevelopers.md
View File

@ -1,46 +0,0 @@
---
layout: doc
title: QubesDevelopers
permalink: /doc/QubesDevelopers/
redirect_from: /wiki/QubesDevelopers/
---
Qubes Developers
================
Architects & Core Developers
----------------------------
- Joanna Rutkowska `joanna at invisiblethingslab dot com` - architecture & project management, original core, occasional addons
- Marek Marczykowski `marmarek at invisiblethingslab dot com` - everything Xen/Linux related :)
- Wojciech Porczyk `woju at invisiblethingslab dot com` -- various Linux-related things
Contributors to the open source code
------------------------------------
(Roughly in chronology order:)
- Rafal Wojtczuk `rafal at invisiblethingslab dot com` - architecture & system-level stuff (notably original gui virtualization)
- Tomasz Sterna `tomek at xiaoka dot com` - installer & gui
- Agnieszka Kostrzewa `a.kostrzewa at alx dot pl` - qubes-manager, docs
- Abel Luck `abel at outcomedubious dot im` - torvm
- Alexandre Bezroutchko `abb at gremwell dot com` - pvusb support
- Bruce A Downs `bruceadowns at gmail.com` - minor various cleanups and miscs
- Olivier Médoc `o_medoc at yahoo.fr` - core and gui fixes, template builder generalization (Arch Linux support)
- Timo Juhani Lindfors `timo.lindfors at iki.fi` - minor core cleanups
- Radoslaw Szkodzinski `astralstorm at gmail.com` - minor gui build fixes
- László Zrubecz `mail at zrubi.hu` -- HCL wiki page maintenance, HCL scripts
- Vincent Penquerc'h `vincent.penquerch@collabora.co.uk` -- code review, misc fixes
Proprietary code developers
---------------------------
- Alexander Tereshkin `alex at invisiblethingslab dot com` - core windows (Qubes Windows Tools)
- Rafał Wojdyła `omeg at invisiblethingslab dot com` - currently main developer for Qubes Windows Tools (core, gui agent)
Wiki/documentation editors
--------------------------
- Hakisho Nukama `nukama at gmail dot com` - various wiki contributions (ZFS, HCL)
- Axon `axon at openmailbox dot org` - various wiki edits

38
QubesDocs.md
View File

@ -1,38 +0,0 @@
---
layout: doc
title: QubesDocs
permalink: /doc/
redirect_from: \
/doc/QubesDocs/
/wiki/QubesDocs/
---
Qubes Documentation
===================
For Users
---------
- [User Documentation](/doc/UserDoc/)
- [Users' FAQ](/doc/UserFaq/)
- [System Requirements](/doc/SystemRequirements/)
- [Hardware Compatibility List](/hcl/)
- [On Digital Signatures and How to Verify Qubes Downloads](/doc/VerifyingSignatures/)
- [Installation Guides](/doc/QubesDownloads/)
- [Troubleshooting](/doc/TroubleShooting/)
- [Security](/doc/QubesSecurity/)
For Developers
--------------
- [Developer Documentation](/doc/SystemDoc/)
- [Developers' FAQ](/doc/DevelFaq/)
- [How can I contribute to the Qubes project?](/doc/ContributingHowto/)
- [Source Code](/doc/SourceCode/)
- [Coding Guidelines](/doc/CodingStyle/)
- [Documentation Guidelines](/doc/DocStyle/)
- [Books for Developers](/doc/DevelBooks/)
- [Research Papers](/doc/QubesResearch/)
- [Architecture](/doc/QubesArchitecture/)
- [Licensing](/doc/QubesLicensing/)

59
QubesDownloads.md
View File

@ -1,59 +0,0 @@
---
layout: doc
title: QubesDownloads
permalink: /doc/QubesDownloads/
redirect_from: /wiki/QubesDownloads/
---
Qubes Downloads
===============
- [System Requirements](/doc/SystemRequirements/)
- [Hardware Compatibility List](/hcl/)
- [On Digital Signatures and How to Verify Qubes Downloads](/doc/VerifyingSignatures/)
- [Installation Security Considerations](/doc/InstallSecurity/)
- [Licensing](/doc/QubesLicensing/)
Qubes Release 3.0
---------------
- [Qubes-R3.0-rc1-x86\_64-DVD.iso](http://sourceforge.net/projects/qubesos/files/Qubes-R3.0-rc1-x86_64-DVD.iso/download) (via sourceforge.net)
- [Digital Signature](http://sourceforge.net/projects/qubesos/files/Qubes-R3.0-rc1-x86_64-DVD.iso.asc/download) (via sourceforge.net)
- **[Installation Guide for Qubes R3.0 rc1](/doc/InstallationGuideR3.0rc1/)**
- [Upgrading to Qubes R3.0 rc1](/doc/InstallationGuideR3.0rc1/#upgrading)
Qubes Release 2
---------------
- [Qubes-R2-x86\_64-DVD.iso](http://sourceforge.net/projects/qubesos/files/Qubes-R2-x86_64-DVD.iso/download) (via sourceforge.net)
- [Digital Signature](http://sourceforge.net/projects/qubesos/files/Qubes-R2-x86_64-DVD.iso.asc/download) (via sourceforge.net)
- **[Installation Guide for Qubes R2](/doc/InstallationGuideR2/)**
- [Upgrading to Qubes R2](/doc/InstallationGuideR2/#upgrading)
- [Qubes-R2-rc2-x86\_64-DVD.iso](http://sourceforge.net/projects/qubesos/files/Qubes-R2-rc2-x86_64-DVD.iso/download) (via sourceforge.net)
- [Digital Signature](http://sourceforge.net/projects/qubesos/files/Qubes-R2-rc2-x86_64-DVD.iso.asc/download) (via sourceforge.net)
- **[Installation Guide for Qubes R2 rc2](/doc/InstallationGuideR2rc2/)**
- [Upgrading to Qubes R2 rc2](/doc/InstallationGuideR2rc2/#upgrading)
Qubes Release 1
---------------
(This is mainly for historical reference, we strongly recommend Qubes R2 above)
- [Qubes-R1-x86\_64-DVD.iso](http://sourceforge.net/projects/qubesos/files/Qubes-R1-x86_64-DVD.iso/download) (via sourceforge.net)
- [Digital Signature](http://sourceforge.net/projects/qubesos/files/Qubes-R1-x86_64-DVD.iso.asc/download) (via sourceforge.net)
- **[Installation Guide](/doc/InstallationGuide/)**
Mirrors
-------
Qubes ISOs are also available from the following mirrors:
- [http://ftp.fsn.hu/pub/linux/distributions/qubes/](http://ftp.fsn.hu/pub/linux/distributions/qubes/)
- [http://linuxtracker.org/index.php?page=torrent-details&id=3bdf893771d63bdbe3d83f31e064360ee10f30ec](http://linuxtracker.org/index.php?page=torrent-details&id=3bdf893771d63bdbe3d83f31e064360ee10f30ec)
- [http://burnbit.com/torrent/303367/Qubes\_R2\_rc2\_x86\_64\_DVD\_iso](http://burnbit.com/torrent/303367/Qubes_R2_rc2_x86_64_DVD_iso)

114
QubesScreenshots.md
View File

@ -1,114 +0,0 @@
---
layout: doc
title: QubesScreenshots
permalink: /doc/QubesScreenshots/
redirect_from: /wiki/QubesScreenshots/
---
Select Qubes OS Screenshots
===========================
[![r2b2-kde-start-menu.png](/attachment/wiki/QubesScreenshots/r2b2-kde-start-menu.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-start-menu.png)
Starting applications from different domains (AppVMs) is very easy.
* * * * *
[![r2b2-kde-three-domains-at-work.png](/attachment/wiki/QubesScreenshots/r2b2-kde-three-domains-at-work.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-three-domains-at-work.png)
In this example, the word processor runs in the “work” domain, which has been assigned the “green” label. It is fully isolated from other domains, such as the “untrusted” domain (assigned the “red” label -- “Watch out!”, “Danger!”) used for random Web browsing, news reading, as well as from the "work-web" domain (assigned the "yellow" label), which is used for work-related Web browsing that is not security critical. Apps from different domains run in different AppVMs and have different X servers, filesystems, etc. Notice the different color frames (labels) and VM names in the titlebars. These are drawn by the trusted Window Manager running in Dom0, and apps running in domains cannot fake them:
* * * * *
[![r2b3-windows-seamless-1.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-1.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-1.png)
Qubes Release 2 can also run Windows AppVMs in seamless mode, integrated onto the common Qubes trusted desktop, just like Linux AppVMs! The seamless GUI integration has been introduced in Qubes R2 Beta 3. This requires our dedicated Qubes Windows Support Tools to be installed in the Windows VMs first. The Qubes Windows Tools are proprietary but we distribute the binaries for free with current Qubes OS releases.
* * * * *
[![r2b3-windows-seamless-filecopy.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-filecopy.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-filecopy.png)
Windows AppVMs are fully integrated with the rest of the Qubes OS system, which includes things such as secure, policy governed, inter-VM file copy, clipboard, and generally whole our elastic qrexec infrastructure for secure inter-VM RPC! Starting with Qubes R2 Beta 3 we also support HVM-based templates allowing to instantly create many Windows AppVMs with shared "root filesystem" from the Template VM (but one should ensure their license allows for such instantiation of the OS in the template). Just like with Linux AppVMs!
* * * * *
[![r2b2-xfce4-programmers-desktop-2.png](/attachment/wiki/QubesScreenshots/r2b2-xfce4-programmers-desktop-2.png)](/attachment/wiki/QubesScreenshots/r2b2-xfce4-programmers-desktop-2.png)
Here we see Xfce4.10 Window Manager running in Dom0 (instead of KDE as on previous screens). Qubes supports customized Xfce4 in dom0 beginning with R2 Beta 2!
* * * * *
[![password-prompt.png](/attachment/wiki/QubesScreenshots/password-prompt.png)](/attachment/wiki/QubesScreenshots/password-prompt.png)
It is always clearly visible to which domain a given window belongs. Here it’s immediately clear that the passphrase-prompting window belongs to some domain with the “green” label. When we look at the titlebar, we see “[work]”, which is the name of the actual domain. Theoretically, the untrusted application (here, the “red” Firefox) beneath the prompt window could draw a similar looking window within its contents. In practice, this would be very hard, because it doesn’t know, e.g., the exact decoration style that is in use. However, if this is a concern, the user can simply try to move the more trusted window onto some empty space on the desktop such that no other window is present beneath it. Or, better yet, use the Expose-like effect (available via a hot-key). A malicious application from an untrusted domain cannot spoof the whole desktop because the trusted Window Manager will never let any domain “own” the whole screen. Its titlebar will always be visible.
* * * * *
[![r2b2-kde-tray-icons.png](/attachment/wiki/QubesScreenshots/r2b2-kde-tray-icons.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-tray-icons.png)
Qubes is all about seamless integration from the user’s point of view. Here you can see how it virtualizes tray icons from other domains. Notice the network icon in a red frame. This icon is in fact managed by the Network Manager running in a separate NetVM. The notes icon (with the green frame around it) has been drawn by the note-taking app running in the work domain (which has the "green" label).
* * * * *
[![r2b2-manager-and-netvm-network-prompt.png](/attachment/wiki/QubesScreenshots/r2b2-manager-and-netvm-network-prompt.png)](/attachment/wiki/QubesScreenshots/r2b2-manager-and-netvm-network-prompt.png)
All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems).
* * * * *
[![r2b2-software-update.png](/attachment/wiki/QubesScreenshots/r2b2-software-update.png)](/attachment/wiki/QubesScreenshots/r2b2-software-update.png)
Qubes lets you update all the software in all the domains all at once, in a centralized way. This is possible thanks to Qubes' unique TemplateVM technology. Note that the user is not required to shut down any AppVMs (domains) for the update process. This can be done later, at a convenient moment, and separately for each AppVM.
* * * * *
[![copy-paste-1.png](/attachment/wiki/QubesScreenshots/copy-paste-1.png)](/attachment/wiki/QubesScreenshots/copy-paste-1.png) [![copy-paste-2.png](/attachment/wiki/QubesScreenshots/copy-paste-2.png)](/attachment/wiki/QubesScreenshots/copy-paste-2.png)
Qubes supports secure copy-and-paste operations between AppVMs. Only the user can initiate a copy or paste operation using a special key combination (Ctrl-Shift-C/V). Other AppVMs have no access to the clipboard buffer, so they cannot steal data from the clipboard. Only the user decides which AppVM should be given access to the clipboard. (This is done by selecting the destination AppVM’s window and pressing the Ctrl-Shift-V combination.)
* * * * *
[!["r2b2-copy-to-other-appvm-1.png](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-1.png)](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-1.png) [![r2b2-copy-to-other-appvm-3.png](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-3.png)](/attachment/wiki/QubesScreenshots/r2b2-copy-to-other-appvm-3.png)
Qubes also supports secure file copying between AppVMs.
* * * * *
[![r2b2-open-in-dispvm-1.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-1.png) [![r2b2-open-in-dispvm-3.png](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)](/attachment/wiki/QubesScreenshots/r2b2-open-in-dispvm-3.png)
Qubes' unique Disposable VMs (DispVMs) allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable VM, and any changes are projected back onto the original file. Currently, there is no way to mark files to be automatically opened in a disposable VM (one needs to right-click on the file and choose the "Open in Disposable VM" option), but this is planned for the R2 Beta 3 release.
* * * * *
[![r2b2-convert-to-trusted-pdf-3.png](/attachment/wiki/QubesScreenshots/r2b2-convert-to-trusted-pdf-3.png)](/attachment/wiki/QubesScreenshots/r2b2-convert-to-trusted-pdf-3.png) [![r2b2-converting-pdf-2.png](/attachment/wiki/QubesScreenshots/r2b2-converting-pdf-2.png)](/attachment/wiki/QubesScreenshots/r2b2-converting-pdf-2.png)
Qubes provides an advanced infrastructure for programming inter-VM services, such as a PDF converter for untrusted files (which is described in [this article](http://theinvisiblethings.blogspot.com/2013/02/converting-untrusted-pdfs-into-trusted.html)).
* * * * *
[![r2b1-manager-firewall.png](/attachment/wiki/QubesScreenshots/r2b1-manager-firewall.png)](/attachment/wiki/QubesScreenshots/r2b1-manager-firewall.png)
Qubes provides a dedicated firewall that itself runs in an isolated FirewallVM.
* * * * *
And some more screenshots:
[![r2b2-xfce4-start-menu-3.png](/attachment/wiki/QubesScreenshots/r2b2-xfce4-start-menu-3.png)](/attachment/wiki/QubesScreenshots/r2b2-xfce4-start-menu-3.png)
[![r2b2-kde-red-and-green-terminals.png](/attachment/wiki/QubesScreenshots/r2b2-kde-red-and-green-terminals.png)](/attachment/wiki/QubesScreenshots/r2b2-kde-red-and-green-terminals.png)
[![r2b3-windows-seamless-2.png](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-2.png)](/attachment/wiki/QubesScreenshots/r2b3-windows-seamless-2.png)
* * * * *
The following screenshots, [courtesy of Qubes user nalu](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion), demonstrate some of the ways in which KDE can be customized to work with Qubes:
[![r3rc1-nalu-desktop-1.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-1.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-1.png)
[![r3rc1-nalu-desktop-2.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-2.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-2.png)
[![r3rc1-nalu-desktop-3.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-3.png)
[![r3rc1-nalu-desktop-4.png](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png)](/attachment/wiki/QubesScreenshots/r3rc1-nalu-desktop-4.png)

18
QubesSecurity.md
View File

@ -1,18 +0,0 @@
---
layout: doc
title: QubesSecurity
permalink: /doc/QubesSecurity/
redirect_from: /wiki/QubesSecurity/
---
Qubes Security
==============
- [Reporting Security Issues in Qubes OS](/doc/SecurityPage/)
- [Qubes Security Pack](/doc/SecurityPack/)
- [Qubes Security Bulletins](/doc/SecurityBulletins/)
- [Qubes Security Goals](/doc/SecurityGoals/)
- [On digital signatures and how to verify Qubes keys and downloads](/doc/VerifyingSignatures/)
- [Qubes Keys](http://keys.qubes-os.org/keys/)

48
README.md Normal file
View File

@ -0,0 +1,48 @@
Qubes OS Documentation
======================
https://www.qubes-os.org/doc/
All [Qubes OS Project][qubes] documentation pages are stored as plain text
files in this dedicated 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 this repository and edit the
files here. The GitHub interface will automatically guide you through the
[fork and pull request 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]: 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/

256
SecurityPack.md
View File

@ -1,256 +0,0 @@
---
layout: doc
title: SecurityPack
permalink: /doc/SecurityPack/
redirect_from: /wiki/SecurityPack/
---
Qubes Security Pack
===================
1. [Qubes Security Pack](#QubesSecurityPack)
1. [Introduction](#Introduction)
2. [History and Rationale](#HistoryandRationale)
3. [How to Obtain, Verify, and Read](#HowtoObtainVerifyandRead)
Introduction
------------
The **Qubes Security Pack (QSP)** is a Git repository which contains:
- [All Qubes Security Bulletins (QSBs)](/doc/SecurityBulletins/)
- [All PGP keys](https://keys.qubes-os.org/keys/)
- [Warrant canaries](https://en.wikipedia.org/wiki/Warrant_canary)
- Other security-related information and announcements (such as key revocations)
The QSP is located here:
> [https://github.com/QubesOS/qubes-secpack](https://github.com/QubesOS/qubes-secpack)
History and Rationale
---------------------
On 2013-01-05, Joanna Rutkowska announced the QSP and explained its rationale in an [email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ) to the Qubes mailing lists:
{% highlight trac-wiki %}
Hello,
A new Qubes Security Bulletin has been just released and is available here:
https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-013-2015.txt
As per the previous discussions about recent problems with verifying
digital signatures on messages sent to Google Groups (thanks to
automatic footer addition by Google), we have decided to change the way
we publish Qubes Security Bulletins, as well as other security-related
info pertinent to the Qubes Project.
Starting today, we will be maintain a Git repository -- "Qubes Security
Pack" -- which will contain all the QSBs released so far, all the keys,
warrant canaries [1], and potentially some additional info or
announcements (e.g. key revocations). The whole repo can be found here:
https://github.com/QubesOS/qubes-secpack
Note that all the keys distributed there should be signed by Qubes
Master Key. The Master Key is also attached in the repo, but should
really be obtained/verified using a different channel.
Additionally, most of the files are signed by core Qubes
developers (currently by Marek and myself) via detached signatures as
well as git tag signatures.
The are several advantages of using Git to distribute all these information:
1) Git repo is a collection of files, some of which can be detached GPG
signatures for other files and we can ensure all these files are
distributed together.
2) Git makes it easy for people to clone and redistribute these
collection of files, as well as to easily host them and view on the Web.
3) Git provides for signed tags mechanisms which is another mean we
utilize to ensure integrity of the distributed files.
A few words about the Warrant Canary which we've just introduced today,
and which can be seen here:
https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt
Even though we're not providing any kind of services (such as e.g. email
hosting), that could be searched or tapped by authorities, there are
other possibilities that worry us [2], in the light of various recent
law "developments", such as those that might be coercing people to hand
over their private keys to authorities.
Until we fully decentralize the root of trust for Qubes, something that
requires the move to deterministic builds [3], and so won't happen
very soon, the possibility of having to disclose any of the Qubes
signing keys to anybody might have pretty serious consequences for those
who decided to entrust Qubes with anything serious. And we would like to
somehow minimize these consequences with this canary thing.
Additionally the canary is a nice way of ensuring "freshness" of our
messaging to the community.
Of course the canary doesn't solve all the problems. E.g. if my signing
keys were somehow stolen without our knowledge, it wouldn't help.
Neither it could help in case me being or becoming a miscreant. And
probably it doesn't address many other potential problems, which could
only be solved one day with a multi-signature scheme. But anyway, until
that time, this is the best we can do, I think.
And congrats to Jann for the very interesting clipboard attack (even
though mostly theoretical, still very cool)!
Thanks,
joanna.
--
The Qubes Security Team
https://www.qubes-os.org/doc/SecurityPage
[1] http://en.wikipedia.org/wiki/Warrant_canary
[2] Especially myself, because I'm currently the Root Of Trust for all
Qubes binaries :/
[3] Deterministic builds are required because it's the only way we can
implement multiple signature scheme for distributed binaries.
{% endhighlight %}
How to Obtain, Verify, and Read
-------------------------------
The following example demonstrates one method of obtaining the QSP, verifying its contents, and reading them.
1. Clone the QSP repo.
{% highlight trac-wiki %}
[user@qubes ~]$ git clone https://github.com/QubesOS/qubes-secpack.git
Cloning into 'qubes-secpack'...
remote: Counting objects: 195, done.
remote: Total 195 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
Resolving deltas: 100% (47/47), done.
Checking connectivity... done.
{% endhighlight %}
2. Import the included PGP keys.
{% highlight trac-wiki %}
[user@qubes ~]$ gpg --import qubes-secpack/keys/*/*
gpg: directory `/home/user/.gnupg' created
gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
gpg: keyring `/home/user/.gnupg/secring.gpg' created
gpg: keyring `/home/user/.gnupg/pubring.gpg' created
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported
gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 42CFA724: public key "Marek Marczykowski-G<>recki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported
gpg: key 36879494: public key "Qubes Master Signing Key" imported
gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 1830E06A: public key "Marek Marczykowski-G<>recki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported
gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported
gpg: Total number processed: 17
gpg: imported: 17 (RSA: 17)
gpg: no ultimately trusted keys found
{% endhighlight %}
3. Verify and trust the Qubes Master Signing Key.
{% highlight trac-wiki %}
[user@qubes ~]$ gpg --edit-key 36879494
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
{% endhighlight %}
> **Important!**
> In order to verify the authenticity of the Qubes Master Signing Key prior to trusting it, you should obtain the Qubes Master Signing Key fingerprint from a trustworthy source (ideally, multiple sources) *other than* this website and visually compare it (them) to the fingerprint displayed in the preceding step, ensuring they match. You can read more about digital signatures and key verification [here](/doc/VerifyingSignatures/).
1. Verify and read the canaries.
{% highlight trac-wiki %}
[user@qubes ~]$ cd qubes-secpack/canaries/
[user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
[user@qubes canaries]$ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A
gpg: Good signature from "Marek Marczykowski-G<>recki (Qubes security pack) <marmarek@invisiblethingslab.com>"
[user@qubes canaries]$ cat canary-001-2015.txt
---===[ Qubes Canary #1 ]===---
[...]
{% endhighlight %}
2. Verify and read the QSBs.
{% highlight trac-wiki %}
[user@qubes canaries]$ cd ../QSBs/
[user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.joanna qsb-013-2015.txt
gpg: Signature made Mon Jan 5 21:22:14 2015 UTC using RSA key ID 92C7B3DC
gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
[user@qubes QSBs]$ gpg --verify qsb-013-2015.txt.sig.marmarek qsb-013-2015.txt
gpg: Signature made Mon Jan 5 21:38:11 2015 UTC using RSA key ID 1830E06A
gpg: Good signature from "Marek Marczykowski-G<>recki (Qubes security pack) <marmarek@invisiblethingslab.com>"
[user@qubes QSBs]$ cat qsb-013-2015.txt
---===[ Qubes Security Bulletin #13 ]===---
[...]
{% endhighlight %}

36
SecurityPage.md
View File

@ -1,36 +0,0 @@
---
layout: doc
title: SecurityPage
permalink: /doc/SecurityPage/
redirect_from: /wiki/SecurityPage/
---
Reporting Security Issues in Qubes OS
=====================================
If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you!
We promise to treat any reported issue seriously and, if the investigation confirms it affects Qubes, to patch it within a reasonable time, and also to release a public Security Bulletin that describes the issue, discusses potential impact of the vulnerability, references applicable patches or workarounds, and also credits the discoverer.
The list of all Qubes Security Advisories published so far can be found [here](/doc/SecurityBulletins/).
Qubes Security Team
-------------------
The Qubes Security Team can be contacted via email using the following address:
{% highlight trac-wiki %}
security at qubes-os dot org
{% endhighlight %}
Qubes Security Team GPG Key
---------------------------
Please use the [this GPG key](http://keys.qubes-os.org/keys/qubes-os-security-team-key.asc) for encrypting any emails send to this address. Like all the GPG keys used by the Qubes project, this key is signed with the Qubes Master key. Please see [this page](/doc/VerifyingSignatures/) for more information on how to verify the keys.
Members of the Security Team
----------------------------
- Joanna Rutkowska \<joanna at invisiblethingslab dot com\>
- Marek Marczykowski \<marmarek at invisiblethingslab dot com\>

37
SourceCode.md
View File

@ -1,37 +0,0 @@
---
layout: doc
title: SourceCode
permalink: /doc/SourceCode/
redirect_from: /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:
{% highlight trac-wiki %}
git clone git://github.com/QubesOS/<repo_name>.git <repo_name>
{% endhighlight %}
e.g.:
{% highlight trac-wiki %}
git clone git://github.com/QubesOS/qubes-core-admin.git core-admin
{% endhighlight %}
If you want to contribute to the project, there are two preferred ways:
1. Use github [fork & pull requests](https://guides.github.com/activities/forking/)
2. [sending a patch](/doc/DevelFaq/#q-how-do-i-submit-a-patch) via the project's mailing list (`git format-patch`).

56
StickMounting.md
View File

@ -1,56 +0,0 @@
---
layout: doc
title: StickMounting
permalink: /doc/StickMounting/
redirect_from: /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 mount a USB stick 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](/doc/AssigningDevices/).)
As of Qubes R2 Beta 3, USB stick mounting has been integrated into the Qubes VM Manger 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.
A command-line tool, `qvm-block`, is also available. 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:
{% highlight trac-wiki %}
qvm-block -l
{% endhighlight %}
> This will list all available block devices connected to any USB controller in your system, no matter in 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.
> **Note:** If your device is not listed here, you may refresh the list by calling (from the VM to which device is connected):
>
> {% highlight trac-wiki %}
> sudo udevadm trigger --action=change
> {% endhighlight %}
1. Connect the device to an AppVM:
{% highlight trac-wiki %}
qvm-block -a personal dom0:sda
{% endhighlight %}
**Note:** The order of these parameters was changed in Qubes 1.0-rc1.
> This will attach the device as "/dev/xvdi" in the AppVM.
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, unmount the stick:
{% highlight trac-wiki %}
qvm-block -d <device> <vmname>
{% endhighlight %}
1. You may now remove the device.

48
SystemDoc.md
View File

@ -1,48 +0,0 @@
---
layout: doc
title: SystemDoc
permalink: /doc/SystemDoc/
redirect_from: /wiki/SystemDoc/
---
System Documentation for Developers
===================================
1. Fundamentals:
1. Qubes OS Architecture v0.3 [(pdf)](http://files.qubes-os.org/files/doc/arch-spec-0.3.pdf) (The original 2009 document that started this all...)
2. [Security-critical elements of Qubes OS](/doc/SecurityCriticalCode/)
3. Qubes RPC framework (qrexec):
1. [The Qubes RPC/Service API](/doc/Qrexec/)
2. Example for writing a qrexec service in Qubes OS [blog post](http://theinvisiblethings.blogspot.com/2013/02/converting-untrusted-pdfs-into-trusted.html)
3. [qrexec implementation in Qubes R2](/doc/Qrexec2Implementation/)
4. [qrexec implementation in Qubes R3/Odyssey](/doc/Qrexec3Implementation/)
4. [Qubes GUI virtualization protocol](/doc/GUIdocs/)
5. [Networking in Qubes](/doc/QubesNet/)
6. [Implementation of template sharing and updating](/doc/TemplateImplementation/)
2. Services:
1. [Inter-domain file copying](/doc/Qfilecopy/)
2. [Dynamic memory management in Qubes](/doc/Qmemman/)
3. [Implementation of DisposableVMs](/doc/DVMimpl/)
4. [Article about disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
5. [Dom0 secure update mechanism](/doc/Dom0SecureUpdates/)
6. [VM secure update mechanism?](/doc/VMSecureUpdates/)
3. Debugging:
1. [Profiling python code](/doc/Profiling/)
2. [Test environment in separate machine for automatic tests](/doc/TestBench/)
3. [Automated tests](/doc/AutomatedTests/)
3. [VM-dom0 internal configuration interface](/doc/SystemDoc/VMInterface/)
4. [Debugging Windows VMs](/doc/WindowsDebugging/)
4. Building:
1. [Building Qubes](/doc/QubesBuilder/)
2. [Development Workflow](/doc/DevelopmentWorkflow/)
3. [KDE Dom0 packages for Qubes](/doc/KdeDom0/)
4. [How to build Qubes installation ISO](/doc/InstallationIsoBuilding/)
5. [Building USB passthrough support (experimental)](/doc/USBVM/)
6. [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/BuildingNonFedoraTemplate/)
7. [Building the Archlinux Template](/doc/BuildingArchlinuxTemplate/)

62
SystemDoc/VMInterface.md
View File

@ -1,62 +0,0 @@
---
layout: doc
title: VMInterface
permalink: /doc/SystemDoc/VMInterface/
redirect_from: /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: TODO: describe format and parameters here
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.

108
TemplateImplementation.md
View File

@ -1,108 +0,0 @@
---
layout: doc
title: TemplateImplementation
permalink: /doc/TemplateImplementation/
redirect_from: /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 symlink 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 kernel is chosen in dom0, not VM there must be some way to provide matching kernel modules to VM OS. Qubes kernel dir 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 uses default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to VM as R/O device.
There is special case when VM can have custom kernel - when it is updateable (StandaloneVM or TemplateVM) and kernel is set to "none" (by qvm-prefs). In this case VM uses kernel from "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.

50
Templates.md
View File

@ -1,50 +0,0 @@
---
layout: doc
title: Templates
permalink: /doc/Templates/
redirect_from: /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](/doc/QubesBuilder/).
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](/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](/doc/Templates/Whonix/)
- [Ubuntu](/doc/Templates/Ubuntu/)
- [Archlinux](/doc/Templates/Archlinux/)

76
Templates/FedoraMinimal.md
View File

@ -1,76 +0,0 @@
---
layout: doc
title: FedoraMinimal
permalink: /doc/Templates/FedoraMinimal/
redirect_from: /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:
{% highlight trac-wiki %}
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-20-x64-minimal
{% endhighlight %}
Usage
-----
It is a good idea to clone the original template, and make any changes in the new clone instead:
{% highlight trac-wiki %}
[user@dom0 ~]$ qvm-clone fedora-20-x64-minimal <your new template name>
{% endhighlight %}
The sudo package is not installed by default, so lets install it:
{% highlight trac-wiki %}
[user@F20-Minimal ~]$ su -
[user@F20-Minimal ~]$ yum install sudo
{% endhighlight %}
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 following command: `journalctl`
### as a NetVM
If You want to use this template to for standard NetVMs You should install some more packeges:
{% highlight trac-wiki %}
[user@F20-Minimal ~]$ sudo yum install NetworkManager network-manager-applet wireless-tools dbus-x11 dejavu-sans-fonts tar tinyproxy
{% endhighlight %}
And maybe some more optional but useful packages as well:
{% highlight trac-wiki %}
[user@F20-Minimal ~]$ sudo yum install pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat gnome-keyring
{% endhighlight %}
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 evem more packages
#### Firewall
This template is ready to use for a standard firewall VM. However, using the default minimal template with the default firewall and default update settings will result in an error when attempting to update dom0 (`qubes-dom0-update`), since this process requires `tar`, which is not present by default in the minimal template.
#### VPN
The needed packages are depend on the VPN technology. `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)

29
Templates/Ubuntu.md
View File

@ -1,29 +0,0 @@
---
layout: doc
title: Ubuntu
permalink: /doc/Templates/Ubuntu/
redirect_from: /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.
Install
-------
It can built using [Qubes Builder](/doc/QubesBuilder/). 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).

8
TestPage.md
View File

@ -1,8 +0,0 @@
---
layout: doc
title: TestPage
permalink: /doc/TestPage/
redirect_from: /wiki/TestPage/
---
This is a test.

13
TestTest.md
View File

@ -1,13 +0,0 @@
---
layout: doc
title: TestTest
permalink: /doc/TestTest/
redirect_from: /wiki/TestTest/
---
This is a test page
===================
Please ignore.
![snapshot1.png](/attachment/wiki/TestTest/snapshot1.png)

9
TroubleShooting.md
View File

@ -1,9 +0,0 @@
---
layout: doc
title: TroubleShooting
permalink: /doc/TroubleShooting/
redirect_from: /wiki/TroubleShooting/
---
- [Home directory is out of disk space error](/doc/OutOfmemory/)

8
Trusted_parts.md
View File

@ -1,8 +0,0 @@
---
layout: doc
title: Trusted_parts
permalink: /doc/Trusted_parts/
redirect_from: /wiki/Trusted_parts/
---

17
UsbInstallation.md
View File

@ -1,17 +0,0 @@
---
layout: doc
title: UsbInstallation
permalink: /doc/UsbInstallation/
redirect_from: /wiki/UsbInstallation/
---
How to create a bootable USB stick from Qubes ISO
=================================================
Qubes ISO image is already prepared to boot from USB disk, you just need to copy the ISO onto the USB device, e.g. using dd:
{% highlight trac-wiki %}
dd if=Qubes-R2-Beta2-x86_64-DVD.iso of=/dev/sdX
{% endhighlight %}
**Be sure to use a correct device as the target in the dd command above (instead of sdX)**

101
UserDoc.md
View File

@ -1,101 +0,0 @@
---
layout: doc
title: UserDoc
permalink: /doc/UserDoc/
redirect_from: /wiki/UserDoc/
---
Qubes User Documentation
========================
1. **Basic Reading**
1. [Getting Started](/doc/GettingStarted/)
2. [Security Guidelines](/doc/SecurityGuidelines/)
3. [Glossary of Qubes Terminology](/doc/Glossary/)
2. **Dom0**
1. [Dom0 Command-Line Tools](/doc/DomZeroTools/)
2. [Updating Software in dom0](/doc/SoftwareUpdateDom0/)
3. [Copying Files to and from dom0](/doc/CopyToDomZero/)
4. [Backup, Restoration, and Migration](/doc/BackupRestore/)
5. [Qubes Policy for InterVM Services](/doc/Qrexec/#qubes-services-rpc-policy)
6. Advanced Topics
1. [Installing Anti Evil Maid](/doc/AntiEvilMaid/)
2. [XFCE Installation in dom0](/doc/UserDoc/XFCE/)
3. [Installing ZFS in Qubes](/doc/ZFS/)
4. [Configuring YubiKey for user authentication](/doc/YubiKey/)
5. [Storing AppVMs on Secondary Drives](/doc/SecondaryStorage/)
7. External Links
1. [Customizing the GUI experience with KDE](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)
3. **DomUs**
1. [DomU Command-Line Tools](/doc/VmTools/)
2. **Intra-VM Actions**
1. [Enabling Fullscreen Mode](/doc/FullScreenMode/)
2. [Managing Application Shortcuts](/doc/ManagingAppVmShortcuts/)
3. **Inter-VM Actions**
1. [Copying and Pasting Text Between Domains](/doc/CopyPaste/)
2. [Copying and Moving Files Between Domains](/doc/CopyingFiles/)
3. [Using GPG more securely in Qubes: Split GPG tutorial](/doc/UserDoc/SplitGpg/)
4. **NetVMs and ProxyVMs**
1. [Understanding Qubes Firewall](/doc/QubesFirewall/)
2. [Understanding and Preventing Data Leaks](/doc/DataLeaks/)
3. [How to Install a Transparent Tor ProxyVM (TorVM)](/doc/UserDoc/TorVM/)
4. [How to set up a ProxyVM as a VPN Gateway](/doc/VPN/)
5. [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/NetworkBridgeSupport/)
6. External Links
1. [Creating Custom NetVMs and ProxyVMs](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
2. [How to run TorBrowser using external tor proxy (from TorVM)](https://groups.google.com/group/qubes-devel/msg/34f67194d3422bfa)
3. [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
4. [HTTP filtering proxy in Qubes firewall VM](https://groups.google.com/group/qubes-devel/browse_thread/thread/5252bc3f6ed4b43e/d881deb5afaa2a6c#39c95d63fccca12b)
5. **[TemplateVMs](/doc/Templates/)**
1. [Updating and Installing Software in VMs](/doc/SoftwareUpdateVM/)
2. [Templates: Fedora - minimal](/doc/Templates/FedoraMinimal/)
3. [Templates: Debian](/doc/Templates/Debian/)
4. External Links
1. [Extending \`root.img\` Size](https://groups.google.com/group/qubes-devel/msg/9d1ac581236ca9b4)
6. **DispVMs**
1. [Disposable VMs](/doc/DisposableVms/)
2. [DispVM Customization](/doc/UserDoc/DispVMCustomization/)
7. **HVMs**
1. [Resizing AppVM and HVM Disk Images](/doc/ResizeDiskImage/)
2. [Tips for Using Linux in an HVM](/doc/LinuxHVMTips/)
3. [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/HvmCreate/)
4. External Links
1. [Creating Whonix HVMs in Qubes](https://www.whonix.org/wiki/Qubes)
2. [Creating NetBSD VM](https://groups.google.com/group/qubes-devel/msg/4015c8900a813985)
8. **Windows VMs**
1. [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/WindowsAppVms/)
2. [Advanced options and troubleshooting of Qubes Tools for Windows](/doc/WindowsTools/)
9. Advanced Topics
1. [Configuration files](/doc/UserDoc/ConfigFiles/)
2. [Qubes service framework](/doc/QubesService/)
3. [Note regarding password-less root access in VM](/doc/VMSudo/)
4. **Applications**
1. [Languages](/doc/LanguageLocalization/)
5. **Hardware**
1. [How to Mount USB Sticks to AppVMs](/doc/StickMounting/)
2. [Where are my external storage devices mounted?](/doc/ExternalDeviceMountPoint/)
3. [Assigning PCI Devices to AppVMs](/doc/AssigningDevices/)
4. [Enabling TRIM for SSD disks](/doc/DiskTRIM/)
5. [Configuring a Network Printer](/doc/NetworkPrinter/)
6. [Using External Audio Devices](/doc/ExternalAudio/)
7. Vendor-specific
1. [How to install an Nvidia driver in dom0](/doc/InstallNvidiaDriver/)
2. [Getting Sony Vaio Z laptop to work with Qubes](/doc/SonyVaioTinkering/)
8. External Links
1. [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
2. [Solving problems with Macbook Air 2012](https://groups.google.com/group/qubes-devel/browse_thread/thread/b8b0d819d2a4fc39/d50a72449107ab21#8a9268c09d105e69)
3. [Booting with GRUB2 and GPT](https://groups.google.com/group/qubes-devel/browse_thread/thread/e4ac093cabd37d2b/d5090c20d92c4128#d5090c20d92c4128)

37
UserDoc/DispVMCustomization.md
View File

@ -1,37 +0,0 @@
---
layout: doc
title: DispVMCustomization
permalink: /doc/UserDoc/DispVMCustomization/
redirect_from: /wiki/UserDoc/DispVMCustomization/
---
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.")
{% highlight trac-wiki %}
[user@dom0 ~]$ qvm-run -a fedora-20-x64-dvm gnome-terminal
{% endhighlight %}
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:
{% highlight trac-wiki %}
[user@fedora-20-x64-dvm ~]$ touch /home/user/.qubes-dispvm-customized
{% endhighlight %}
4. Shutdown the VM (either by `poweroff` from VM terminal, or `qvm-shutdown` from dom0 terminal).
5. Regenerate the DispVM template:
{% highlight trac-wiki %}
[user@dom0 ~]$ qvm-create-default-dvm --default-template --default-script
{% endhighlight %}
**Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template.

166
UserDoc/SplitGpg.md
View File

@ -1,166 +0,0 @@
---
layout: doc
title: SplitGpg
permalink: /doc/UserDoc/SplitGpg/
redirect_from: /wiki/UserDoc/SplitGpg/
---
Qubes Split GPG
===============
What is Split GPG and why should I use it instead of the standard GPG?
----------------------------------------------------------------------
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" plays another Qubes AppVM. This way one, not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations, such as encryption/decryption and signing to another, more trusted, network-isolated, domain. This way a compromise of your domain where the Thunderbird or other client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys (we should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then).
The diagram below presents the big picture of Split GPG architecture.
![split-gpg-diagram.png](/attachment/wiki/UserDoc/SplitGpg/split-gpg-diagram.png)
### Advantages of Split GPG vs. traditional GPG with a smart card
It is often thought that the use of smart cards for private key storage guarantees ultimate safety. While this might be true (unless the attacker can find a usually-very-expensive-and-requiring-physical-presence way to extract the key from the smart card) but only with regards to the safety of the private key itself. However, there is usually nothing that could stop the attacker from requesting the smart card to perform decryption of all the user documents the attacker has found or need to decrypt. In other words, while protecting the user's private key is an important task, we should not forget that ultimately it is the user data that are to be protected and that the smart card chip has no way of knowing the requests to decrypt documents are now coming from the attacker's script and not from the user sitting in front of the monitor. (Similarly the smart card doesn't make the process of digitally signing a document or a transaction in any way more secure -- the user cannot know what the chip is really signing. Unfortunately this problem of signing reliability is not solvable by Split GPG)
With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running. This way it would be easy to spot unexpected requests to decrypt documents.
![r2-split-gpg-1.png](/attachment/wiki/UserDoc/SplitGpg/r2-split-gpg-1.png) ![r2-split-gpg-3.png](/attachment/wiki/UserDoc/SplitGpg/r2-split-gpg-3.png)
### Current limitations
- Current implementation requires importing of public keys to the vault domain. This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code. See ticket \#474 for more details and plans how to get around this problem, as well as the section on [using split GPG with subkeys](/wiki/UserDoc/SplitGpg#Advanced:UsingSplitGPGwithSubkeys) below.
- It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved. Perhaps the GPG backend domain could start a Disposable VM and have the to-be-signed document displayed there? To Be Determined.
- Verifying detached signatures does not work (see \#900). You have to have public keys in AppVM and some means to use different command to verify them. Both git and Enigmail does not allow that and you have to choose between [SplitGpg](/wiki/UserDoc/SplitGpg) and PGP/MIME.
Configuring and using Split GPG
-------------------------------
Start with creating a dedicated AppVM for storing your keys (the GPG backend domain). It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose. In later examples this AppVM is named `work-gpg`, but of course it might have any other name.
### Setting up the GPG backend domain
Make sure the gpg is installed there and there are some private keys in the keyring, e.g.:
{% highlight trac-wiki %}
[user@work-gpg ~]$ gpg -K
/home/user/.gnupg/secring.gpg
-----------------------------
sec 4096R/3F48CB21 2012-11-15
uid Qubes OS Security Team <security@qubes-os.org>
ssb 4096R/30498E2A 2012-11-15
(...)
{% endhighlight %}
This is pretty much all that is required. However one might also want to modify the default timeout which tells the backend for how long the user's approval for key access should be valid (default 5 minutes). This is adjustable via `QUBES_GPG_AUTOACCEPT` variable. One can override it e.g. in `~/.bash_profile`:
{% highlight trac-wiki %}
[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.bash_profile
{% endhighlight %}
### Configuring the client apps to use split GPG backend
Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
{% highlight trac-wiki %}
[user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work ~]$ gpg -K
[user@work ~]$ qubes-gpg-client -K
/home/user/.gnupg/secring.gpg
-----------------------------
sec 4096R/3F48CB21 2012-11-15
uid Qubes OS Security Team <security@qubes-os.org>
ssb 4096R/30498E2A 2012-11-15
(...)
[user@work ~]$ qubes-gpg-client secret_message.txt.asc
(...)
{% endhighlight %}
Note that running normal `gpg -K` in the demo above shows no private keys stored in this AppVM.
### Configuring Thunderbird/Enigmail for use with Split GPG
However, when using Thunderbird with Enigmail extension it is not enough, because Thunderbird doesn't preserve the environment variables. Instead it is recommended to use a simple script provided by `/usr/bin/qubes-gpg-client-wrapper` file by pointing Enigmail to use this script instead of the standard GnuPG binary:
![tb-enigmail-split-gpg-settings-2.png](/attachment/wiki/UserDoc/SplitGpg/tb-enigmail-split-gpg-settings-2.png)
The script also sets the QUBES\_GPG\_DOMAIN variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the AppVM reboot, of course.
{% highlight trac-wiki %}
[user@work ~]$ sudo bash
[user@work ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
{% endhighlight %}
*NOTE*: A recent engimail update, version `thunderbird-enigmail-1.7-1`, introduced changes in how Enigmail expects to execute GPG binary and so requires an updated split-gpg package with version \>= `qubes-gpg-split-2.0.7-1`. Please make sure you have all the latest qubes packages installed in your template.
### How to use `gpg2` instead of `gpg`
In your GPG backend domain's TemplateVM:
1. `sudo vim /etc/qubes-rpc/qubes.Gpg`
2. Change `/usr/bin/gpg` to `/usr/bin/gpg2`.
3. Ensure that your key has a **blank passphrase**. If not, you will encounter an error.
4. Shut down the TemplateVM and restart the GPG backend domain.
### Importing public keys
Use `qubes-gpg-import-key` in the client AppVM to import the key into the GPG backend VM. Of course a (safe, unspoofable) user consent dialog box is displayed to accept this.
{% highlight trac-wiki %}
[user@work ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
{% endhighlight %}
![r2-split-gpg-5.png](/attachment/wiki/UserDoc/SplitGpg/r2-split-gpg-5.png)
Advanced: Using Split GPG with Subkeys
--------------------------------------
Users with particularly high security requirements may wish to use split GPG with [​subkeys](https://wiki.debian.org/Subkeys). However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model. Nonetheless, if signing others' keys is not required, then split GPG with subkeys offers unparalleled security for one's master secret key.
### Setup Description
In this example, the following keys are stored in the following locations:
||
|**PGP Key(s)**|**VM Name**|
|master secret key|vault|
|secret subkeys|work-gpg|
|public key|work-email|
master secret key (sec)
It is recommended that this key be created as a **certify-only (C)** key, i.e., a key which is capable only of signing other keys. This key may be created *without* an expiration date. This is for two reasons. First, the master secret key is never to leave the vault VM, so it is extremely unlikely ever to be obtained by an adversary (see below). Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key, or he does not. If he does, then he can simply use the passphrase in order to legally extend the expiration date of the key (or remove it entirely). If he does not, then he cannot use the key. In either case, an expiration date provides no additional benefit. It is, however, recommended that a **revocation certificate** be created so that the master keypair may be revoked in the (exceedingly unlikely) event that an adversary obtains both the master secret key *and* the passphrase. It is recommended that the master secret key passphrase only ever be input in the vault VM. (Subkeys should use a different passphrase; see below).
secret subkeys (ssb)
It is recommended that two subkeys be created: one for **signing (S)**, and one for **encryption (E)**. It is further recommended that a *different* passphrase be used for these subkeys than for the master secret key. Finally, it is recommended that each of these subkeys be created with a reasonable expiration date (e.g., one year), and that a *new* set of subkeys be created whenever the existing set expires, rather than the expiration date of the existing keys being extended. This is because an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted with that subkey. If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the work-gpg VM being compromised; see below) in order to decrypt *all* of the user's emails. If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
public key (pub)
This is the complement of the master secret key. It should be uploaded to keyservers and may be signed by others.
vault
This is a network-isolated VM. The initial master keypair and subkeys are generated in this VM. The master secret key *never* leaves this VM under *any* circumstances. No files or text is *ever* [copied](/wiki/CopyingFiles#Oninter-domainfilecopysecurity) or [pasted](/wiki/CopyPaste#Clipboardautomaticpolicyenforcement) into this VM under *any* circumstances.
work-gpg
This is a network-isolated VM. This VM is used *only* as the GPG backend for work-email. The secret subkeys (but *not* the master secret key) are [copied](/wiki/CopyingFiles) from the vault VM to this VM. Files from less trusted VMs are *never* copied into this VM under *any* circumstances.
work-email
This VM has access to the mail server. It accesses the work-gpg VM via the split GPG protocol. The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
### Security Benefits
In the standard split GPG setup, there are at least two ways in which the work-gpg VM might be compromised. First, an attacker who is capable of exploiting a hypothetical bug in work-email's [​MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the work-email VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the work-gpg VM), giving the attacker control of the work-gpg VM. Second, a malicious public key file which is imported to the work-gpg VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the work-gpg VM. In either case, such an attacker might then be able to leak both the master secret key and its passphrase (which is regularly input in the work-gpg VM and is therefore easily obtained by an attacker who controls this VM) back to the work-email VM or to another VM (e.g., the netvm, which is always untrusted by default) via the split GPG protocol or other [covert channels](/wiki/DataLeaks).
In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the work-gpg VM will not be able to obtain the user's master secret key since it is simply not there. Rather, the master secret key remains in the vault VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the work-gpg VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
<sup>\*</sup>In order to gain access to the vault VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/wiki/SoftwareUpdateVM#NotesontrustingyourTemplateVMs) upon which the vault VM is based.
### Subkey Tutorials and Discussions
(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments. As always, exercise caution and use your good judgment.)
- [​"OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
- [​"Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
- [​"GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
- [​"Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)

65
UserDoc/XFCE.md
View File

@ -1,65 +0,0 @@
---
layout: doc
title: XFCE
permalink: /doc/UserDoc/XFCE/
redirect_from: /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:
{% highlight trac-wiki %}
qubes-dom0-update --enablerepo=qubes-dom0-unstable @XFCE
{% endhighlight %}
Then you need to create /etc/sysconfig/desktop to stay with KDM, as GDM still starts invalid Xorg startup script:
{% highlight trac-wiki %}
DISPLAYMANAGER=KDE
{% endhighlight %}
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:
{% highlight trac-wiki %}
<!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>
{% endhighlight %}
2. add it to the panel: right click on panel, "add new items", select "XFCE menu", choose custom menu file - just created one

159
VerifyingSignatures.md
View File

@ -1,159 +0,0 @@
---
layout: doc
title: VerifyingSignatures
permalink: /doc/VerifyingSignatures/
redirect_from: /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.,
{% highlight trac-wiki %}
gpg --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
{% endhighlight %}
or downloaded [here](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) and imported with gpg,
{% highlight trac-wiki %}
$ gpg --import ./qubes-master-signing-key.asc
{% endhighlight %}
or fetched directly with gpg.
{% highlight trac-wiki %}
$ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
{% endhighlight %}
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:
{% highlight trac-wiki %}
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
{% endhighlight %}
There should also be a copy of this key at the project's main website, in the [Qubes Security Pack](/doc/SecurityPack/), 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:
{% highlight trac-wiki %}
$ 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
{% endhighlight %}
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.
{% highlight trac-wiki %}
$ 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)
{% endhighlight %}
You can also download all the currently used developers' signing keys and current and older release signing keys (and also a copy of the Qubes Master Signing Key) from the [keys directory on our server](https://keys.qubes-os.org/keys/) and from the [Qubes Security Pack](/doc/SecurityPack/).
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):
{% highlight trac-wiki %}
$ 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
{% endhighlight %}
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)):
{% highlight trac-wiki %}
$ 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
{% endhighlight %}
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 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:
{% highlight trac-wiki %}
$ git tag -v <tag name>
{% endhighlight %}

43
VersionScheme.md
View File

@ -1,43 +0,0 @@
---
layout: doc
title: VersionScheme
permalink: /doc/VersionScheme/
redirect_from: /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”).
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 [http://keys.qubes-os.org/keys/](http://keys.qubes-os.org/keys/).

14
VmTools.md
View File

@ -1,14 +0,0 @@
---
layout: doc
title: VmTools
permalink: /doc/VmTools/
redirect_from: /wiki/VmTools/
---
VM tools:
- [qvm-copy-to-vm](/doc/VmTools/QvmCopyToVm/)
- [qvm-open-in-dvm](/doc/VmTools/QvmOpenInDvm/)
- [qvm-open-in-vm](/doc/VmTools/QvmOpenInVm/)
- [qvm-run](/doc/VmTools/QvmRun/)

47
WikiStart.md
View File

@ -1,47 +0,0 @@
---
layout: doc
title: Qubes OS Project
permalink: /
redirect_from:
- "/wiki/"
- "/wiki/WikiStart/"
- "/trac/"
- "/trac/WikiStart/"
---
Welcome to the Qubes OS Project
===============================
[![Qubes OS Architecture](/attachment/wiki/QubesArchitecture/qubes-arch-diagram-1.png)](/doc/QubesArchitecture/)
Qubes is an open-source operating system designed to provide strong security for desktop computing using **Security by Compartmentalization** approach. Qubes is based on Xen, the X Window System, and Linux, and can run most Linux applications and utilize most of the Linux drivers. Qubes **Release 1** was released in September 2012 and **Release 2** in September 2014. Qubes also supports Windows-based AppVMs beginning with Release 2 (currently in "Beta"). Qubes **Release 3** is coming soon and will introduce **Hypervisor Abstraction Layer (HAL)**, allowing easy porting to alternative virtualization systems.
- [A Simple Introduction to Qubes](/doc/SimpleIntro/)
- [Getting Started](/doc/GettingStarted/)
- [Qubes OS Tutorial slides by ITL](http://www.invisiblethingslab.com/resources/2014/LinuxCon_2014_Qubes_Tutorial.pdf) (LinuxCon October 2014)
- [Screenshots](/doc/QubesScreenshots/)
- [Architecture Overview](/doc/QubesArchitecture/), and also the more recent: [Why Qubes OS is more than a bunch of VMs?](http://www.invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf)
- [Security](/doc/QubesSecurity/)
- [FAQ](/doc/UserFaq/)
- [User Documentation](/doc/UserDoc/)
- [How is Qubes OS different from...?](http://theinvisiblethings.blogspot.com/2012/09/how-is-qubes-os-different-from.html)
- Beyond Qubes R2 -- the [Qubes Odyssey Framework](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html)
Recent News
-----------
- `Mar 21, 2013` Introducing Qubes Odyssey Framework [article](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html)
- `Jun 21, 2013` Qubes OS R3 Alpha preview: Odyssey HAL in action! [announcement](http://theinvisiblethings.blogspot.com/2013/06/qubes-os-r3-alpha-preview-odyssey-hal.html)
- `Nov 26, 2013` Windows 7 seamless GUI integration coming to Qubes OS! [article](http://theinvisiblethings.blogspot.com/2013/11/windows-7-seamless-gui-integration.html)
- `Dec 11, 2013` Qubes OS R2 Beta 3 has been released! [announcement](http://theinvisiblethings.blogspot.com/2013/12/qubes-r2-beta-3-has-been-released.html)
- `Feb 16, 2014` Qubes OS selected as a finalist of Access Innovation Prize 2014 for Endpoint Security Solution [announcement](https://www.accessnow.org/blog/2014/02/13/endpoint-security-prize-finalists-announced?utm_content=buffere803e&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer)
- `Mar 28, 2014` [Article about Qubes OS](http://www.economist.com/blogs/babbage/2014/03/computer-security) in The Economist
- `Apr 12, 2014` [Article about Qubes OS](https://pressfreedomfoundation.org/blog/2014/04/operating-system-can-protect-you-even-if-you-get-hacked) by the [Freedom of the Press Foundation](https://pressfreedomfoundation.org/about/board)
- `Apr 21, 2014` Qubes OS R2 rc1 has been released! [announcement](http://theinvisiblethings.blogspot.com/2014/04/qubes-os-r2-rc1-has-been-released.html)
- `Jul 03, 2014` ITL to present on Qubes OS at LinuxCon Europe: a keynote by Joanna Rutkowska and hands-on training by the core dev team! [conference website](http://events.linuxfoundation.org/events/linuxcon-europe)
- `Jul 16, 2014` Qubes Wiki now uses a CA-signed SSL cert (but you might also want to [read](https://groups.google.com/forum/#!topic/qubes-users/LsDpKnwN6w8) also why this is mostly irrelevant)
- `Aug 06, 2014` Qubes OS R2 rc2 has been released! [announcement](http://theinvisiblethings.blogspot.com/2014/08/qubes-os-r2-rc2-debian-template-ssled.html)
- `Sep 26, 2014` **Qubes OS R2** has been released! [announcement](http://theinvisiblethings.blogspot.com/2014/09/announcing-qubes-os-release-2.html)
- `Oct 19, 2014` LinuxCon EU 2014 slides: [keynote](http://www.invisiblethingslab.com/resources/2014/LinuxCon_2014_Qubes_Keynote.pdf) and [tutorial](http://www.invisiblethingslab.com/resources/2014/LinuxCon_2014_Qubes_Tutorial.pdf)
- `Nov 20, 2014` [Article about Qubes OS](http://www.wired.com/2014/11/protection-from-hackers/) in Wired

8
amChartTest.md
View File

@ -1,8 +0,0 @@
---
layout: doc
title: amChartTest
permalink: /doc/amChartTest/
redirect_from: /wiki/amChartTest/
---

40
GettingStarted.md → en/basics/getting-started.md
View File

@ -1,14 +1,16 @@
---
layout: doc
title: GettingStarted
permalink: /doc/GettingStarted/
redirect_from: /wiki/GettingStarted/
title: Getting Started
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.
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](/downloads/) page.
Now that you've installed Qubes, let's cover some basic concepts.
@ -27,14 +29,14 @@ Each domain, apart from having a distinct name, is also assigned a **label**, wh
![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!)
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](/en/doc/security-guidelines/#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](/doc/DomZeroTools/).
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)
@ -51,19 +53,15 @@ You can start apps directly from the start menu. Each domain has its own menu di
![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 applictions, 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.
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:
{% highlight trac-wiki %}
qvm-run -a <domain> "<app name> [arguments]"
{% endhighlight %}
qvm-run -a <domain> "<app name> [arguments]"
e.g.:
{% highlight trac-wiki %}
qvm-run -a red firefox
{% endhighlight %}
qvm-run -a untrusted firefox
Adding, Removing, and Listing Domains
-------------------------------------
@ -81,7 +79,7 @@ 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](/doc/CopyingFiles/).
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.
@ -96,30 +94,26 @@ To allow domains to enter full screen mode, one should edit the `/etc/qubes/guid
E.g. to allow all domains to enter full screen mode, set `allow_fullscreen` flag to `true` in the `global` section:
{% highlight trac-wiki %}
global: {
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;
};
{% endhighlight %}
};
To allow only select AppVMs to enter full screen mode, create a per-VM section, and set `allow_fullscreen` flag there to `true`:
{% highlight trac-wiki %}
VM: {
VM: {
work: {
allow_fullscreen = true;
};
};
{% endhighlight %}
};
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](/doc/UserDoc/).
Now that you're familiar with the basics, please have a look at the rest of the [documentation](/en/doc/).

23
SimpleIntro.md → en/basics/intro.md
View File

@ -1,8 +1,11 @@
---
layout: doc
title: SimpleIntro
permalink: /doc/SimpleIntro/
redirect_from: /wiki/SimpleIntro/
title: Introduction
permalink: /en/intro/
redirect_from:
- /intro/
- "/doc/SimpleIntro/"
- "/wiki/SimpleIntro/"
---
A Simple Introduction to Qubes
@ -23,7 +26,7 @@ Most people use an operating system like Windows or OS X on their desktop and la
Aren't antivirus programs and firewalls enough?
-----------------------------------------------
Unfortunately, conventional security approaches like antivirus programs and (softare 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.
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?
--------------------------------
@ -40,7 +43,7 @@ Booting your computer from a live CD (or DVD) when you need to perform sensitive
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 effectivley compromised.
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.
@ -54,7 +57,7 @@ Using a separate physical computer for sensitive activities can certainly be mor
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 seaparation 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.)
- 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:
@ -70,8 +73,8 @@ 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](/doc/UserDoc/) and the [FAQ](/doc/UserFaq/).
- If you're a developer, there's dedicated [documentation](/doc/SystemDoc/) and an [FAQ](/doc/DevelFaq/) just for you.
- Ready to give Qubes a try? Head on over to the [download page](/doc/QubesDownloads/).
- Once you've installed Qubes, here's a guide on [getting started](/doc/GettingStarted/).
- 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/).

12
QubesLists.md → en/basics/mailing-lists.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: QubesLists
permalink: /doc/QubesLists/
redirect_from: /wiki/QubesLists/
title: Mailing Lists
permalink: /en/doc/mailing-lists/
redirect_from:
- /doc/QubesLists/
- /wiki/QubesLists/
---
Qubes Mailing Lists
@ -45,8 +47,8 @@ This list is for helping users solve various daily problems with Qubes OS. Examp
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](/doc/UserFaq/)
- [Qubes User Guides](/doc/UserDoc/) \<-- for questions about how to use Qubes OS
- [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

108
UserFaq.md → en/basics/user-faq.md
View File

@ -1,45 +1,54 @@
---
layout: doc
title: UserFaq
permalink: /doc/UserFaq/
redirect_from: /wiki/UserFaq/
title: Users' FAQ
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)
[General Questions](#general-questions)
---------------------------------------
* [Is Qubes just another Linux distribution?](#is-qubes-just-another-linux-distribution)
* [How is Qubes different from other security solutions?](#how-is-qubes-different-from-other-security-solutions)
* [What is the main concept behind Qubes?](#what-is-the-main-concept-behind-qubes)
* [What about other approaches to security?](#what-about-other-approaches-to-security)
* [What about safe languages and formally verified microkernels?](#what-about-safe-languages-and-formally-verified-microkernels)
* [Why does Qubes use virtualization?](#why-does-qubes-use-virtualization)
* [Does Qubes run every app in a separate VM?](#does-qubes-run-every-app-in-a-separate-vm)
* [Why does Qubes use Xen instead of KVM or some other hypervisor?](#why-does-qubes-use-xen-instead-of-kvm-or-some-other-hypervisor)
* [What about this other/new (micro)kernel/hypervisor?](#what-about-this-othernew-microkernelhypervisor)
* [What's so special about Qubes' GUI virtualization?](#whats-so-special-about-qubes-gui-virtualization)
* [Can I watch YouTube videos in AppVMs?](#can-i-watch-youtube-videos-in-appvms)
* [Can I run applications, like games, which require 3D support?](#can-i-run-applications-like-games-which-require-3d-support)
* [Is Qubes a multi-user system?](#is-qubes-a-multi-user-system)
* [Why passwordless sudo?](#why-passwordless-sudo)
* [How should I report documentation issues?](#how-should-i-report-documentation-issues)
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)
[Installation & Hardware Compatibility](#installation--hardware-compatibility)
------------------------------------------------------------------------------
* [How much disk space does each AppVM require?](#how-much-disk-space-does-each-appvm-require)
* [How much memory is recommended for Qubes?](#how-much-memory-is-recommended-for-qubes)
* [Can I install Qubes on a system without VT-x?](#can-i-install-qubes-on-a-system-without-vt-x)
* [Can I install Qubes on a system without VT-d?](#can-i-install-qubes-on-a-system-without-vt-d)
* [Can I use AMD-v instead of VT-x?](#can-i-use-amd-v-instead-of-vt-x)
* [Can I install Qubes in a virtual machine (e.g., on VMWare)?](#can-i-install-qubes-in-a-virtual-machine-eg-on-vmware)
* [Why does my network adapter not work?](#why-does-my-network-adapter-not-work)
[Common Problems](#common-problems)
-----------------------------------
* [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)
* [My keyboard layout settings are not behaving correctly. What should I do?](#my-keyboard-layout-settings-are-not-behaving-correctly-what-should-i-do)
* [My dom0 and/or TemplateVM update stalls when attempting to update via …](#my-dom0-andor-templatevm-update-stalls-when-attempting-to-update-via-the-gui-tool-what-should-i-do)
* [How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?](#how-do-i-run-a-windows-hvm-in-non-seamless-mode-ie-as-a-single-window)
* [I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.](#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot)
* [I assigned a PCI device to 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)
-----------------
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 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
-----------------
@ -62,7 +71,7 @@ The other two popular [approaches](http://theinvisiblethings.blogspot.com/2008/0
### 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](http://files.qubes-os.org/files/doc/arch-spec-0.3.pdf).
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?
@ -74,7 +83,7 @@ No! This would not make much sense. Qubes uses lightweight VMs to create securit
### 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](http://files.qubes-os.org/files/doc/arch-spec-0.3.pdf).
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?
@ -132,7 +141,7 @@ Create an issue in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues
Installation & Hardware Compatibility
-------------------------------------
(See also: [System Requirements](/doc/SystemRequirements/) and [Hardware Compatibility List](/hcl/).)
(See also: [System Requirements](/en/doc/system-requirements/) and [Hardware Compatibility List](/hcl/).)
### How much disk space does each AppVM require?
@ -185,7 +194,28 @@ 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](/doc/Dom0Tools/QvmPrefs/).)
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?
@ -197,11 +227,7 @@ 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`:
{% highlight trac-wiki %}
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
{% endhighlight %}

35
BackupEmergencyRestoreV2.md → en/common-tasks/backup-emergency-restore-v2.md
View File

@ -1,7 +1,8 @@
---
layout: doc
title: Emergency Backup Recovery - format version 2
permalink: /doc/BackupEmergencyRestoreV2/
permalink: /en/doc/backup-emergency-restore-v2/
redirect_from: /doc/BackupEmergencyRestoreV2/
---
Emergency Backup Recovery without Qubes - format version 2
@ -15,7 +16,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
{% highlight trac-wiki %}
~~~
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
backup-header.hmac
@ -31,17 +32,17 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
vm1/whitelisted-appmenus.list.000.hmac
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
{% endhighlight %}
~~~
1. Verify the integrity of the `private.img` file which houses your data.
{% highlight trac-wiki %}
~~~
[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
{% endhighlight %}
~~~
**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.
@ -49,59 +50,59 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Decrypt the `private.img` file.
{% highlight trac-wiki %}
~~~
[user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
{% endhighlight %}
~~~
**Note:** For multi-part files, a loop can be used:
{% highlight trac-wiki %}
~~~
for f in private.img.*; do
openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
${f/.img/.img.dec}
done
{% endhighlight %}
~~~
**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.
{% highlight trac-wiki %}
~~~
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
{% endhighlight %}
~~~
**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.
{% highlight trac-wiki %}
~~~
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
{% endhighlight %}
~~~
**Note:** For multi-part files, a script is required:
1. Create a `new-volume-script`:
{% highlight trac-wiki %}
~~~
#!/bin/sh
name=`expr $TAR_ARCHIVE : '\(.*\)\..*'`
suffix=`printf %03d $[ $TAR_VOLUME - 1 ]`
echo $name.$suffix >&$TAR_FD
{% endhighlight %}
~~~
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.
{% highlight trac-wiki %}
~~~
[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!
{% endhighlight %}
~~~
**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:

101
en/common-tasks/backup-emergency-restore-v3.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

14
BackupRestore.md → en/common-tasks/backup-restore.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: BackupRestore
permalink: /doc/BackupRestore/
redirect_from: /wiki/BackupRestore/
title: Backup, Restoration, and Migration
permalink: /en/doc/backup-restore/
redirect_from:
- /doc/BackupRestore/
- /wiki/BackupRestore/
---
Qubes Backup, Restoration, and Migration
@ -17,7 +19,7 @@ Qubes Backup, Restoration, and Migration
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/Dom0Tools/QvmBackup/) and [qvm-backup-restore](/doc/Dom0Tools/QvmBackupRestore/).
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
-----------------
@ -32,7 +34,7 @@ Creating a Backup
1. Select the destination for the backup:
- If you wish to send your backup to a [USB mass storage device](/doc/StickMounting/), 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 [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.
@ -54,7 +56,7 @@ Restoring from a Backup
1. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/StickMounting/), select the device in the dropdown box next to **Device**.
- 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.

22
CopyPaste.md → en/common-tasks/copy-paste.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: CopyPaste
permalink: /doc/CopyPaste/
redirect_from: /wiki/CopyPaste/
title: Copy and Paste
permalink: /en/doc/copy-paste/
redirect_from:
- /doc/CopyPaste/
- /wiki/CopyPaste/
---
Copy and Paste between domains
@ -44,7 +46,7 @@ You may now paste the log contents to any VM as you normally would (i.e., Ctrl-S
For data other than logs, there are two options:
1. [Copy it as a file.](/doc/CopyToDomZero/)
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
@ -52,22 +54,22 @@ Clipboard automatic policy enforcement
The Qubes clipboard policy is configurable in:
{% highlight trac-wiki %}
~~~
/etc/qubes-rpc/policy/qubes.ClipboardPaste
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
$anyvm vault deny
$anyvm $anyvm ask
{% endhighlight %}
~~~
Shortcut Configuration
----------------------
The copy/paste shortcuts are configurable in:
{% highlight trac-wiki %}
~~~
/etc/qubes/guid.conf
{% endhighlight %}
~~~

16
CopyToDomZero.md → en/common-tasks/copy-to-dom0.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: CopyToDomZero
permalink: /doc/CopyToDomZero/
redirect_from: /wiki/CopyToDomZero/
title: Copying to and from dom0
permalink: /en/doc/copy-to-dom0/
redirect_from:
- /doc/CopyToDomZero/
- /wiki/CopyToDomZero/
---
Copying files to between VMs and Dom0
@ -12,15 +14,15 @@ First, there should normally be few reasons for the user to want to copy files f
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):
{% highlight trac-wiki %}
~~~
qvm-run --pass-io <src_domain> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
{% endhighlight %}
~~~
BTW, you can use the same method to copy files from Dom0 to VMs:
{% highlight trac-wiki %}
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dst_domain> 'cat > /path/to/file_name_in_appvm'
{% endhighlight %}
~~~
### Copying logs from dom0

10
CopyingFiles.md → en/common-tasks/copying-files.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: CopyingFiles
permalink: /doc/CopyingFiles/
redirect_from: /wiki/CopyingFiles/
title: Copying Files between Domains
permalink: /en/doc/copying-files/
redirect_from:
- /doc/CopyingFiles/
- /wiki/CopyingFiles/
---
Copying files between domains
@ -26,7 +28,7 @@ GUI
CLI
---
[qvm-copy-to-vm](/doc/VmTools/QvmCopyToVm/)
[qvm-copy-to-vm](/en/doc/vm-tools/qvm-copy-to-vm/)
On inter-domain file copy security
----------------------------------

59
DisposableVms.md → en/common-tasks/dispvm.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: DisposableVms
permalink: /doc/DisposableVms/
redirect_from: /wiki/DisposableVms/
title: Disposable VMs
permalink: /en/doc/dispvm/
redirect_from:
- /doc/DisposableVms/
- /wiki/DisposableVMs/
---
Disposable VMs (DispVMs)
@ -13,17 +15,23 @@ 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 Scripts -\> Open in Disposable VM. Wait a few seconds and an 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 view this very file. Once you close the viewing application then whole Disposable VM will get destroyed.
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 -\> Disposable VM -\> Firefox and wait a few seconds until a web browser starts. Once you close the viewing application then whole Disposable VM will get destroyed.
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)
@ -32,9 +40,9 @@ 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.:
{% highlight trac-wiki %}
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
{% endhighlight %}
~~~
The qvm-open-in-dvm will not exit until you close the application in the Disposable VM.
@ -43,9 +51,9 @@ 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 ;)
{% highlight trac-wiki %}
[joanna@dom0 ~]$ echo gnome-terminal | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
{% endhighlight %}
~~~
[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...
@ -54,34 +62,19 @@ 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:
{% highlight trac-wiki %}
[user@vault ~]$ qvm-run '$dispvm' gnome-terminal
{% endhighlight %}
~~~
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
Note the above command is issued in an AppVM, not in Dom0. The created Disposable VM can be normally accessed via other tools, such as e.g. `qvm-copy-to-vm`, using its 'dispX' name, as shown by the Qubes Manager or `qvm-ls` tools. The created Disposable VM will inherit firewall settings of the ancestor VM, which is useful in some cases (e.g. when the original AppVM had networking cut off).
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.
Using a non-default template as a basis for Disposable VM
Customizing Disposable VMs
---------------------------------------------------------
In some situations it might be beneficial 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.
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/)
In order to regenerate Disposable VM "snapshot" (called 'savefile' on Qubes) one can conveniently use the following command in Dom0:
{% highlight trac-wiki %}
[joanna@dom0 ~]$ qvm-create-default-dvm <custom-template-name>
{% endhighlight %}
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):
{% highlight trac-wiki %}
[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
{% endhighlight %}
Disposable VMs and Local Forensics
----------------------------------

16
FullScreenMode.md → en/common-tasks/full-screen-mode.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: FullScreenMode
permalink: /doc/FullScreenMode/
redirect_from: /wiki/FullScreenMode/
title: Full Screen Mode
permalink: /en/doc/full-screen-mode/
redirect_from:
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
---
Enabling Full Screen Mode for select VMs
@ -30,19 +32,19 @@ If you want to enable full screen mode for select VMs, you can do that by creati
**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))
{% highlight trac-wiki %}
~~~
VM: {
personal: {
allow_fullscreen = true;
};
};
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
global: {
# default values
allow_fullscreen = true;
@ -51,6 +53,6 @@ global: {
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
};
{% endhighlight %}
~~~
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.

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

@ -1,8 +1,10 @@
---
layout: doc
title: ManagingAppVmShortcuts
permalink: /doc/ManagingAppVmShortcuts/
redirect_from: /wiki/ManagingAppVmShortcuts/
title: Managing AppVm Shortcuts
permalink: /en/doc/managing-appvm-shortcuts/
redirect_from:
- /doc/ManagingAppVmShortcuts/
- /wiki/ManagingAppVmShortcuts/
---
Managing shortcuts to applications in AppVMs
@ -29,6 +31,6 @@ List of installed applications for each AppVM is stored in its template's `/var/
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](/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.
`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.

38
SoftwareUpdateDom0.md → en/common-tasks/software-update-dom0.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: SoftwareUpdateDom0
permalink: /doc/SoftwareUpdateDom0/
redirect_from: /wiki/SoftwareUpdateDom0/
title: Updating software in dom0
permalink: /en/doc/software-update-dom0/
redirect_from:
- /doc/SoftwareUpdateDom0/
- /wiki/SoftwareUpdateDom0/
---
Updating software in dom0
@ -35,15 +37,15 @@ Of course, command line tools are still available for accomplishing various upda
1. To check and install updates for dom0 software:
{% highlight trac-wiki %}
~~~
$ sudo qubes-dom0-update
{% endhighlight %}
~~~
1. To install additional packages in dom0 (usually not recommended):
{% highlight trac-wiki %}
~~~
$ sudo qubes-dom0-update anti-evil-maid
{% endhighlight %}
~~~
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.
@ -51,16 +53,30 @@ Of course, command line tools are still available for accomplishing various upda
1. Download an older version of the package:
{% highlight trac-wiki %}
~~~
sudo qubes-dom0-update package-version
{% endhighlight %}
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
1. Downgrade the packge:
{% highlight trac-wiki %}
~~~
sudo yum downgrade package-version
{% endhighlight %}
~~~
### 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.

39
SoftwareUpdateVM.md → en/common-tasks/software-update-vm.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: SoftwareUpdateVM
permalink: /doc/SoftwareUpdateVM/
redirect_from: /wiki/SoftwareUpdateVM/
title: Installing and updating software in VMs
permalink: /en/doc/software-update-vm/
redirect_from:
- /doc/SoftwareUpdateVM/
- /wiki/SoftwareUpdateVM/
---
Installing and updating software in VMs
@ -39,7 +41,7 @@ As the template VM is used for creating filesystems for other AppVMs, where you
There are several ways to deal with this problem:
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/QubesFirewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/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.
@ -49,7 +51,7 @@ Some popular questions:
- So, why should we actually trust Fedora repos -- it also contains large amount of 3rd party software that might buggy, right?
As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/QubesFirewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/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?
@ -72,9 +74,9 @@ Sometime it might be convenient to have a VM that has its own filesystem, where
In order to create a standalone VM you can use a command line like this (from console in Dom0):
{% highlight trac-wiki %}
~~~
qvm-create <vmname> --standalone --label <label>
{% endhighlight %}
~~~
... or click appropriate options in the Qubes Manager's Create VM window.
@ -85,9 +87,9 @@ It's also possible to have more than one template VM in the system. E.g. one cou
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:
{% highlight trac-wiki %}
~~~
qvm-create <vmname> --template <templatename> --label <label>
{% endhighlight %}
~~~
Temporarily allowing networking for software installation
---------------------------------------------------------
@ -97,7 +99,7 @@ Some 3rd party applications cannot be installed using the standard yum repositor
Updates proxy
-------------
Updates proxy is a service which filter http access to allow access to only something that looks like yum repository (or apt repository in the future - \#887). 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.
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).
@ -111,15 +113,15 @@ The proxy is running in selected VMs (by default all the NetVMs (1)) and interce
1. Updates proxy: It is running as "qubes-yum-proxy" service. Startup script of this service setup firewall rule to intercept proxy traffic:
{% highlight trac-wiki %}
~~~
iptables -t nat -A PR-QBS-SERVICES -d 10.137.255.254/32 -i vif+ -p tcp -m tcp --dport 8082 -j REDIRECT
{% endhighlight %}
~~~
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
{% highlight trac-wiki %}
~~~
proxy=http://10.137.255.254:8082/
{% endhighlight %}
~~~
line, or be empty. Note that this file is specifically included from main yum.conf, yum does not support real conf.d configuration style...
@ -133,3 +135,12 @@ However, one should be careful with treating this property as a reliable way to
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/stick-mounting.md Normal file
View File

@ -0,0 +1,99 @@
---
layout: doc
title: Mounting USB Sticks
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.

52
AssigningDevices.md → en/configuration/assigning-devices.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: AssigningDevices
permalink: /doc/AssigningDevices/
redirect_from: /wiki/AssigningDevices/
title: Assigning Devices
permalink: /en/doc/assigning-devices/
redirect_from:
- /doc/AssigningDevices/
- /wiki/AssigningDevices/
---
Assigning Devices to VMs
@ -10,21 +12,21 @@ Assigning Devices to VMs
In order to assign a whole PCI(e) device to a VM, one should use `qvm-pci` tool. E.g.
{% highlight trac-wiki %}
~~~
lspci
{% endhighlight %}
~~~
Find the BDF address of the device you want to assign, and then:
{% highlight trac-wiki %}
~~~
qvm-pci -a <vmname> <bdf>
{% endhighlight %}
~~~
E.g. assuming 00:1a.0 is a BDF of the device I want to assign to the "personal" domain:
{% highlight trac-wiki %}
~~~
qvm-pci -a personal 00:1a.0
{% endhighlight %}
~~~
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.
@ -40,33 +42,33 @@ 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:
{% highlight trac-wiki %}
~~~
lsusb
{% endhighlight %}
~~~
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):
{% highlight trac-wiki %}
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
readlink /sys/bus/usb/devices/usb3
{% endhighlight %}
~~~
This should output something like:
{% highlight trac-wiki %}
~~~
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
{% endhighlight %}
~~~
Now you see BDF address in the path (right before final usb3). Strip leading "0000:" and pass the rest to qvm-pci tool:
{% highlight trac-wiki %}
~~~
qvm-pci -a netvm 00:1a.0
{% endhighlight %}
~~~
Possible issues
---------------
@ -75,11 +77,11 @@ Possible issues
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):
{% highlight trac-wiki %}
~~~
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
{% endhighlight %}
~~~
This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3) for Realtek RTL8111DL Gigabit Ethernet Controller.
@ -87,7 +89,7 @@ This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
{% highlight trac-wiki %}
~~~
[Unit]
Description=Netvm fixup
Before=qubes-netvm.service
@ -99,7 +101,7 @@ RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
{% endhighlight %}
~~~
Then enable it with `systemctl enable qubes-pre-netvm.service`
@ -118,11 +120,11 @@ 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`:
{% highlight trac-wiki %}
~~~
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
{% endhighlight %}
~~~

17
UserDoc/ConfigFiles.md → en/configuration/config-files.md
View File

@ -1,8 +1,11 @@
---
layout: doc
title: ConfigFiles
permalink: /doc/UserDoc/ConfigFiles/
redirect_from: /wiki/UserDoc/ConfigFiles/
title: Config Files
permalink: /en/doc/config-files/
redirect_from:
- /doc/ConfigFiles/
- "/doc/UserDoc/ConfigFiles/"
- "/wiki/UserDoc/ConfigFiles/"
---
Qubes specific VM config files
@ -12,11 +15,11 @@ Those files are placed in /rw, which survives VM restart, so can be used to cust
- `/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:
{% highlight trac-wiki %}
~~~
# 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
{% endhighlight %}
~~~
- `/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
@ -29,7 +32,7 @@ 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):
{% highlight trac-wiki %}
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
@ -53,7 +56,7 @@ VM: {
#allow_fullscreen = true;
};
};
{% endhighlight %}
~~~
Currently supported settings:

20
DiskTRIM.md → en/configuration/disk-trim.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: DiskTRIM
permalink: /doc/DiskTRIM/
redirect_from: /wiki/DiskTRIM/
title: Disk TRIM
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.
@ -11,23 +13,23 @@ To enable TRIM in dom0 you need:
1. Get your LUKS device UUID:
{% highlight trac-wiki %}
~~~
ls /dev/mapper/luks-*
{% endhighlight %}
~~~
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
{% highlight trac-wiki %}
~~~
luks-<UUID> UUID=<UUID> none allow-discards
{% endhighlight %}
~~~
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**:
{% highlight trac-wiki %}
~~~
dracut -H -f
{% endhighlight %}
~~~
6. Add "discard" option to `/etc/fstab` for root device
7. Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)

20
ExternalAudio.md → en/configuration/external-audio.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: ExternalAudio
permalink: /doc/ExternalAudio/
redirect_from: /wiki/ExternalAudio/
title: External Audio
permalink: /en/doc/external-audio/
redirect_from:
- /doc/ExternalAudio/
- /wiki/ExternalAudio/
---
Using External Audio Devices
@ -22,16 +24,16 @@ First you need to identify an user VM dedicated to audio and [assign a device](/
In a terminal of the template from which you user VM depends, install pavucontrol with:
{% highlight trac-wiki %}
~~~
sudo yum install pavucontrol
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
{% endhighlight %}
~~~
Start the audio application that is going to use the external audio device.
@ -39,8 +41,8 @@ Launch pavucontrol, for example using "run command in VM" of Qubes Manager and s
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:
{% highlight trac-wiki %}
~~~
pactl unload-module module-udev-detect
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
{% endhighlight %}
~~~

16
en/configuration/external-device-mount-point.md Normal file
View File

@ -0,0 +1,16 @@
---
layout: doc
title: External Device Mount Point
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.

22
Fetchmail.md → en/configuration/fetchmail.md
View File

@ -1,14 +1,16 @@
---
layout: doc
title: Fetchmail
permalink: /doc/Fetchmail/
redirect_from: /wiki/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 MUA like Thunderbird or [Mutt](/doc/Mutt/).
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
------------
@ -20,11 +22,11 @@ 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](/doc/Postfix/) as your local MTA.
**NOTE:** this assumes you use [Postfix](/en/doc/postfix/) as your local MTA.
In TemplateVM create `/etc/systemd/system/fetchmail@.service`:
{% highlight trac-wiki %}
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
@ -34,11 +36,11 @@ Requires=postfix.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
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
set syslog
set no bouncemail
#set daemon 600
@ -57,13 +59,13 @@ user woju pass supersecret
idle
# vim: ft=fetchmail
{% endhighlight %}
~~~
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`:
{% highlight trac-wiki %}
~~~
#!/bin/sh
for rc in /usr/local/etc/fetchmail/*.rc; do
@ -71,6 +73,6 @@ for rc in /usr/local/etc/fetchmail/*.rc; do
instance=${instance##*/}
echo systemctl --no-block start fetchmail@${instance}
done
{% endhighlight %}
~~~
Now reboot your AppVM and you are done.

27
Mutt.md → en/configuration/mutt.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: Mutt
permalink: /doc/Mutt/
redirect_from: /wiki/Mutt/
permalink: /en/doc/mutt/
redirect_from:
- /doc/Mutt/
- /wiki/Mutt/
---
Mutt
@ -13,10 +15,10 @@ Mutt is a fast, standards-compliant, efficient MUA (Mail User Agent). In some ar
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](/doc/Postfix/) or Exim and MRA such as
[Fetchmail](/doc/Fetchmail/). Alternativelly you can synchronize your mailbox
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 itegrated IMAP client, but it is
to integrated SMTP support. You can even use integrated IMAP client, but it is
not very convenient.
Installation
@ -27,13 +29,13 @@ Installation
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](/doc/UserDoc/SplitGpg/), which is assumed to be already working.
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:
{% highlight trac-wiki %}
~~~
# specify your key or override in ~/.mutt/muttrc in AppVM
set pgp_sign_as="0xDEADBEEF"
@ -105,11 +107,11 @@ send-hook "~A" set pgp_autoinline=no crypt_autoencrypt=no
send-hook "~t @invisiblethingslab\.com" set crypt_autoencrypt=yes
# vim:ft=muttrc
{% endhighlight %}
~~~
Then shutdown your TemplateVM. Next open your AppVM, create file `/home/user/.mutt/muttrc` and adjust for your needs:
{% highlight trac-wiki %}
~~~
#
# accounts
#
@ -134,14 +136,14 @@ 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/
{% endhighlight %}
~~~
You may also create `/home/user/.signature`:
{% highlight trac-wiki %}
~~~
regards,
Wojciech Porczyk
{% endhighlight %}
~~~
Some additional useful settings
-------------------------------
@ -188,6 +190,7 @@ In `.urlview`:
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

40
NetworkBridgeSupport.md → en/configuration/network-bridge-support.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: NetworkBridgeSupport
permalink: /doc/NetworkBridgeSupport/
redirect_from: /wiki/NetworkBridgeSupport/
title: Network Bridge Support
permalink: /en/doc/network-bridge-support/
redirect_from:
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
---
Network Bridge Support (EXPERIMENTAL and UNSUPPORTED)
@ -22,20 +24,20 @@ 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:
{% highlight trac-wiki %}
~~~
# qubes-dom-update qubes-core-dom0 qubes-manager
# yum reinstall qubes-core-dom0
# yum reinstall qubes-manager
{% endhighlight %}
~~~
First, retrieve the attachment of this Wifi article in dom0. Then apply the three patches the following way after installing the patch tool :
{% highlight trac-wiki %}
~~~
# 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
{% endhighlight %}
~~~
Finally restart the qubes manager GUI.
@ -50,7 +52,7 @@ Modify manually the Template you use for your NetVM (not the NetVM itself). This
- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment :
{% highlight trac-wiki %}
~~~
# Bridge support
# Comment the following line
#-A POSTROUTING -j MASQUERADE
@ -59,26 +61,26 @@ Modify manually the Template you use for your NetVM (not the NetVM itself). This
# Allow redirection of bridge packets (optional as POSTROUTING default is ACCEPT)
#-A POSTROUTING -o bridge+ -j ACCEPT
# End Bridge support
{% endhighlight %}
~~~
- Starting from the line -A FORWARD -i vif+ -j ACCEPT:
{% highlight trac-wiki %}
~~~
-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
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
# systemctl restart iptables
{% endhighlight %}
~~~
Create a Bridge inside the NetVM
--------------------------------
@ -96,7 +98,7 @@ The bridge edition GUI is somehow buggy as it does not remember all the paramete
- Bridge-DHCP
{% highlight trac-wiki %}
~~~
[connection]
id=Bridge-DHCP
uuid=fd68198b-313a-47cb-9155-52e95cdc67f3
@ -113,13 +115,13 @@ The bridge edition GUI is somehow buggy as it does not remember all the paramete
[bridge]
interface-name=bridge0
stp=false
{% endhighlight %}
~~~
Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :)
- bridge0-eth0
{% highlight trac-wiki %}
~~~
[802-3-ethernet]
duplex=full
mac-address=88:AE:1D:AE:30:31
@ -132,12 +134,12 @@ Note: Do not forget to put stp=false if you bridge only eth0 because sending BPD
timestamp=1363601650
master=fd68198b-313a-47cb-9155-52e95cdc67f3
slave-type=bridge
{% endhighlight %}
~~~
If you do not manager to start your bridge, you can start it manually from a NetVM terminal:
{% highlight trac-wiki %}
~~~
$ nmcli con up id bridge0-eth0
{% endhighlight %}
~~~
Now that the bridge is ready, the bridged AppVM can be started...

20
NetworkPrinter.md → en/configuration/network-printer.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: NetworkPrinter
permalink: /doc/NetworkPrinter/
redirect_from: /wiki/NetworkPrinter/
title: Network Printer
permalink: /en/doc/network-printer/
redirect_from:
- /doc/NetworkPrinter/
- /wiki/NetworkPrinter/
---
Configuring a network printer for Qubes AppVMs
@ -13,25 +15,25 @@ 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 for this particular VM.
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](/doc/DisposableVms/), 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).
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 lock network, or who is controlling the (normally untrusted) Qubes NetVM, will likely 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.
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 default template
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 special Qubes proxy for updates installation. One can use Qubes Manager to modify firewall rules for particular VMs.
3. Test the printer by printing a test page. If it works, shut down the template VM.
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.

44
Postfix.md → en/configuration/postfix.md
View File

@ -1,14 +1,16 @@
---
layout: doc
title: Postfix
permalink: /doc/Postfix/
redirect_from: /wiki/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](/doc/Mutt/)+Postfix+[Fetchmail](/doc/Fetchmail/) stack.
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
------------
@ -22,9 +24,9 @@ Configuration
In TemplateVM open `/etc/aliases` and add line:
{% highlight trac-wiki %}
~~~
root: user
{% endhighlight %}
~~~
and run `newaliases`.
@ -36,7 +38,7 @@ Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix`
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`:
{% highlight trac-wiki %}
~~~
all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf))
newaliases
clean:
@ -45,13 +47,13 @@ clean:
%.db: %
/usr/sbin/postmap hash:$<
{% endhighlight %}
~~~
### Postfix main configuration
`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it):
{% highlight trac-wiki %}
~~~
mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain
mynetworks_style = host
@ -84,36 +86,36 @@ sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
alias_maps = hash:/etc/aliases
{% endhighlight %}
~~~
### Lookup tables
`/usr/local/etc/postfix/generic` (put there your primary address):
{% highlight trac-wiki %}
~~~
@localhost your.mail@example.com
{% endhighlight %}
~~~
`/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.
{% highlight trac-wiki %}
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
{% endhighlight %}
~~~
`/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 `@`.
{% highlight trac-wiki %}
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
[smtp.mail.com]:smtp your.other@mail.com:supers3cret
{% endhighlight %}
~~~
`/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`.
{% highlight trac-wiki %}
~~~
spamdomain1.com DISCARD
spamdomain2.com DISCARD
{% endhighlight %}
~~~
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`).
@ -121,7 +123,7 @@ Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four above
Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`:
{% highlight trac-wiki %}
~~~
MAILDIR = "${HOME}/.maildir"
ORGMAIL = "${MAILDIR}/"
DEFAULT = "${MAILDIR}/"
@ -133,18 +135,18 @@ list/qubes-users/
:0
* ^List-Id:.*qubes-devel\.googlegroups\.com
list/qubes-devel/
{% endhighlight %}
~~~
Run
---
Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them):
{% highlight trac-wiki %}
~~~
#!/bin/sh
mount --bind /usr/local/etc/postfix /etc/postfix
systemctl --no-block start postfix
{% endhighlight %}
~~~
Reboot your AppVM and you are done.

42
ResizeDiskImage.md → en/configuration/resize-disk-image.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: ResizeDiskImage
permalink: /doc/ResizeDiskImage/
redirect_from: /wiki/ResizeDiskImage/
title: Resize Disk Image
permalink: /en/doc/resize-disk-image/
redirect_from:
- /doc/ResizeDiskImage/
- /wiki/ResizeDiskImage/
---
Resizing Disk Image
@ -15,19 +17,19 @@ There are several disk images which can be easily extended.
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](/doc/Dom0Tools/QvmGrowPrivate/) can be used:
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:
{% highlight trac-wiki %}
~~~
qvm-grow-private <vm-name> <size>
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
sudo resize2fs /dev/xvdb
{% endhighlight %}
~~~
### Shrinking private disk image (Linux VM)
@ -40,14 +42,14 @@ The basic idea is to:
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:
{% highlight trac-wiki %}
~~~
qvm-prefs -s <vm-name> kernelopts rd.break
qvm-start --no-guid <vm-name>
{% endhighlight %}
~~~
And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
{% highlight trac-wiki %}
~~~
sudo xl console <vm-name>
# you should get dracut emergency shell here
mount --bind /dev /sysroot/dev
@ -59,19 +61,19 @@ umount /proc
exit
umount /sysroot/dev
poweroff
{% endhighlight %}
~~~
Now you can resize the image:
{% highlight trac-wiki %}
~~~
truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
{% endhighlight %}
~~~
**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:
{% highlight trac-wiki %}
~~~
qvm-prefs -s <vm-name> kernelopts default
{% endhighlight %}
~~~
Done.
@ -97,12 +99,12 @@ First, stop/shutdown the HVM.
Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
{% highlight trac-wiki %}
~~~
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)
{% endhighlight %}
~~~
The partition table and file-system must be adjusted after this change:
@ -117,9 +119,9 @@ No reboot required.
#### FreeBSD
{% highlight trac-wiki %}
~~~
gpart recover ada0
sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
{% endhighlight %}
~~~

34
en/configuration/resize-root-disk-image.md Normal file
View File

@ -0,0 +1,34 @@
---
layout: doc
title: Resize Root Disk Image
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

14
Rxvt.md → en/configuration/rxvt.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: Rxvt
permalink: /doc/Rxvt/
redirect_from: /wiki/Rxvt/
permalink: /en/doc/rxvt/
redirect_from:
- /doc/Rxvt/
- /wiki/Rxvt/
---
Rxvt
@ -20,7 +22,7 @@ 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.
{% highlight trac-wiki %}
~~~
! CGA colour palette
!*color0: #000000
@ -123,15 +125,15 @@ URxvt.insecure: False
! some termcap-aware software sometimes throw '$TERM too long'
!URxvt.termName: rxvt-256color
{% endhighlight %}
~~~
Then create script to automatically merge those to xrdb. File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
{% highlight trac-wiki %}
~~~
#!/bin/sh
[ -r /etc/X11/Xresources.urxvt ] && xrdb -merge /etc/X11/Xresources.urxvt
{% endhighlight %}
~~~
Shortcuts
---------

8
SecondaryStorage.md → en/configuration/secondary-storage.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: SecondaryStorage
permalink: /doc/SecondaryStorage/
redirect_from: /wiki/SecondaryStorage/
title: Secondary Storage
permalink: /en/doc/secondary-storage/
redirect_from:
- /doc/SecondaryStorage/
- /wiki/SecondaryStorage/
---
Storing AppVMs on Secondary Drives

43
UserDoc/TorVM.md → en/configuration/torvm.md
View File

@ -1,8 +1,11 @@
---
layout: doc
title: TorVM
permalink: /doc/UserDoc/TorVM/
redirect_from: /wiki/UserDoc/TorVM/
permalink: /en/doc/torvm/
redirect_from:
- /doc/TorVM/
- "/doc/UserDoc/TorVM/"
- "/wiki/UserDoc/TorVM/"
---
Known issues:
@ -28,6 +31,8 @@ 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
@ -48,7 +53,7 @@ Installation
0. *(Optional)* If you want to use a separate vm template for your TorVM
qvm-clone fedora-20-x64 fedora-20-x64-net
qvm-clone fedora-21 fedora-21-tor
1. In dom0, create a proxy vm and disable unnecessary services and enable qubes-tor
@ -59,9 +64,9 @@ Installation
qvm-service torvm -e qubes-tor
# if you created a new template in the previous step
qvm-prefs torvm -s template fedora-20-x64-net
qvm-prefs torvm -s template fedora-21-tor
2. From your template vm, install the torproject Fedora repo
2. From your TemplateVM, install the torproject Fedora repo
sudo yum install qubes-tor-repo
@ -69,21 +74,18 @@ Installation
sudo yum install qubes-tor
5. Configure an AppVM to use TorVM as its netvm (example a vm named anon-web)
5. Configure an AppVM to use TorVM as its NetVM (for example a vm named anon-web)
qvm-prefs -s anon-web netvm torvm
... repeat for other appvms ...
qvm-prefs -s anon-web sys-net torvm
... repeat for any other AppVMs you want torified...
6. Shutdown templateVM.
7. Set prefs of torvm to use your default netvm or firewallvm as its NetVM
8. Start the TorVM and any AppVM you have configured
9. Execute in TorVM (will be not necessary in R2 Beta3):
6. Shutdown the TemplateVM.
7. Set the prefs of your TorVM to use the default sys-net or sys-firewall as its NetVM
sudo mkdir /rw/usrlocal/etc/qubes-tor
sudo touch /rw/usrlocal/etc/qubes-tor/torrc
sudo service qubes-tor restart
qvm-prefs -s torvm netvm sys-net
10. From the AppVM, verify torified connectivity
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
@ -103,6 +105,11 @@ Installation
[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
=====
@ -258,14 +265,14 @@ 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://sourceforge.net/p/whonix/wiki/Security/)
* [Patrick Schleizer](mailto:adrelanos@riseup.net) for his work on [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]: http://wiki.qubes-os.org/trac/wiki/QubesNet
[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

22
VPN.md → en/configuration/vpn.md
View File

@ -1,27 +1,29 @@
---
layout: doc
title: VPN
permalink: /doc/VPN/
redirect_from: /wiki/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 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 choose the right VM for the VPN client:
The Qubes specific part is to choose the right VM for the VPN client:
### NetVM
The simplest case if you 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:
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 wich is directly connected to the outside world
- All your AppVMs wich are connected to the NetVM will be connected to the VPN (by default)
- 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.
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
@ -29,10 +31,10 @@ While the Network Manager is not started here (for a good reason) You can config
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 will gives you the ability to:
Using a ProxyVM to set up a VPN client gives you the ability to:
- Separate your VPN credentials from Your AppVM data.
- You can easily control which of your AppVMs are connected to your VPN by simply set it as a NetVM of the desired AppVM.
- 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:**

62
ZFS.md → en/configuration/zfs.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: ZFS
permalink: /doc/ZFS/
redirect_from: /wiki/ZFS/
permalink: /en/doc/zfs/
redirect_from:
- /doc/ZFS/
- /wiki/ZFS/
---
ZFS in Qubes
@ -20,14 +22,14 @@ Install DKMS style packages for Fedora <sup>(defunct\\ in\\ 0.6.2\\ due\\ to\\ s
Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html):
{% highlight trac-wiki %}
~~~
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
{% endhighlight %}
~~~
Install DKMS style packages from git-repository
-----------------------------------------------
@ -38,57 +40,57 @@ Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.
Checkout repositories for SPL and ZFS:
{% highlight trac-wiki %}
~~~
mkdir ~/repositories && cd ~/repositories
git clone https://github.com/zfsonlinux/spl.git
git clone https://github.com/zfsonlinux/zfs.git
{% endhighlight %}
~~~
Revert changes in SPL repository due to this bug: [https://github.com/zfsonlinux/spl/issues/284](https://github.com/zfsonlinux/spl/issues/284)
{% highlight trac-wiki %}
~~~
cd ~/repositories/spl
git config --global user.email "user@example.com"
git config --global user.name "user"
git revert e3c4d44886a8564e84aa697477b0e37211d634cd
{% endhighlight %}
~~~
### Installation steps in Dom0
Copy repositories over to Dom0:
{% highlight trac-wiki %}
~~~
mkdir ~/repositories
qvm-run --pass-io disp1 'tar -cf - -C ~/repositories/ {spl,zfs}' | tar -xpf - -C ~/repositories/
{% endhighlight %}
~~~
Installing build requirements for SPL and ZFS DKMS modules:
{% highlight trac-wiki %}
~~~
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
{% endhighlight %}
~~~
Configure and build SPL DKMS packages:
{% highlight trac-wiki %}
~~~
cd ~/repositories/spl
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
{% endhighlight %}
~~~
Configure and build ZFS DKMS packages:
{% highlight trac-wiki %}
~~~
cd ~/repositories/zfs
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
{% endhighlight %}
~~~
Install SPL and ZFS packages (i.e. version 0.6.2):
{% highlight trac-wiki %}
~~~
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 \
@ -96,7 +98,7 @@ sudo yum localinstall \
~/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
{% endhighlight %}
~~~
Configure ZFS
=============
@ -106,13 +108,13 @@ Automatically load modules
/etc/sysconfig/modules/zfs.modules
{% highlight trac-wiki %}
~~~
#!/bin/sh
for module in spl zfs; do
modprobe ${module} >/dev/null 2>&1
done
{% endhighlight %}
~~~
Make this file executable.
@ -123,9 +125,9 @@ Tame the memory-eating dragon (i.e. 512 Mb zfs\_arc\_max):
/etc/modprobe.d/zfs.conf
{% highlight trac-wiki %}
~~~
options zfs zfs_arc_max=536870912
{% endhighlight %}
~~~
Setup a zpool with ZFS datasets
-------------------------------
@ -138,7 +140,7 @@ Beware: VMs on a ZFS dataset aren't working, if your ZFS installation deserts yo
So keep netvm, firewallvm and your templates on your root file-system (preferably on a SSD).
{% highlight trac-wiki %}
~~~
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
@ -146,7 +148,7 @@ 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
{% endhighlight %}
~~~
Have fun with zpool and zfs.
@ -161,28 +163,28 @@ You're depending on an huge amount of code for this file system, keep this in mi
Encrypt underlying devices
--------------------------
{% highlight trac-wiki %}
~~~
dom0# cryptsetup -c aes-xts-plain64 luksFormat <device1>
dom0# cryptsetup luksOpen <device1> <cryptname1>
{% endhighlight %}
~~~
With the use of cryptsetup a keyfile can be specified to decrypt devices.
{% highlight trac-wiki %}
~~~
dom0# head -c 256 /dev/random > /root/keyfile1
dom0# chmod 0400 /root/keyfile1
dom0# cryptsetup luksAddKey <device1> /root/keyfile1
{% endhighlight %}
~~~
Decrypt devices on boot
-----------------------
Add your devices to /etc/crypttab.
{% highlight trac-wiki %}
~~~
<cryptname1> <device1> <keyfile1>
<cryptname2> <device2> none
{% endhighlight %}
~~~
Specifying a keyfile is especially useful, if ZFS should be ready during boot.

60
en/customization/dispvm-customization.md Normal file
View File

@ -0,0 +1,60 @@
---
layout: doc
title: DispVM Customization
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.

273
en/customization/fedora-minimal-template-customization.md Normal file
View File

@ -0,0 +1,273 @@
---
layout: doc
title: Fedora Minimal Template Customization
permalink: /en/doc/fedora-minimal-template-customization/
---
FEDORA Packages Recommendations
======================
(starting from a minimal template)
Template installation
------------------------------
> [dom0]#qubes-dom0-update qubes-template-fedora-21-minimal
*Note*: the template may not start in qubes R3 when using kernel 3.19 (unstable). In this case, switch the AppVM or TemplateVM to the kernel 3.18.
*Note*: If you have doubts about a set of tool or package you want to install, start installing and testing it in an AppVM. You can then reproduce it later in your TemplateVM if you are satisfied. That the (QubesOS?) template philosophy.
Standard tools installation
================
Administration (documented)
---------------------------------------------
sudo pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat usbutils
*Notes*: nmap can be used to discover a network (nmap -sP [network]), especially if you are inside a Microsoft network, because your AppVM will be protected/NATted behind Qubes firewall (microsoft / home network are heavily using autodiscovery technologies which require to beint in the same local network (no firewall/no NAT), eg: your printer.
Some recommendation here: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to allow temporarily the Qubes Firewall if you are inside a TemplateVM.
Administration (undocumented)
-------------------------------------------------
openssh keepassx openssl gnome-keyring man
Dependency note: keepassx rely on qt which takes ~30MB
Network VM (documented)
----------------------------------------
NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 tar tinyproxy
Network VM (undocumented)
--------------------------------------------
which dconf dconf-editor
*Notes*: which is required for autostart scripts
*Notes*: dconf is required to remember the VM settings that are changed (the gsetting backend will be in memory only if gconf is not installed).
Network VM (manual operations - documented)
------------------------------------------------------------------------
Search for a wireless firmware matching your wireless card (to be launched in network VM)
> lspci; yum search firmware
ProxyVM/NetworkVM for 3G Modems
=====================
ModemManager NetworkManager-wwan usb_modeswitch modem-manager-gui
Dependency note: modem-manager-gui rely on webkit-gtk and is optional (NetworkManager can handle the modem alone)
Source: [3GMODEM]
ProxyVM for VPNs
==========
Search for a VPN package for your particular vpn solution
> yum search NetworkManager [openconnect|openswat|...]
OR
For manual handling of VPN (and because NetworkManager is not available in proxyVMs, check the Qubes-users mail threads on google group
(cprise started a good one on openvpn: [OPENVPNSETUP] "[qubes-users] OpenVPN Setup, Revisited Again!")
Printer Setup
========
system-config-printer system-config-printer-applet cups
Dependency Note: depends on python3 + python3 additionnal libraries which takes more than 40 M once installed.
Dependency Note: cups depends on ghostscript and require installing additionnal printing fonts (not documented here), so it can takes several dozen of MB
Manual operations
---------------------------
- Don't forget to restart your TemplateVM or only the cups service when you installed cups (systemctl start cups)
- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to allow temporarily the Qubes Firewall if you are inside a TemplateVM.
- Once you identifed your printer, run system-config-printer GUI to install your printer
- You man need to cancel the operation to install more adapted printer drivers (eg: if the driver cannot be found automatically). Use yum search printername to find potential drivers (eg yum search photosmart)
GUI recommendations
=============
Lightweight packages recommendations
---------------------------------------------------------------
lxterminal dejavu-sans-mono-fonts dejavu-sans-fonts gnome-settings-daemon
*Note*: You need to install sans-mono fonts for the terminal or it will be unreadable (overlapping characters....), while the sans fonts are just to get nicer GUI menus.
*Scite* is a nice notepad that can also highlight scripts with very light dependencies
scite
*Meld* allow comparing two text files/ two configuration files easily.
meld
*Thunar* is a light file manager usually used by xfce
thunar thunar-volman ntfs-3g
Dependency Note: xfce4 dependencies (but still quite light ~1.4M downloads)
GUI themes
-----------------
Managing GUI theme / appearance is often complex because when you do not want to depends on a specific desktop system.
For this reason, we need to customize themes for each GUI framework that our application depends on.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), QT.
The apparance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
### Packages
Choose theme packages for each framework. I recommend the following documentation [THEMEPACKAGES]
clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme
You can search for other themes using yum search theme gtk
You can check your currently installed theme packages (to eventually remove them) using rpm -qa | grep theme
### Tweaking theme and appearance
First you can get an insight of installed Gtk theme and see how it will appears using lxappearance.
I recommend not applying settings using lxappearance (do not click on apply) because it will create multiple configuration files.
To remove these files, follow cleanup notes.
#### Cleanup notes
~~~
rm ~/.gtkrc-2.0
rm ~/.icons/default/index.theme
rm ~/.config/gtk-3.0/settings.ini
rm ~/.config/Trolltech.conf
~~~
Cleaning the whole dconf settings is also possible by removing the following file. Please note that it will remove all preferences set for gnome application (not only the themes)
~~~
rm ~/.config/dconf/user
~~~
*Note*: lxappearance only have effect on gtk3 theme so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
However, it is very lightweight and can be used to identify the name and look of themes you are interested in.
Once you have the name, you can apply it using gsetting command line or gconf-editor.
*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool have a lot
of gnome dependencies (~150MB of dependencies). Eventually install it and uninstall it as soon as you changed your theme.
#### Testing notes
The following programs can be used to see if theme has been correctly applied:
* GTK2 program: scite, thunderbird, firefox
* GTK3 program: lxterminal
* QT program: keepassx
*Note*: testing in a TemplateVM will not work as expected because gnome-settings-daemon is not started in TemplateVM.
so test your themes in an AppVM and then update the TemplateVM accordingly.
### Forcing theme change for all AppVM depending on a TemplateVM
This can be done for gtk themes by creating dconf global settings. I recommend reading these articles:
[DCONF1]
[DCONF2]
#### Creating global file
* Setup global config file:
> mkdir /etc/dconf/db/qubes.d
Edit/Create the following file: /etc/dconf/db/qubes.d/10-global-theme-settings:
~~~
[org/gnome/desktop/interface]
cursor-theme="Adwaita"
gtk-theme="Clearlooks-Phenix"
icon-theme="Adwaita"
font-name="Cantarell 11"
monospace-font-name="Monospace 11"
~~~
* Generate global config database
> dconf update
* Configure default user profile
Edit/Create the following file: /etc/dconf/profile/user:
~~~
user-db:user
system-db:qubes
~~~
#### Locking configuration
It should be noted that the user dconf settings stored in ~/.config/dconf/user always takes precedence over the global dconf settings.
User dconf settings can be browsed using dconf-editor GUI.
If you want to force specific settings to be applied for all user (so in our case for all AppVMs depending on the template), you need to create locks:
> mkdir /etc/dconf/db/qubes.d/locks
Edit/Create the following file: /etc/dconf/db/qubes.d/locks/theme.lock:
~~~
/org/gnome/desktop/interface/gtk-theme
~~~
Finally, regenerate the dconf database
> dconf update
### Uniform look for QT & GTK
Getting an uniform look for QT & GTK is not acheaved yet. A good source is on the following link [UNIFORMTHEME]
Two case:
1. You installed packages of the theme you selected both for Qt, GTK2 and GTK3.
(eg: Adwaita which is the default theme. I did not found another cross framework theme on fedora default packages).
2. You want to use the GTK theme you selected for Qt but there is no qt package.
In this case QGtkStyle will take precedence and convert the style automaticall.
You can verify if it is enabled by searching for "style=GTK+" in /etc/xdg/Trolltech.conf.
If style is changed to another name, it will be used instead of your GTK theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global QT theme.
[3GMODEM]: https://www.codeenigma.com/community/blog/installing-3g-usb-modems-linux
[OPENVPNSETUP]: https://groups.google.com/forum/#!searchin/qubes-users/openvpn$20setup/qubes-users/UbY4-apKScE/lhB_ouTnAwAJ
[THEMEPACKAGES]: https://groups.google.com/forum/#!search/appvm$20theme/qubes-users/RyVeDiEZ6D0/YR4ITjgdYX0J
[DCONF1]: http://www.mattfischer.com/blog/?p=431
[DCONF2]: https://wiki.gnome.org/Projects/dconf/SystemAdministrators
[UNIFORMTHEME]: https://wiki.archlinux.org/index.php/Uniform_look_for_Qt_and_GTK_applications

8
LanguageLocalization.md → en/customization/language-localization.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: LanguageLocalization
permalink: /doc/LanguageLocalization/
redirect_from: /wiki/LanguageLocalization/
title: Language Localization
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)

166
en/customization/windows-template-customization.md Normal file
View File

@ -0,0 +1,166 @@
---
layout: doc
title: Windows Template Customization
permalink: /en/doc/windows-template-customization/
---
Disable/Uninstall unecessary features/services
=============================
Windows features
----------------------------
Uninstall windows features from Control Panel > Turn windows features On/Off.
Generally, it will be required to reboot after features desinstallation.
If you do not manage to uninstall some features, it is sometimes necessarry to uninstall them one by one or two by two.
Only keep:
* Print and Document Service => Internet Printing Client
* Print and Document Service => Windows Fax and Scan (apparently it cannot be uninstalled)
* Windows search
*Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel).
*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. on a new install it is generally old versions anyway and it will be quicker to install directly the new versions later.
Services
Windows services
---------------------------
Disable the following services that are not required or have no sense in a VM context:
* Base Filtering Engine (only required if your want to use Microsoft IPSEC)
* DHCP Client
* Function Discovery Provider Host
this will not work anyway because SSDP discovery uses multicast - need to be on the same network which is not the case because of qubes firewall
* Peer Name Resolution Protocol
* Peer Netwoking Grouping
* Peer Networking Identity Manager
* SSDP Discovery
* Security Center (is it only notifications ?)
* TCP/IP Netbios Help (is Netbios still really used by Windows ? Maybe for discovery only ?)
* Themes (if you don't care about theme)
* Volume Shadow Copy (see next note in the performance section)
* Windows defender
* Windows Firewall
* Power
*Notes*: IP Helper is required as it is used by Qubes Agent to configure the IP address.
Windows update
--------------------------
I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you don't started your template after some days.
Running windows update is also apparently IO hungry.
Of course I recommend starting the template regularly and checking manually for updates.
System properties
---------------------------
Right click on computer and go to Properties > Advanced > Performances:
* If your don't care about visual effect, in Visual Effect select "Adjust for best performance"
* I personnally tweak the page file size to win some place on my root.
In Advanced>Performances>Advanced tab, change Virtual memory:
1. unselect automatically manage paging file size for all drive
2. click on drive C:
3. select no paging file
4. click on set
5. click on drive d:
6. select customer size
7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notify a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
* System Protection
Here you can disable Shadow Folder because it has little sense in case of qubes because
* we do backup regularly of AppVMs/TemplateVMs;
* we can revert at least one template change if we break something.
Select drives where system protection is enabled and click Configure. "Turn of system protection" "Delete all restore points"
* Remote
Unselect Allow Remote Assistance connetions to this computer.
Task scheduler
-----------------------
Open the task scheduler and *disable* the following tasks.
If you remove these tasks they may be recreated automatically by various windows management tools (such as defragmentation)
* Autochk: All
* Application Experience: All
* Customer Experience Improvement Program: All
* Defrag: All
* DiskDiagnosis: All (the disk is virtual anyway so S.M.A.R.T. has no sense)
* Maintenance: All
* SystemRestore: All
* WindowsBackup: All
Disable hibernation
------------------------------
and clean hyberfil.sys
1. Ensure that you disabled the Power service (you may need to reboot so that the Power service is effectively stopped).
2. Run a cmd.exe as an administrator:
> powercfg -h off
C:\hyberfil.sys should now be deleted
Manual tasks that can/should be started in the template
===================================
* Disk defragmentation
* Windows Update
* Windows file cleaning
1. Run windows drive cleaner as Administrator.
2. Enable all the task and run the cleaner
* CCleaner file cleaning
1. Install CCleaner free
2. Copy the attached ccleaner configuration file in CCleaner program file folder
3. Run ccleaner with all option set except "wipe free space" (it will also remove user history and preferences)
4. Run ccleaner only with the option "wipe free space".
It will write zeros in all unused space. This will allow you to strip the root.img file later
* TemplateVM stripping
Ensure that you know what you are doing in this section as you may destroy by error your template root.img file.
* If you ran ccleaner with "wipe free space", follow the following procedure
1. from dom0, go to /var/lib/templates-vm/yourtemplate
2. copy root.img using the following command
> cp --sparse=always root.img root.img.clean
3. if the copy worked, you can move the new root file by running this command
> mv root.img.clean root.img
* If don't managed to fill the free space with zeroes, you can follow the following *unsafe* undocumented procedure
1. from dom0, go to /var/lib/templates-vm/yourtemplate
2. check the partitionning to identify the filesystem offset of root.img
3. mount the filesystem
4. create a file with zeros inside the filesystem until the mounted filesystem is full
5. remove the file
6. unmount the partition
7. make a copy of root.img in sparse mode.

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

76
BuildingArchlinuxTemplate.md → en/developers/building/building-archlinux-template.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: BuildingArchlinuxTemplate
permalink: /doc/BuildingArchlinuxTemplate/
redirect_from: /wiki/BuildingArchlinuxTemplate/
title: Building Archlinux Template
permalink: /en/doc/building-archlinux-template/
redirect_from:
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
---
Template building
@ -23,17 +25,17 @@ Change the following variables GIT\_SUBDIR=marmarek DISTS\_VM=archlinux
Get all required sources
------------------------
{% highlight trac-wiki %}
~~~
make get-sources
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
COMPONENTS:=$(filter-out desktop-linux-kde desktop-linux-xfce,$(COMPONENTS))
{% endhighlight %}
~~~
Just don't forget that you need to comment this line again if you want to build the whole Qubes-OS install CD.
@ -42,23 +44,23 @@ 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:
{% highlight trac-wiki %}
~~~
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
{% endhighlight %}
~~~
Now build the template itself
-----------------------------
This can take again several hours, especially the first time you built and archlinux template:
{% highlight trac-wiki %}
~~~
make linux-template-builder
{% endhighlight %}
~~~
Retrieve your template
----------------------
@ -75,30 +77,30 @@ 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:
{% highlight trac-wiki %}
~~~
ISO_VERSION=2013.06.01
{% endhighlight %}
~~~
You will also need to download the signature matching this ISO version inside qubes-src/linux-template-builder/scripts\_archlinux/:
{% highlight trac-wiki %}
~~~
wget http://mir.archlinux.fr/iso/2013.06.01/archlinux-2013.06.01-dual.iso.sig
{% endhighlight %}
~~~
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"\>:
{% highlight trac-wiki %}
~~~
<deny send_destination="org.freedesktop.NetworkManager"/>
{% endhighlight %}
~~~
to
{% highlight trac-wiki %}
~~~
<allow send_destination="org.freedesktop.NetworkManager"/>
{% endhighlight %}
~~~
DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all.
--------------------------------------------------------------------------------------
@ -111,26 +113,26 @@ This is apparently a bug in Archlinux between glibc and pulseaudio package 4.0-6
Error when building the gui-agent-linux with pulsecore error
------------------------------------------------------------
{% highlight trac-wiki %}
~~~
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
{% endhighlight %}
~~~
You can check the current archlinux pulseaudio version like this:
{% highlight trac-wiki %}
~~~
sudo chroot chroot-archlinux/ pacman -Qi pulseaudio
{% endhighlight %}
~~~
chroot-archlinux/dev/pts has not been unmounted
-----------------------------------------------
@ -154,15 +156,15 @@ The boot process fails without visible errors in the logs, but spawn a recovery
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:
{% highlight trac-wiki %}
~~~
extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
{% endhighlight %}
~~~
to:
{% highlight trac-wiki %}
~~~
extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"
{% endhighlight %}
~~~
Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
----------------------------------------------------------------------------------------------------
@ -171,15 +173,15 @@ Apply the following fix in the template to revert the variable name to the old Q
You can edit the template the following way:
{% highlight trac-wiki %}
~~~
sudo mkdir /mnt/vm
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
sudo chroot /mnt/vm
{% endhighlight %}
~~~
Then apply the fix:
{% highlight trac-wiki %}
~~~
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
@ -212,19 +214,19 @@ sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_t
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
{% endhighlight %}
~~~
Do not forgot to:
{% highlight trac-wiki %}
~~~
umount /mnt/vm
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
sudo rpm -U --nodeps yourpackage.rpm
{% endhighlight %}
~~~

26
BuildingNonFedoraTemplate.md → en/developers/building/building-non-fedora-template.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: BuildingNonFedoraTemplate
permalink: /doc/BuildingNonFedoraTemplate/
redirect_from: /wiki/BuildingNonFedoraTemplate/
title: Building Non-Fedora Template
permalink: /en/doc/building-non-fedora-template/
redirect_from:
- /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/
---
Building a TemplateVM for ArchLinux (or another non fedora OS)
@ -24,11 +26,11 @@ You need to install your OS inside a chroot that will be used to build all the r
The scripts you will be interested in will be inside the qubes-src/linux-template-builder project:
{% highlight trac-wiki %}
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
{% endhighlight %}
~~~
### 00\_prepare.sh
@ -42,19 +44,19 @@ The goal of this script is to install a base environment of your target OS insid
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:
{% highlight trac-wiki %}
~~~
make linux-template-builder
{% endhighlight %}
~~~
Qubes builder Makefiles
-----------------------
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside qubes-builder:
{% highlight trac-wiki %}
~~~
prepare-chroot-yourOSname
Makefile.yourOSname
{% endhighlight %}
~~~
### prepare-chroot-yourOSname
@ -103,11 +105,11 @@ Additional Installation scripts
Again you need to work on scripts inside the qubes-src/linux-template-builder project:
{% highlight trac-wiki %}
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
{% endhighlight %}
~~~
### 02\_install\_groups.sh
@ -136,7 +138,7 @@ As soon as you manage to make qrexec and qubes-gui-agent working, it should be s
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](/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).
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.

76
DevelopmentWorkflow.md → en/developers/building/development-workflow.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: DevelopmentWorkflow
permalink: /doc/DevelopmentWorkflow/
redirect_from: /wiki/DevelopmentWorkflow/
title: Development Workflow
permalink: /en/doc/development-workflow/
redirect_from:
- /doc/DevelopmentWorkflow/
- /wiki/DevelopmentWorkflow/
---
Development Workflow
@ -10,21 +12,22 @@ Development Workflow
A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/QubesBuilder/). This guide assumes you're using qubes-builder to build Qubes.
First things first, setup [QubesBuilder](/en/doc/qubes-builder/). This guide assumes you're using qubes-builder to build Qubes.
Repositories and Committing Code
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:**
{% highlight trac-wiki %}
~~~
$ cd qubes-builder/qubes-src/qubes-manager
$ git remote add abel git@github.com:abeluck/qubes-manager.git
{% endhighlight %}
~~~
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.
@ -36,55 +39,55 @@ When you are ready to submit your changes to Qubes to be merged, push your chang
In qubes-builder/qubes-src/kernel:
{% highlight trac-wiki %}
~~~
make prep
{% endhighlight %}
~~~
The resulting tree will be in kernel-\<VERSION\>/linux-\<VERSION\>:
{% highlight trac-wiki %}
~~~
ls -ltrd kernel*/linux*
{% endhighlight %}
~~~
{% highlight trac-wiki %}
~~~
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
{% endhighlight %}
~~~
#### Go to the kernel tree and update the version
In qubes-builder/qubes-src/kernel:
{% highlight trac-wiki %}
~~~
cd kernel-3.4.18/linux-3.4.18
{% endhighlight %}
~~~
#### Changing the config
In kernel-3.4.18/linux-3.4.18:
{% highlight trac-wiki %}
~~~
cp ../../config-pvops .config
make oldconfig
{% endhighlight %}
~~~
Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18:
{% highlight trac-wiki %}
~~~
make menuconfig
{% endhighlight %}
~~~
Copy the modified config back into the kernel tree:
{% highlight trac-wiki %}
~~~
cp .config ../../../config-pvops
{% endhighlight %}
~~~
#### Patching the code
TODO: describe the workflow for patching the code, below are some random notes, not working well
{% highlight trac-wiki %}
~~~
ln -s ../../patches.xen
export QUILT_PATCHES=patches.xen
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
@ -100,7 +103,7 @@ quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \
quilt refresh
cd ../..
vi series-pvops.conf
{% endhighlight %}
~~~
#### Building RPMS
@ -112,22 +115,22 @@ You might want to take a moment here to review (git diff, git status), commit yo
To actually build RPMS, in qubes-src/kernel:
{% highlight trac-wiki %}
~~~
make rpms
{% endhighlight %}
~~~
RPMS will appear in qubes-src/kernel/rpm/x86\_64:
{% highlight trac-wiki %}
~~~
-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
{% endhighlight %}
~~~
### Useful [QubesBuilder](/doc/QubesBuilder/) commands
### 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
@ -141,13 +144,13 @@ When developing it is convenient to be able to rapidly test changes. Assuming yo
Here are some handy scripts Marek has shared to facilitate this.
You may also like to run your [test environment on separate machine](/doc/TestBench/).
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
{% highlight trac-wiki %}
~~~
#!/bin/sh
set -x
@ -168,25 +171,26 @@ 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/I hope to
{% endhighlight %}
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
{% highlight trac-wiki %}
~~~
#!/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/
{% endhighlight %}
~~~
### Copy from dom0 to an appvm
{% highlight trac-wiki %}
~~~
#/bin/sh
#
# usage ./cp-domain <vm_name> <file_to_copy>
@ -197,4 +201,4 @@ 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"
{% endhighlight %}
~~~

88
en/developers/building/installation-iso-building.md Normal file
View File

@ -0,0 +1,88 @@
---
layout: doc
title: Installation ISO Building
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.

30
KdeDom0.md → en/developers/building/kde-dom0.md
View File

@ -1,21 +1,23 @@
---
layout: doc
title: KdeDom0
permalink: /doc/KdeDom0/
redirect_from: /wiki/KdeDom0/
title: KDE dom0
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](/doc/SourceCode/)) 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 :)
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
-------------------
{% highlight trac-wiki %}
~~~
git clone git://qubes-os.org/mainstream/kde-dom0.git kde-dom0
{% endhighlight %}
~~~
Building the packages
---------------------
@ -24,27 +26,27 @@ 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):
{% highlight trac-wiki %}
~~~
make get-sources verify-sources
{% endhighlight %}
~~~
Now, check if you have all the required build dependencies:
{% highlight trac-wiki %}
~~~
make prep
{% endhighlight %}
~~~
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):
{% highlight trac-wiki %}
~~~
make rpms
{% endhighlight %}
~~~
**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:
{% highlight trac-wiki %}
~~~
yum install kdelibs-devel-{version}
{% endhighlight %}
~~~
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`).

20
QubesBuilderDetails.md → en/developers/building/qubes-builder-details.md
View File

@ -1,22 +1,24 @@
---
layout: doc
title: QubesBuilderDetails
permalink: /doc/QubesBuilderDetails/
redirect_from: /wiki/QubesBuilderDetails/
title: Qubes Builder Details
permalink: /en/doc/qubes-builder-details/
redirect_from:
- /doc/QubesBuilderDetails/
- /wiki/QubesBuilderDetails/
---
[QubesBuilder](/doc/QubesBuilder/) "API"
[QubesBuilder](/en/doc/qubes-builder/) "API"
========================================
Components Makefile.builder file
--------------------------------
[QubesBuilder](/doc/QubesBuilder/) 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](/doc/QubesBuilder/).
[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](/doc/QubesBuilder/) 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](/doc/QubesBuilder/) will install all makedepends, then build the package.
- `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.
@ -35,8 +37,8 @@ Variables for Windows build:
- `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](/doc/QubesBuilder/) 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](/doc/QubesBuilder/) 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.
- `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
---------------------

106
QubesBuilder.md → en/developers/building/qubes-builder.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: QubesBuilder
permalink: /doc/QubesBuilder/
redirect_from: /wiki/QubesBuilder/
title: Qubes Builder
permalink: /en/doc/qubes-builder/
redirect_from:
- /doc/QubesBuilder/
- /wiki/QubesBuilder/
---
Building Qubes from scratch
@ -21,74 +23,64 @@ In order to use it one should use an rpm-based distro, like Fedora :) and should
- wget
- rpmdevtools
- python-sh
- dialog
- rpm-sign
Unusually one can install those packages by just issuing:
{% highlight trac-wiki %}
sudo yum install git createrepo rpm-build make wget rpmdevtools python-sh
{% endhighlight %}
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.:
{% highlight trac-wiki %}
cp builder.conf.default builder.conf
# edit the builder.conf file and set the following variables:
# (make sure to leave no spaces around '=' sign!)
NO_SIGN=1
# As time of writing this, the default for Qubes 2 Dom0 is fc20
# and VMs is fc20 so if you want to build Qubes 2
DIST_DOM0=fc20
DISTS_VM=fc20
{% endhighlight %}
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.:
{% highlight trac-wiki %}
%_signature gpg
%_gpg_path /home/user/.gnupg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
{% endhighlight %}
%_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:
{% highlight trac-wiki %}
# Import the Qubes master key
gpg --recv-keys 0x36879494
# Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
wget http://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
wget https://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
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:
# (make sure to leave no spaces around '=' sign!)
# NO_SIGN="1"
# Verify its integrity:
git tag -v `git describe`
# Download all components:
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
# NO_SIGN="1"
make get-sources
# Download all components:
# And now to build all Qubes rpms (this will take a few hours):
make get-sources
make qubes
# And now to build all Qubes rpms (this will take a few hours):
# ... and then to build the ISO
make qubes
make iso
{% endhighlight %}
# ... and then to build the ISO
make iso
And this should produce a shiny new ISO.
@ -97,9 +89,9 @@ You can also build selected component separately. Eg. to compile only gui virtua
make gui-daemon
Full list you can get from make help. For advanced use and preparing sources
for use with [QubesBuilder](/doc/QubesBuilder/) take a look at [doc directory
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](/doc/QubesBuilderDetails/) page.
[QubesBuilderDetails](/en/doc/qubes-builder-details/) page.
Making customized build
-----------------------
@ -112,23 +104,21 @@ If you want to somehow modify sources, you can also do it, here are some basic s
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
1. Download unmodified sources
3. Download unmodified sources
make get-sources
1. **Make your modifications here**
4. **Make your modifications here**
1. Build the Qubes
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`.
> `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
>
> {% highlight trac-wiki %}
> make xen core kernel gui addons docs template kde-dom0 installer qubes-manager dom0-updates
> {% endhighlight %}
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
@ -137,13 +127,11 @@ If you want to somehow modify sources, you can also do it, here are some basic s
Code verification keys management
=================================
[QubesBuilder](/doc/QubesBuilder/) 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:
[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:
{% highlight trac-wiki %}
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
{% endhighlight %}
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.

30
QubesR3Building.md → en/developers/building/qubes-r3-building.md
View File

@ -1,56 +1,58 @@
---
layout: doc
title: QubesR3Building
permalink: /doc/QubesR3Building/
redirect_from: /wiki/QubesR3Building/
title: Qubes R3 Building
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](/doc/QubesBuilder/) for more info):
Ensure your system is rpm-based and that you have necessary dependencies installed (see [QubesBuilder](/en/doc/qubes-builder/) for more info):
{% highlight trac-wiki %}
~~~
sudo yum install git createrepo rpm-build make wget rpmdevtools pandoc
{% endhighlight %}
~~~
Get the necessary keys to verify the sources:
{% highlight trac-wiki %}
~~~
$ 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
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
$ git clone git://github.com/QubesOS/qubes-builder.git
$ cd qubes-builder
$ git describe --exact-match HEAD
<some tag>
$ git tag -v <some tag>
{% endhighlight %}
~~~
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):
{% highlight trac-wiki %}
~~~
cp example-configs/qubes-os-master.conf builder.conf
{% endhighlight %}
~~~
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:
{% highlight trac-wiki %}
~~~
$ make get-sources qubes
$ make sign-all # this requires setting SIGN_KEY in the builder.conf, can be skipped for test builds.
$ make iso
{% endhighlight %}
~~~
Enjoy your new ISO!

6
USBVM.md → en/developers/building/usbvm.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: USBVM
permalink: /doc/USBVM/
redirect_from: /wiki/USBVM/
permalink: /en/doc/usbvm/
redirect_from:
- /doc/USBVM/
- /wiki/USBVM/
---
USB Pass through: USBVM

45
CodingStyle.md → en/developers/coding-style.md
View File

@ -1,8 +1,11 @@
---
layout: doc
title: CodingStyle
permalink: /doc/CodingStyle/
redirect_from: /wiki/CodingStyle/
title: Coding Style
permalink: /en/doc/coding-style/
redirect_from:
- /doc/CodingStyle/
- /wiki/CodingStyle/
- /trac/wiki/CodingStyle/
---
Coding Guidelines for Qubes Developers
@ -18,7 +21,7 @@ Maintaining proper coding style is very important for any larger software projec
- 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 how 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.
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!
@ -45,14 +48,14 @@ General typographic conventions
- Comments should be indent together with the code, e.g. like this:
{% highlight trac-wiki %}
~~~
for (...) {
// The following code finds PGP private key matching the given public key in O(1)
while (key_found) {
(...)
}
}
{% endhighlight %}
~~~
File naming conventions
-----------------------
@ -63,12 +66,12 @@ File naming conventions
- 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-*`
- Auxilary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
- Helper, non-exeutable files in `/usr/share/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 the reflect the current state of system in `/var/run/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:**
@ -79,35 +82,35 @@ File naming conventions
General programming style guidelines
------------------------------------
- Do not try to impress wit your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
- 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 first first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
- 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:
{% highlight trac-wiki %}
~~~
// Return window id
int get_window_id (...) {
(...)
return id;
}
{% endhighlight %}
~~~
- 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.:
{% highlight trac-wiki %}
~~~
#if 0
(...) // Some unused code here
#endif
{% endhighlight %}
~~~
... and preferably use some descriptive macro instead of just `0`, e.g.:
{% highlight trac-wiki %}
~~~
#if USE_OLD_WINDOW_TRAVERSING
(...) // Some unused code here
#endif
{% endhighlight %}
~~~
Not sure how to do similar thing in Python... Anyone?
@ -135,7 +138,7 @@ Security coding guidelines
- 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.:
{% highlight trac-wiki %}
~~~
read_struct(untrusted_conf);
/* sanitize start */
if (untrusted_conf.width > MAX_WINDOW_WIDTH)
@ -144,14 +147,14 @@ Security coding guidelines
untrusted_conf.height = MAX_WINDOW_HEIGHT;
width = untrusted_conf.width;
height = untrusted_conf.height;
{% endhighlight %}
~~~
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as seen above.
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
Python-specific guidelines
--------------------------
- Please follow the guidlines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
- 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
-----------------------------

15
ContributingHowto.md → en/developers/contributing.md
View File

@ -1,8 +1,11 @@
---
layout: doc
title: ContributingHowto
permalink: /doc/ContributingHowto/
redirect_from: /wiki/ContributingHowto/
title: Contributing
permalink: /en/doc/contributing/
redirect_from:
- /doc/contributing/
- "/doc/ContributingHowto/"
- "/wiki/ContributingHowto/"
---
How can I contribute to the Qubes Project?
@ -12,14 +15,16 @@ Ok, so you think Qubes Project is cool and you would like to contribute? You are
First you should decide what you are interested in (and good in). The Qubes project would welcome contributions in various areas:
- Testing and [bug reporting](/doc/BugReportingGuide/)
- 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](/doc/QubesLists/) 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.
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.

48
AutomatedTests.md → en/developers/debugging/automated-tests.md
View File

@ -1,17 +1,18 @@
---
layout: doc
title: Automated tests
permalink: /doc/AutomatedTests/
title: Automated Tests
permalink: /en/doc/automated-tests/
redirect_from: /doc/AutomatedTests/
---
Automatic tests
===============
Starting with Qubes R3 we use [python unittest](TODO) to perform automatic
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 deliver much more stable releases.
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
@ -94,3 +95,42 @@ For example to run only tests for fedora-21 template, you can use `-l` option, t
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

30
Profiling.md → en/developers/debugging/profiling.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: Profiling
permalink: /doc/Profiling/
redirect_from: /wiki/Profiling/
permalink: /en/doc/profiling/
redirect_from:
- /doc/Profiling/
- /wiki/Profiling/
---
Profiling
@ -15,17 +17,17 @@ For the purpose of this document, `qubes-dev` is name of the domain used for pos
Requirements
------------
{% highlight trac-wiki %}
~~~
yum install gprof2dot graphviz
git clone http://git.woju.eu/qubes/profiling.git
{% endhighlight %}
~~~
If you profile something on dom0, move `Upload.sh` from repository to dom0:
{% highlight trac-wiki %}
~~~
mkdir -p ~/profiling
qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
{% endhighlight %}
~~~
- WARNING: this will obviously be running third party code which is not signed by ITL nor Fedora. You have been warned.
@ -62,28 +64,28 @@ Remember to revert your changes to application afterwards.
If you are in dom0:
{% highlight trac-wiki %}
~~~
cd ~/profiling
./Upload.sh
{% endhighlight %}
~~~
### Analyse
{% highlight trac-wiki %}
~~~
make
{% endhighlight %}
~~~
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`.
{% highlight trac-wiki %}
~~~
make index.html
{% endhighlight %}
~~~
This creates `index.html` with all SVG graphics linked to TXT files. Ready for upload.
{% highlight trac-wiki %}
~~~
make REMOTE=example.com:public_html/qubes/profiling/ upload
{% endhighlight %}
~~~
Example
-------

22
TestBench.md → en/developers/debugging/test-bench.md
View File

@ -1,8 +1,10 @@
---
layout: doc
title: TestBench
permalink: /doc/TestBench/
redirect_from: /wiki/TestBench/
title: Test Bench
permalink: /en/doc/test-bench/
redirect_from:
- /doc/TestBench/
- /wiki/TestBench/
---
Test bench for Dom0
@ -10,7 +12,7 @@ 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](/doc/QubesBuilder/) and you have it set up and running flawlessly.
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
----------------------
@ -57,9 +59,9 @@ Now configure your DHCP server so your testbench gets static IP and connect your
Install `openssh-server` on your testbench:
{% highlight trac-wiki %}
~~~
yum install openssh-server
{% endhighlight %}
~~~
Ensure that sudo works without password from your user account (it should by default).
@ -70,19 +72,19 @@ Development VM
Arrange firewall so you can reach the testbench from your `qubes-dev` VM. Generate SSH key in `qubes-dev`:
{% highlight trac-wiki %}
~~~
ssh-keygen -t ecdsa -b 521
{% endhighlight %}
~~~
Add the following section in `.ssh/config` in `qubes-dev`:
{% highlight trac-wiki %}
~~~
Host testbench
# substitute username in testbench
User user
# substitute address of your testbench
HostName 192.168.123.45
{% endhighlight %}
~~~
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.

128
en/developers/debugging/vm-interface.md Normal file
View File

@ -0,0 +1,128 @@
---
layout: doc
title: VM Configuration Interface
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.

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