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

Merge branch 'master' into patch-5

Browse source
This commit is contained in:
awokd 2018-02-10 20:26:01 +00:00 • committed by GitHub
commit 0fb020c87c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
141 changed files with 2027 additions and 1071 deletions
Download patch file Download diff file Expand all files Collapse all files

184
common-tasks/backup-restore.md
View file

@ -11,96 +11,218 @@ redirect_from:
Qubes Backup, Restoration, and Migration
========================================
**Caution:** The Qubes backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971). It is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups.
**Caution:** The Qubes R3.2 backup system currently relies on a [weak key derivation scheme](https://github.com/QubesOS/qubes-issues/issues/971).
Although resolved in R4.0 and higher with the switch to scrypt, it is *strongly recommended* that users select a *high-entropy* passphrase for use with Qubes backups.
With Qubes, it's easy to back up and restore your whole system, as well as to migrate between two physical machines.
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI. There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/).
As of Qubes R2B3, these functions are integrated into the Qubes VM Manager GUI.
There are also two command-line tools available which perform the same functions: [qvm-backup](/doc/dom0-tools/qvm-backup/) and [qvm-backup-restore](/doc/dom0-tools/qvm-backup-restore/).
Creating a Backup
Creating a Backup (R4.0 and later)
-----------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list. This brings up the **Qubes Backup VMs** window.
1. Go to **Applications menu -> System Tools -> Backup Qubes**.
This brings up the **Qubes Backup VMs** window.
2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up.
2. Move the VMs that you want to back up to the right-hand **Selected** column.
VMs in the left-hand **Available** column will not be backed up.
**Note:** A VM must be shut down in order to be backed up. Currently running VMs appear in red.
You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
Normally this should be left on unless you have a specific reason otherwise.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
This destination directory must already exist.
If it does not exist, you must create it manually prior to backing up.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM.
Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM.
This can be used to send your backup directly to, e.g., a remote server using SSH.
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box.
**Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Creating a Backup (R3.2 and earlier)
-----------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Backup VMs** in the drop-down list.
This brings up the **Qubes Backup VMs** window.
2. Move the VMs that you want to back up to the right-hand **Selected** column.
VMs in the left-hand **Available** column will not be backed up.
**Note:** A VM must be shut down in order to be backed up.
Currently running VMs appear in red.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a [USB mass storage device](/doc/stick-mounting/), first mount the device in a VM, then select the mount point inside that VM as the backup destination.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup. For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply type `backups` in this field. This destination directory must already exist. If it does not exist, you must create it manually prior to backing up.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
If it does not exist, you must create it manually prior to backing up.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM. Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM. This can be used to send your backup directly to, e.g., a remote server using SSH.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM.
Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM.
This can be used to send your backup directly to, e.g., a remote server using SSH.
At this point, you must also choose whether to encrypt your backup by checking or unchecking the **Encrypt backup** box.
**Note:** It is strongly recommended that you opt to encrypt all backups which will be sent to untrusted destinations!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification. If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification. If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
If you decide not to encrypt your backup (by unchecking the **Encrypt backup** box), the passphrase you supply will be used **only** for integrity verification.
If you supply a passphrase but do not check the **Encrypt backup** box, your backup will **not** be encrypted!
4. When you are ready, click **Next**. Qubes will proceed to create your backup. Once the progress bar has completed, you may click **Finish**.
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup
Restoring from a Backup (R4.0 and later)
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list. This brings up the **Qubes Restore VMs** window.
1. Go to **Applications menu -> System Tools -> Restore Backup**.
This brings up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/stick-mounting/), select the device in the drop-down box next to **Device**.
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
You must also specify the directory in which the backup resides (or a command to be executed in a VM). If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3. For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again type `backups` into the **Backup directory** field.
**Note:** After you have typed the directory location of the backup in the **Backup directory** field, click the ellipsis button `...` to the right of the field.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click it or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory. If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **skip dom0**: If this box is checked, dom0's home directory will not be restored from your backup.
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file.
See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
4. If your backup is encrypted, you must check the **Encrypted backup** box. If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification. If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
All backups made from a Qubes R4.0 system will be encrypted.
**Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system. You must first remove or change the name of any VM with the same name in order to restore such a VM.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
5. When you are ready, click **Next**. Qubes will proceed to restore from your backup. Once the progress bar has completed, you may click **Finish**.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
Restoring from a Backup (R3.2 and earlier)
-----------------------
1. In **Qubes VM Manager**, click **System** on the menu bar, then click **Restore VMs from backup** in the drop-down list.
This brings up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing**: If any of the VMs in your backup depended upon a NetVM, ProxyVM, or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file. See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
**Note:** A VM cannot be restored from a backup if a VM with the same name already exists on the current system.
You must first remove or change the name of any VM with the same name in order to restore such a VM.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
Emergency Backup Recovery without Qubes
---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind. No special Qubes-specific tools are required to access data backed up by Qubes. In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in mind.
No special Qubes-specific tools are required to access data backed up by Qubes.
In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
For emergency restore of backup created on Qubes R2 or newer take a look [here](/doc/backup-emergency-restore-v3/). For backups created on earlier Qubes version, take a look [here](/doc/backup-emergency-restore-v2/).
Refer to the following for emergency restore of a backup created on:
* [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
* [Qubes R3](/doc/backup-emergency-restore-v3/)
* [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
Migrating Between Two Physical Machines
---------------------------------------
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine. All of your settings and data will be preserved!
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine.
All of your settings and data will be preserved!
Choosing a Backup Passphrase
----------------------------
Here are some things to consider when selecting a passphrase for your backups:
* If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. If your system drive decryption passphrase is already sufficiently strong, it may not.)
* An adversary who has access to your backups may try to substitute one backup for another. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
* If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). On the othe hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
* If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
If your system drive decryption passphrase is already sufficiently strong, it may not.)
* An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
* If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
Notes
-----
* The Qubes backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme. The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective. Users are advised to use a very high entropy passphrase for Qubes backups. For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ).
* The Qubes R3.2 and earlier backup system relies on `openssl enc`, which is known to use a very weak key derivation scheme.
The Qubes backup system also uses the same passphrase for authentication and for encryption, which is problematic from a security perspective.
Users are advised to use a very high entropy passphrase for Qubes backups.
For a full discussion, see [this ticket](https://github.com/QubesOS/qubes-issues/issues/971) and [this thread](https://groups.google.com/d/msg/qubes-devel/CZ7WRwLXcnk/u_rZPoVxL5IJ).
* For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
* If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

70
common-tasks/dispvm.md
View file

@ -11,16 +11,56 @@ redirect_from:
Disposable VMs (DispVMs)
========================
A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed.
Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser.
Changes made to a file opened in a Disposable VM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
DispVMs can be created either directly from Dom0 or from within AppVMs.
Once a DispVM has been created it will appear in Qubes VM Manager with the name "dispX".
A Disposable VM (DispVM) is a lightweight VM that can be created quickly and will disappear when closed.
Disposable VMs are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an AppVM, choosing the `Open in Disposable VM` option on a file will launch a DispVM for just that file.
Changes made to a file opened in a DispVM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
DispVMs can be launched either directly from Dom0's Start Menu or terminal window, or from within AppVMs.
While running, DispVMs will appear in Qubes VM Manager with the name `disp####`.
See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a Disposable VM.
Disposable VMs and Networking
Disposable VMs and Networking (R4.0 and later)
-----------------------------
Similarly to how AppVMs are based on their underlying [TemplateVM](https://www.qubes-os.org/doc/glossary/#templatevm), DispVMs are based on their underlying [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
R4.0 introduces the concept of multiple DVM Templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default DVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DVM Template available for your use.
You can set any AppVM to have the ability to act as a DVM Template with:
qvm-prefs <vmname> template_for_dispvms true
The default system wide DVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in Disposable VM` from inside an AppVM will open the document in a DispVM based on the default DVM Template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default DispVM" setting to specify which DVM Template will be used to launch DispVMs from that VM.
This can also be changed from the command line with:
qvm-prefs <vmname> default_dispvm <dvmtemplatename>
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DVM Template to use itself, so DispVMs launched from within the AppVM/DVM Template would inherit the same settings.
NetVM and firewall rules for DVM Templates can be set as they can for a normal VM.
By default a DispVM will inherit the NetVM and firewall settings of the DVM Template on which it is based.
This is a change in behaviour from R3.2, where DispVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DispVM from an AppVM will result in it using the network/firewall settings of the DVM Template on which it is based.
For example, if an AppVM uses sys-net as its NetVM, but the default system DispVM uses sys-whonix, any DispVM launched from this AppVM will have sys-whonix as its NetVM.
**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DispVM uses sys-net, launching a DispVM from inside anon-whonix will result in the DispVM using sys-net.
A Disposable VM launched from the Start Menu inherits the NetVM and firewall settings of the DVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DVM Template *does* affect the NetVM of DispVMs launched from the Start Menu.
Different DVM Templates with individual NetVM settings can be added to the Start Menu.
Disposable VMs and Networking (R3.2 and earlier)
-----------------------------
NetVM and firewall rules for Disposable VMs can be set as they can for a normal VM.
@ -29,7 +69,7 @@ Thus if an AppVM uses sys-net as its NetVM, any DispVM launched from this AppVM
You can change this behaviour for individual VMs: in Qubes VM Manager open VM Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "NetVM for DispVM" setting to change the NetVM of any DispVM launched from that VM.
A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](https://www.qubes-os.org/doc/glossary/#dvm-template).
A Disposable VM launched from the Start Menu inherits the NetVM of the [DVM Template](/doc/glossary/#dvm-template).
By default the DVM template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
As an "internal" VM it is hidden in Qubes VM Manager, but can be shown by selecting "Show/Hide internal VMs".
Note that changing the "NetVM for DispVM" setting for the DVM Template does *not* affect the NetVM of DispVMs launched from the Start Menu; only changing the DVM Template's own NetVM does.
@ -49,7 +89,7 @@ Opening a fresh web browser instance in a new Disposable VM
-----------------------------------------------------------
Sometimes it is desirable to open an instance of Firefox within a new fresh Disposable VM.
This can be done easily using the Start Menu: just go to Start -\> System Tools -\> DispVM:Firefox web browser.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DispVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole Disposable VM will be destroyed.
@ -75,7 +115,7 @@ Sometimes it can be useful to start an arbitrary program in a DispVM. This can b
[user@vault ~]$ qvm-run '$dispvm' xterm
~~~
The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its "dispX" name as shown in the Qubes Manager or `qvm-ls`.
The created Disposable VM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
Starting an arbitrary application in a Disposable VM via command line (from Dom0)
---------------------------------------------------------------------------------
@ -83,6 +123,12 @@ Starting an arbitrary application in a Disposable VM via command line (from Dom0
The Start Menu has shortcuts for opening a terminal and a web browser in dedicated DispVMs, since these are very common tasks.
However, it is possible to start an arbitrary application in a DispVM directly from Dom0 by running
R4.0 (border colour will be inherited from that set in the `dispvm-template`)
~~~
[joanna@dom0 ~]$ qvm-run --dispvm=dispvm-template --service qubes.StartApp+xterm
~~~
R3.2 (border colour can be specified in the command)
~~~
[joanna@dom0 ~]$ echo xterm | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red
~~~
@ -92,8 +138,8 @@ However, it is possible to start an arbitrary application in a DispVM directly f
Customizing Disposable VMs
--------------------------
You can change the template used to generate the Disposable VM, and change settings used in the Disposable VM savefile.
These changes will be reflected in every new Disposable VM.
You can change the template used to generate the Disposable VMs, and change settings used in the Disposable VM savefile.
These changes will be reflected in every new Disposable VM based on that template.
Full instructions can be found [here](/doc/dispvm-customization/).
Disposable VMs and Local Forensics

2
common-tasks/full-screen-mode.md
View file

@ -24,7 +24,7 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on
Secure use of full screen mode
------------------------------
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such q mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0.
Enabling full screen mode for select VMs

8
common-tasks/managing-appvm-shortcuts.md
View file

@ -15,11 +15,11 @@ For ease of use Qubes aggregates shortcuts to applications that are installed in
![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-menu.png)
To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs does this automatically):
To make newly installed applications show up in the menu, use the **qvm-sync-appmenus** command (Linux VMs do this automatically):
`qvm-sync-appmenus vmname`
After that, select the *Add more shortcuts* entry in VM's submenu to customize which applications are shown:
After that, select the *Add more shortcuts* entry in the VM's submenu to customize which applications are shown:
![dom0-appmenu-select.png"](/attachment/wiki/ManagingAppVmShortcuts/dom0-appmenu-select.png)
@ -33,7 +33,7 @@ What about applications in DispVMs?
Behind the scenes
-----------------
The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
The list of installed applications for each AppVM is stored in dom0's `/var/lib/qubes/vm-templates/templatename/apps.templates` (or in the case of StandaloneVM: `/var/lib/qubes/appvms/vmname/apps.templates`). Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in `/var/lib/qubes/appvms/vmname/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain. Examples: `qvm-run -q --tray -a w7s 'cmd.exe /c "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Accessories\\Calculator.lnk"'` or `qvm-run -q --tray -a untrusted 'firefox %u'`
Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q --tray -a personal -- 'qubes-desktop-run /home/user/application.desktop'`
@ -45,4 +45,4 @@ For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`. In Wi
What if my application has not been automatically included in the list of available apps?
-----------------------------------------------------------------------------------------
You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a worked example of creating a new menu item for a Chrome .desktop shortcut.
You can manually create new entries in the "available applications" list of shortcuts. See [Signal](/doc/signal/) for a working example of creating a new menu item for a Chrome .desktop shortcut.

24
common-tasks/software-update-dom0.md
View file

@ -14,7 +14,7 @@ Updating software in dom0
Why would one want to update software in dom0?
----------------------------------------------
Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in Qubes 2.0.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
Normally, there should be few reasons for updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching.
However, we anticipate some other situations in which updating dom0 software might be necessary or desirable:
@ -58,12 +58,12 @@ Of course, command line tools are still available for accomplishing various upda
sudo qubes-dom0-update package-version
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Downgrade the package:
~~~
sudo yum downgrade package-version
sudo dnf downgrade package-version
~~~
### How to re-install a package
@ -76,21 +76,21 @@ You can re-install in a similar fashion to downgrading.
sudo qubes-dom0-update package
~~~
Yum will say that there is no update, but the package will nonetheless be downloaded to dom0.
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Re-install the package:
~~~
sudo yum reinstall package
sudo dnf reinstall package
~~~
Note that yum will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
Note that Dnf will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
### How to uninstall a package
If you've installed a package such as anti-evil-maid, you can remove it with the following command:
sudo yum remove anti-evil-maid
sudo dnf remove anti-evil-maid
### Testing repositories
@ -124,8 +124,16 @@ is needed for the VMs. (Note that the following example enables the unstable rep
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm
~~~
Rebuild grub config.
If the update process does not automatically do it (you should see it mentioned in the CLI output
from the update command), you may need to manually rebuild the EFI or grub config depending on which
your system uses.
EFI (Replace the file names with the correct versions for your updated kernel)
~~~
sudo /usr/bin/dracut -f /boot/efi/EFI/qubes/initramfs-4.4.31-11.pvops.qubes.x86_64.img 4.4.31-11.pvops.qubes.x86_64
~~~
Grub2
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~

30
common-tasks/software-update-vm.md
View file

@ -37,7 +37,7 @@ In order to permanently install new software, you should:
- Install/update software as usual (e.g. using dnf, or the dedicated GUI application). Then, shutdown the template VM,
- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you.
- You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their filesystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You can restart others whenever this will be convenient to you.
Testing repositories
--------------------
@ -125,17 +125,17 @@ As the TemplateVM is used for creating filesystems for other AppVMs, where you a
There are several ways to deal with this problem:
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and as we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Only install packages from trusted sources -- e.g. from the pre-configured Fedora repositories. All those packages are signed by Fedora, and we expect that at least the package's installation scripts are not malicious. This is enforced by default (at the [firewall VM level](/doc/firewall/)), by not allowing any networking connectivity in the default template VM, except for access to the Fedora repos.
- Use *standalone VMs* (see below) for installation of untrusted software packages.
- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from somehow less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
- Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted AppVMs, would get various packages from less trusted vendors, while the template used for more trusted AppVMs will only get packages from the standard Fedora repos.
Some popular questions:
- So, why should we actually trust Fedora repos -- it also contains large amount of third-party software that might buggy, right?
As long as template's compromise is considered, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and got infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
As far as the template's compromise is concerned, it doesn't really matter whether /usr/bin/firefox is buggy and can be exploited, or not. What matters is whether its *installation* scripts (such as %post in the rpm.spec) are benign or not. Template VM should be used only for installation of packages, and nothing more, so it should never get a chance to actually run the /usr/bin/firefox and get infected from it, in case it was compromised. Also, some of your more trusted AppVMs, would have networking restrictions enforced by the [firewall VM](/doc/firewall/), and again they should not fear this proverbial /usr/bin/firefox being potentially buggy and easy to compromise.
- But why trust Fedora?
@ -148,13 +148,13 @@ Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over<sup>TM
Standalone VMs
--------------
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on its own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Standalone VMs have their own copy of the whole filesystem, and thus can be updated and managed on their own. But this means that they take a few GBs on disk, and also that centralized updates do not apply to them.
Sometime it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.:
Sometimes it might be convenient to have a VM that has its own filesystem, where you can directly introduce changes, without the need to start/stop the template VM. Such situations include e.g.:
- VMs used for development (devel environments requires a lot of \*-devel packages and specific devel tools)
- VMs used for development (devel environments require a lot of \*-devel packages and specific devel tools)
- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages form less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
- VMs used for installing untrusted packages. Normally you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts). However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
In order to create a standalone VM you can use a command line like this (from console in Dom0):
@ -178,15 +178,18 @@ qvm-create <vmname> --template <templatename> --label <label>
Temporarily allowing networking for software installation
---------------------------------------------------------
Some third-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 third-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 third-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.
Some third-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 third-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 decide by themselves whether such third-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 filters http access to allow access to only something that looks like yum or apt repository. This is meant to mitigate user errors (like using a browser in the template VM), rather than some real isolation. It is done with an http proxy (tinyproxy) 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.
There are two services ([qvm-service](https://www.qubes-os.org/doc/dom0-tools/qvm-service/), [service framework](https://www.qubes-os.org/doc/qubes-service/)):
Updates proxy is a service which filters http access to allow access to only something that looks like a 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 (tinyproxy) 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 intercepts 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 allow that). If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf 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. qubes-updates-proxy (and its deprecated name: qubes-yum-proxy) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net)
2. updates-proxy-setup (and its deprecated name: yum-proxy-setup) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
@ -199,6 +202,7 @@ qrexec policy: /etc/qubes-rpc/policy/qubes.UpdatesProxy. By default this is set
sys-net and/or sys-whonix, depending on firstboot choices. This new design allows for templates to be
updated even when they are not connected to any netvm.
Example policy file in R4.0 (with whonix installed, but not set as default updatevm for all templates):
```
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
@ -230,7 +234,7 @@ a firewall rule to intercept traffic directed to 10.137.255.254:8082:
~~~
2. VMs using the proxy service Startup script (updates-proxy-setup or qubes-misc-post service) configure
dnf using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain a
dnf using /etc/yum.conf.d/qubes-proxy.conf file. It can either contain
~~~
proxy=http://10.137.255.254:8082/
@ -243,7 +247,7 @@ Note on treating AppVM's root filesystem non-persistence 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-persistence, 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.
However, one should be careful with treating this property as a reliable way to keep the AppVM malware-free. This is because the non-persistence, in the 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.

13
common-tasks/tips-and-tricks.md
View file

@ -10,9 +10,9 @@ This section provides user suggested tips that aim to increase Qubes OS usabilit
Opening links in your preferred AppVM
-------------------------------------
To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. to learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. To learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
The command `qvm-open-in-vm` lets you open a document or a URL in another VM, it takes two parameters: vmname and filename.
The command `qvm-open-in-vm` lets you open a document or a URL in another VM. It takes two parameters: vmname and filename.
For example, if you launch this command from your email AppVM:
@ -20,7 +20,7 @@ For example, if you launch this command from your email AppVM:
it will open duckduckgo.com in the `untrusted` AppVM (after you confirmed the request).
If you want this to happen automatically you can creatte a .desktop file that advertises itself as a handler for http/https links, and then setting this as your default browser.
If you want this to happen automatically you can create a .desktop file that advertises itself as a handler for http/https links, and then set this as your default browser.
Open a text editor and copy and paste this into it:
@ -46,9 +46,9 @@ Preventing data leaks
---------------------
First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip.
Suppose that you have a not so trusted enviroment, for example a Windows VM, an application that track and report it's usage or you simply want to protect your data.
Suppose that you have within a not so trusted enviroment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
Start Windows template VM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
Start the Windows TemplateVM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows.
Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112)
@ -58,4 +58,5 @@ Trim for standalone AppVMs
---------------------
The `qvm-trim-template` command is not available for a standalone AppVM.
It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm
It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm.
You can also add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM if you want trimming to be performed automatically, but there may be a performance impact on writes and deletes.

477
common-tasks/usb.md
View file

@ -24,10 +24,10 @@ Using and Managing USB Devices
Creating and Using a USB qube
-----------------------------
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23].
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this with a encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23].
Connecting an untrusted USB device to dom0 is a security risk since dom0,
like almost every OS, reads partition tables automatically. The whole
The connection of an untrusted USB device to dom0 is a security risk since dom0,
like almost every OS, reads partition tables automatically and since the whole
USB stack is put to work to parse the data presented by the USB device in order
to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
@ -46,18 +46,18 @@ steps as root in dom0:
1. Enable `sys-usb`:
sudo qubesctl top.enable qvm.sys-usb
qubesctl top.enable qvm.sys-usb
2. Apply the configuration:
sudo qubesctl state.highstate
qubesctl state.highstate
Alternatively, you can create a USB qube manually as follows:
1. Read the [Assigning Devices] page to learn how to list and identify your
USB controllers. Carefully check whether you have a USB controller that
would be appropriate to assign to a USB qube. Note that it should have no
input devices, programmable devices, and any other devices that must be
would be appropriate to assign to a USB qube. Note that it should be free
of input devices, programmable devices, and any other devices that must be
directly available to dom0. If you find a free controller, note its name
and proceed to step 2.
2. Create a new qube. Give it an appropriate name and color label
@ -112,7 +112,7 @@ opt to create a USB qube during installation. This also occurs automatically if
you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning:** USB keyboard cannot be used to type the disk passphrase
**Warning:** A USB keyboard cannot be used to type the disk passphrase
if USB controllers were hidden from dom0. Before hiding USB controllers
make sure your laptop keyboard is not internally connected via USB
(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand
@ -150,77 +150,32 @@ If you have only a USB mouse connected to a USB qube, but the keyboard is connec
You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer.
This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube.
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
How to use a USB keyboard
-------------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputKeyboard
Add a line like this one to the top of the file:
sys-usb dom0 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
For a confirmation dialog each time the USB keyboard is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
How to use a USB mouse
----------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB mouse, you must first attach it to a USB qube, then give that qube permission to pass mouse input to dom0.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputMouse
Add a line like this to the top of the file:
sys-usb dom0 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB mouse.
For a confirmation dialog each time the USB mouse is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
How to attach USB drives
------------------------
(**Note:** In the present context, the term "USB drive" denotes any
[USB mass storage device][mass-storage]. In addition to smaller flash memory
sticks, this includes things like USB external hard drives.)
Qubes OS supports the ability to attach a USB drive (or just one or more of its
partitions) to any qube easily, no matter which qube actually handles the USB
controller. (The USB controller may be assigned on the **Devices** tab of a
qube's settings page in Qubes VM Manager or by using the
[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
controller, see [here][usb-controller].)
controller.
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
your USB drive, right-click on the desired qube in the Qubes VM Manager list,
click **Attach/detach block devices**, and select your desired action and
device. This, however, only works for the whole device. If you would like to
attach individual partitions, you must use the command-line tool.
### R4.0 ###
USB drive mounting is integrated into the Devices Widget. This is the tool tray
icon with a yellow square located in the top right of your screen by default.
Simply insert
your USB drive and click on the widget. You will see multiple entries for your
USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
The simplest (but slightly less secure, see note below about attaching individual
partitions) option is to attach the entire block drive. In our example, this is `sda`,
so hover over it.
This will pop up a submenu showing running VMs to which the USB drive can be connected.
Click on one and your USB drive will be attached!
Note that attaching individual partitions can be slightly more secure because it doesn't
force the target AppVM to parse the partition table. However, it often means the
AppVM won't detect the new partition and you will need to manually mount it inside
the AppVM. See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
follows:
@ -230,7 +185,7 @@ follows:
2. In a dom0 console (running as a normal user), list all available block
devices:
qvm-block -l
qvm-block
This will list all available block devices connected to any USB controller
in your system, no matter which qube hosts the controller. The name of the
@ -243,14 +198,14 @@ follows:
usbVM:sdb1 Disk () 2GiB
**Note:** If your device is not listed here, you may refresh the list by
calling (from the qube to which the device is connected):
calling from the qube to which the device is connected (typically `sys-usb`):
sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to dom0 and is `sdb`, we attach the
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
device to a qube with the name `personal` like so:
qvm-block -a personal dom0:sdb
qvm-block attach personal sys-usb:sdb
This will attach the device to the qube as `/dev/xvdi` if that name is not
already taken by another attached device, or `/dev/xvdj`, etc.
@ -258,6 +213,78 @@ follows:
You may also mount one partition at a time by using the same command with
the partition number after `sdb`.
4. The USB drive is now attached to the qube. If using a default qube, you may
open the Nautilus file manager in the qube, and your drive should be
visible in the **Devices** panel on the left. If you've attached a single
partition, you may need to manually mount before it becomes visible:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
5. When you finish using your USB drive, click the eject button or right-click
and select **Unmount**. If you've manually mounted a single partition
in the above step, use:
`sudo umount mnt`
6. In a dom0 console, detach the stick
qvm-block detach <vmname> <device>
7. You may now remove the device.
### R3.2 ###
USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert
your USB drive, right-click on the desired qube in the Qubes VM Manager list,
click **Attach/detach block devices**, and select your desired action and
device. This, however, only works for the whole device. If you would like to
attach individual partitions, you must use the command-line tool.
Note that attaching individual partitions can be slightly more secure because it doesn't
force the target AppVM to parse the partition table. However, it often means the
AppVM won't detect the new partition and you will need to manually mount it inside
the AppVM. See below for more detailed steps.
The command-line tool you may use to mount whole USB drives or their partitions
is `qvm-block`. This tool can be used to assign a USB drive to a qube as
follows:
1. Insert your USB drive.
2. In a dom0 console (running as a normal user), list all available block
devices:
qvm-block
This will list all available block devices connected to any USB controller
in your system, no matter which qube hosts the controller. The name of the
qube 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
qube, like so:
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 qube to which the device is connected (typically `sys-usb`):
sudo udevadm trigger --action=change
3. Assuming your USB drive is attached to `sys-usb` and is `sdb`, we attach the
device to a qube with the name `personal` like so:
qvm-block -a personal sys-usb:sdb
This will attach the device to the qube as `/dev/xvdi` if that name is 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`. This is slightly more secure because it
does not force the target AppVM to parse the partition table.
**Warning:** when working with single partitions, it is possible to assign
the same partition to multiple qubes. For example, you could attach `sdb1`
to qube1 and then `sdb` to qube2. It is up to the user not to make this
@ -267,10 +294,18 @@ follows:
4. The USB drive is now attached to the qube. If using a default qube, you may
open the Nautilus file manager in the qube, and your drive should be
visible in the **Devices** panel on the left.
visible in the **Devices** panel on the left. If you've attached a single
partition, you may need to manually mount before it becomes visible:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
5. When you finish using your USB drive, click the eject button or right-click
and select **Unmount**.
and select **Unmount**. If you've manually mounted a single partition
in the above step, use:
`sudo umount mnt`
6. In a dom0 console, detach the stick
@ -291,7 +326,7 @@ 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).
### What if I removed the device before detaching it from the VM? ###
### What if I removed the device before detaching it from the VM? (R3.2) ###
Currently (until issue [1082] gets implemented), if you remove the device
before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will
@ -310,7 +345,7 @@ steps:
[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
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
In above example, all `xl block-attach` parameters can be deduced from the
output of `qvm-block`. In order:
@ -319,7 +354,7 @@ steps:
brackets by `qvm-block` command
* `phy:/dev/sda` - physical path at which device appears in source qube
(just after source qube name in `qvm-block` output)
* `backend=sys-usb` - name of source qube, can be omitted in case of dom0
* `backend=sys-usb` - name of source qube, can be omitted in the case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block`
output)
@ -331,10 +366,10 @@ Attaching a single USB device to a qube (USB passthrough)
---------------------------------------------------------
Starting with Qubes 3.2, it is possible to attach a single USB device to any
Qube. While this is useful feature, it should be used with care, because there
Qube. While this is a useful feature, it should be used with care, because there
are [many security implications][usb-challenges] from using USB devices and USB
passthrough will **expose your target qube** for most of them. If possible, use
method specific for particular device type (for example block devices described
a method specific for particular device type (for example block devices described
above), instead of this generic one.
### Installation of qubes-usb-proxy ###
@ -351,7 +386,52 @@ you want to attach the USB device to.
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Usage of qubes-usb-proxy ###
### Usage of qubes-usb-proxy (R4.0) ###
This feature is also available from the Devices Widget. This is the tool tray
icon with a yellow square located in the top right of your screen by default.
Simply insert
your USB device and click on the widget. You will see an entry for your device
such as `sys-usb:2-5 - 058f_USB_2.0_Camera` for example.
Hover over it.
This will pop up a submenu showing running VMs to which the USB device can be connected.
Click on one and your device will be attached! You may also use the command line:
Listing available USB devices:
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Attaching selected USB device:
[user@dom0 ~]$ qvm-usb attach conferences sys-usb:2-5
[user@dom0 ~]$ qvm-usb
conferences:2-1 058f:3822 058f_USB_2.0_Camera
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera (attached to conferences)
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
Now, you can use your USB device (camera in this case) in the `conferences` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead,
please refer to the [Installation Section][installation].
When you finish, detach the device. This can be done in the GUI by
clicking on the Devices Widget. You will see an entry in bold for your device
such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover over it.
This will pop up a submenu showing running VMs. The one which your device is
connected to will have an Eject button next to it. Click that and your device
will be detached. You may also use the command line:
[user@dom0 ~]$ qvm-usb detach conferences sys-usb:2-5
[user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
### Usage of qubes-usb-proxy (R3.2) ###
Listing available USB devices:
@ -381,8 +461,231 @@ When you finish, detach the device:
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
This feature is not yet available in Qubes Manager however, if you would like to contribute to Qubes OS project by implementing it and are a student please consider applying for the [Google Summer of Code][gsoc-page] scholarship and choosing QubesOS Project as a mentor organization. You can find list of our our Project Ideas [here][project-page].
This feature is not available in Qubes Manager.
Creating and Using a USB qube
-----------------------------
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. There are problems with doing this in an encrypted install (LUKS). If you find yourself in this situation, see this [issue][2270-comm23].
Connecting an untrusted USB device to dom0 is a security risk since dom0,
like almost every OS, reads partition tables automatically. The whole
USB stack is put to work to parse the data presented by the USB device in order
to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, it is possible to prepare and utilize a USB qube.
A USB qube acts as a secure handler for potentially malicious USB devices,
preventing them from coming into contact with dom0 (which could otherwise be
fatal to the security of the whole system). With a USB qube, every time you
connect an untrusted USB drive to a USB port managed by that USB controller, you
will have to attach it to the qube in which you wish to use it (if different
from the USB qube itself), either by using Qubes VM Manager or the command line
(see instructions above). The USB controller may be assigned on the **Devices** tab of a
qube's settings page in Qubes VM Manager or by using the
[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB
controller, see [here][usb-controller].
You can create a USB qube using the management stack by performing the following
as root in dom0:
sudo qubesctl state.sls qvm.sys-usb
Alternatively, you can create a USB qube manually as follows:
1. Read the [Assigning Devices] page to learn how to list and identify your
USB controllers. Carefully check whether you have a USB controller that
would be appropriate to assign to a USB qube. Note that it should have no
input devices, programmable devices, and any other devices that must be
directly available to dom0. If you find a free controller, note its name
and proceed to step 2.
2. Create a new qube. Give it an appropriate name and color label
(recommended: `sys-usb`, red). If you need to attach a networking device,
it might make sense to create a NetVM. If not, an AppVM might make more
sense. (The default `sys-usb` is a NetVM.)
3. In the qube's settings, go to the "Devices" tab. Find the USB controller
that you identified in step 1 in the "Available" list. Move it to the
"Selected" list.
**Caution:** By assigning a USB controller to a USB qube, it will no longer
be available to dom0. This can make your system unusable if, for example,
you have only one USB controller, and you are running Qubes off of a USB
drive.
4. Click "OK." Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM
automatically on boot." (This will help to mitigate attacks in which
someone forces your system to reboot, then plugs in a malicious USB
device.)
If the USB qube will not start, see [here][faq-usbvm].
How to hide all USB controllers from dom0
-----------------------------------------
If you create a USB qube manually, there will be a brief period of time during the
boot process during which dom0 will be exposed to your USB controllers (and any
attached devices). This is a potential security risk, since even brief exposure
to a malicious USB device could result in dom0 being compromised. There are two
approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM] device, do not use the second option. Using
a USB AEM device requires dom0 to have access to the USB controller to which
your USB AEM device is attached. If dom0 cannot read your USB AEM device, AEM
will hang.
The procedure to hide all USB controllers from dom0 is as follows:
* GRUB2
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
* EFI
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
2. Find the lines that begin with `kernel=`. There may be more than one.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. Reboot.
(Note: Beginning with R3.2, `rd.qubes.hide_all_usb` is set automatically if you
opt to create a USB qube during installation. This also occurs automatically if
you choose to [create a USB qube] using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning:** A USB keyboard cannot be used to type the disk passphrase
if USB controllers were hidden from dom0. Before hiding USB controllers
make sure your laptop keyboard is not internally connected via USB
(by checking output of `lsusb` command) or that you have a PS/2 keyboard at hand
(if using a desktop PC). Failure to do so will render your system unusable.
Removing a USB qube
-------------------
**Warning:** This procedure will result in your USB controller(s) being attached
directly to dom0.
* GRUB2
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.
Security Warning about USB Input Devices
----------------------------------------
**Important security warning. Please read this section carefully!**
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a USB qube are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer.
You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer.
This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube.
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
How to use a USB keyboard
-------------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
### R4.0, using salt ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates][dom0-updates]) and execute in dom0:
sudo qubesctl state.sls qvm.usb-keyboard
The above command will take care of all required configuration, including creating USB qube if not present.
Note that it will expose dom0 to USB devices while entering LUKS passphrase.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
If you wish to perform only subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
### R3.2, manual ###
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputKeyboard
Add a line like this one to the top of the file:
sys-usb dom0 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard.
For a confirmation dialog each time the USB keyboard is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0][How to hide all USB controllers from dom0].
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
How to use a USB mouse
----------------------
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
In order to use a USB mouse, you must first attach it to a USB qube, then give that
qube permission to pass mouse input to dom0.
The following steps are already done by default if you created the sys-usb qube with
`qubesctl state.sls qvm.sys-usb` above, or let Qubes create it for you on first boot. However,
if you've created the USB qube manually:
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputMouse
Add a line like this to the top of the file:
sys-usb dom0 allow,user=root
(Change `sys-usb` to your desired USB qube.)
You can now use your USB mouse.
For a confirmation dialog each time the USB mouse is connected, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[Assigning Devices]: /doc/assigning-devices/
@ -398,8 +701,8 @@ This feature is not yet available in Qubes Manager however, if you would like to
[1618]: https://github.com/QubesOS/qubes-issues/issues/1618
[create a USB qube]: #creating-and-using-a-usb-qube
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[project-page]: /gsoc/
[gsoc-page]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[YubiKey]: /doc/YubiKey/
[Security Warning about USB Input Devices]: #security-warning-about-usb-input-devices
[How to hide all USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
[qubes-usb-proxy]: https://github.com/QubesOS/qubes-app-linux-usb-proxy
[dom0-updates]: /doc/software-update-dom0/#how-to-update-software-in-dom0