Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-07-29 09:39:09 -04:00
Code Issues Projects Releases Packages Wiki Activity

Move current pages to /en/ subdirectory

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

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

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

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

@ -0,0 +1,101 @@
---
layout: doc
title: Emergency Backup Recovery - format version 3
permalink: /en/doc/backup-emergency-restore-v3/
redirect_from: /doc/BackupEmergencyRestoreV3/
---
Emergency Backup Recovery without Qubes - format version 3
==========================================================
This page describes how to perform an emergency restore of a backup created on Qubes R2 or later (which uses backup format version 3).
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
**Note:** In the following example, the backup file is both *encrypted* and *compressed*.
1. Untar the main backup file.
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
backup-header.hmac
qubes.xml.000
qubes.xml.000.hmac
vm1/private.img.000
vm1/private.img.000.hmac
vm1/icon.png.000
vm1/icon.png.000.hmac
vm1/firewall.xml.000
vm1/firewall.xml.000.hmac
vm1/whitelisted-appmenus.list.000
vm1/whitelisted-appmenus.list.000.hmac
dom0-home/dom0user.000
dom0-home/dom0user.000.hmac
2. Verify the integrity of the `backup-header` file, which contains basic information about your backup.
[user@restore ~]$ openssl dgst -sha512 -hmac "your_passphrase" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
[user@restore ~]$ cat backup-header.hmac
(stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3), however it is not recommended to open this file until its integrity and authenticity has been verified (the current step). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
3. Read the `backup-header`. You'll need some of this information later. The file will look similar to this:
[user@restore ~]$ cat backup-header
version=3
hmac-algorithm=SHA512
crypto-algorithm=aes-256-cbc
encrypted=True
compressed=True
compression-filter=gzip
**Note:** If you see `version=2` here, go to [Emergency Backup Recovery - format version 2](/doc/BackupEmergencyRestoreV2/) instead.
4. Verify the integrity of the `private.img` file which houses your data.
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
**Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error.
**Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 3). A complete list of supported message digest algorithms can be found with `openssl list-message-digest-algorithms`.
5. Decrypt the `private.img` file.
[user@restore vm1]$ cat private.img.??? | openssl enc -d -pass pass:your_passphrase -aes-256-cbc -out private.img.dec
**Note:** If your backup was encrypted with a cipher algorithm other than `aes-256-cbc`, you must substitute the correct cipher command. This information is contained in the `backup-header` file (see step 3). A complete list of supported cipher algorithms can be found with `openssl list-cipher-algorithms`.
6. Decompress the decrypted `private.img` file.
[user@restore vm1]$ zforce private.img.dec
private.img.dec -- replaced with private.img.dec.gz
[user@restore vm1]$ gunzip private.img.dec.gz
**Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program. This information is contained in the `backup-header` file (see step 3).
7. Untar the decrypted and decompressed `private.img` file.
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
8. Mount the private.img file and access your data.
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
This data has been successfully recovered!
9. Success! If you wish to recover data from more than one VM in your backup, simply repeat steps 4--8 for each additional VM.
**Note:** You may wish to store a copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git repository:
https://github.com/QubesOS/qubes-doc.git

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -0,0 +1,36 @@
---
layout: doc
title: ManagingAppVmShortcuts
permalink: /en/doc/managing-appvm-shortcuts/
redirect_from:
- /doc/ManagingAppVmShortcuts/
- /wiki/ManagingAppVmShortcuts/
---
Managing shortcuts to applications in AppVMs
============================================
For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one "start menu" in dom0. Clicking on such shortcut runs the assigned application in its AppVM.
![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png)
To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically):
`qvm-sync-appmenus vmname`
After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown:
![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png)
The above image shows that Windows HVMs are also supported (provided that Qubes Tools are installed).
Behind the scenes
-----------------
List of installed applications for each AppVM is stored in its template's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Example: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/en/doc/qrexec/) in the target domain. This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.

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

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

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

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

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

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