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

Update and reorganize documentation

Browse source 
- Convert "Common Tasks" to "How-to Guides"
  (QubesOS/qubes-issues#6694)
- Make title capitalization consistent across docs
- Fix leftover h1 headings
- Reorganize various pages and topics
- Update permalinks to better match titles
- Create redirects for changed permalinks
- Miscellaneous cleanup

QubesOS/qubes-issues#6701
This commit is contained in:
Andrew David Wong 2021-06-17 04:23:57 -07:00
parent 12408884dd
commit 6d81f95cc2
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
73 changed files with 101 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

126
user/how-to-guides/backup-emergency-restore-v2.md Normal file
View file

@ -0,0 +1,126 @@
---
lang: en
layout: doc
permalink: /doc/backup-emergency-restore-v2/
redirect_from:
- /en/doc/backup-emergency-restore-v2/
- /doc/BackupEmergencyRestoreV2/
ref: 207
title: Emergency Backup Recovery (v2)
---
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
~~~
2. 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`.
3. 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:
~~~
find -name 'private.img.*' | sort -V | while read f; 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`.
4. 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.
5. 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.)
6. 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 on [Github](https://github.com/QubesOS/qubes-doc.git)

139
user/how-to-guides/backup-emergency-restore-v3.md Normal file
View file

@ -0,0 +1,139 @@
---
lang: en
layout: doc
permalink: /doc/backup-emergency-restore-v3/
redirect_from:
- /en/doc/backup-emergency-restore-v3/
- /doc/BackupEmergencyRestoreV3/
ref: 201
title: Emergency Backup Recovery (v3)
---
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/backup-emergency-restore-v2/) 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]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | 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). For example, if you
used `bzip2`, then you should do this:
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
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

180
user/how-to-guides/backup-emergency-restore-v4.md Normal file
View file

@ -0,0 +1,180 @@
---
lang: en
layout: doc
permalink: /doc/backup-emergency-restore-v4/
redirect_from:
- /en/doc/backup-emergency-restore-v4/
- /doc/BackupEmergencyRestoreV4/
ref: 192
title: Emergency Backup Recovery (v4)
---
This page describes how to perform an emergency restore of a backup created on
Qubes R4.X (which uses backup format version 4).
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt](https://www.tarsnap.com/scrypt.html). You
will need a copy of this utility in order to access your data. Since `scrypt`
is not pre-installed on every GNU/Linux system, it is strongly recommended that
you store a copy of it with your backups. If your distribution has `scrypt`
packaged (e.g., Debian), you can install the package in the standard way using
your distribution's package manager. Otherwise, you'll need to obtain a
compiled binary (instructions below) or compile the program from source
yourself. (Don't forget to [verify signatures](/security/verifying-signatures) first!) Note that versions of
`scrypt` up to 1.2.0 (inclusive) do not support the `-P` option for easier
scripting, which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key](/security/verifying-signatures/#2-get-the-release-signing-key).
2. If you're not on Qubes 4.X, import the Release 4 Signing Key.
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
3. Download the `scrypt` RPM.
[user@restore ~]$ dnf download scrypt
or, if that doesn't work:
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
4. Verify the signature on the `scrypt` RPM.
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
The message `digests signatures OK` means that both the digest (i.e., the
output of a hash function) and PGP signature verification were successful.
5. Install `rpmdevtools`.
[user@restore ~]$ sudo dnf install rpmdevtools
6. Extract the `scrypt` binary from the RPM.
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
7. (Optional) Create an alias for the new binary.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
Emergency Recovery Instructions
-------------------------------
**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.enc
vm1/private.img.000.enc
vm1/private.img.001.enc
vm1/private.img.002.enc
vm1/icon.png.000.enc
vm1/firewall.xml.000.enc
vm1/whitelisted-appmenus.list.000.enc
dom0-home/dom0user.000.enc
**To extract only specific VMs:** Each VM in the backup file has its path
listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
`password`.)
[user@restore ~]$ cat backup-header | grep backup-id
backup-id=20190128T123456-1234
[user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
[user@restore ~]$ tar -i -xvf qubes.xml.000
Now that you have the decrypted `qubes.xml.000` file, search for the
`backup-path` property inside of it. With the `backup-path`, extract only
the files necessary for your VM (`vmX`).
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
backup-header backup-header.hmac vmX/
2. Set the backup passphrase environment variable. While this isn't strictly
required, it will be handy later and will avoid saving the passphrase in
the shell's history.
[user@restore ~]$ read backup_pass
3. Verify the integrity of `backup-header`. For compatibility reasons,
`backup-header.hmac` is an encrypted *and integrity protected*
version of `backup-header`.
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
scrypt dec -P backup-header.hmac backup-header.verified && \
diff -qs backup-header backup-header.verified
Files backup-header and backup-header.verified are identical
**Note:** If this command fails, it may be that the backup was tampered
with or is in a different format. In the latter case, look inside
`backup-header` at the `version` field. If it contains a value other than
`version=4`, go to the instructions for that format version:
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
4. Read `backup-header`:
[user@restore ~]$ cat backup-header
version=4
encrypted=True
compressed=True
compression-filter=gzip
backup_id=20161020T123455-1234
5. Set `backup_id` to the value in the last line of `backup-header`:
[user@restore ~]$ backup_id=20161020T123455-1234
6. Verify the integrity of your data, decrypt, decompress, and extract `private.img`:
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
done | gzip -d | tar -xv
vm1/private.img
If this pipeline fails, it is likely that the backup is corrupted or has
been tampered with.
**Note:** If your backup was compressed with a program other than `gzip`,
you must substitute the correct compression program in the command above.
This information is contained in `backup-header` (see step 4). For example,
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
command above.
7. Mount `private.img` 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!
8. Success! If you wish to recover data from more than one VM in your backup,
simply repeat steps 6 and 7 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

170
user/how-to-guides/how-to-back-up-restore-and-migrate.md Normal file
View file

@ -0,0 +1,170 @@
---
lang: en
layout: doc
permalink: /doc/how-to-back-up-restore-and-migrate/
redirect_from:
- /doc/backup-restore/
- /en/doc/backup-restore/
- /doc/BackupRestore/
- /wiki/BackupRestore/
ref: 199
title: How to Back Up, Restore, and Migrate
---
With Qubes, it's easy and secure to back up and restore your whole system, as well as to migrate between two physical machines.
These functions are integrated into the Qube Manager.
There are also two command-line tools available that perform the same functions: `qvm-backup` and `qvm-backup-restore`.
It's extremely important to make regular backups of all the data you care about.
This is true of all computing, not just the use of Qubes.
Data loss can and does occur in myriad and unexpected ways.
A standard recommendation is to make backups at least weekly: three copies in two different formats, one off-site.
Backing up changes to dom0
--------------------------
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up.
Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup.
Here is an example of how to back up Qubes config files and RPC policies:
```
$ mkdir -p ~/backup/etc/qubes/
$ cp -a /etc/qubes/* ~/backup/etc/qubes/
$ mkdir ~/backup/etc/qubes-rpc/
$ cp -a /etc/qubes-rpc/* ~/systemfiles/etc/qubes-rpc/
```
To restore these files, move them from the restored directory in dom0's home back to their appropriate locations in `/etc/`.
Please note that any packages installed via the package manager in dom0 will not be backed up.
Such packages will have to be reinstalled through the package manager when restoring on a fresh installation.
Creating a backup
-----------------
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.
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**.
6. Test restore your backup.
Follow the [restore procedure](#restoring-from-a-backup), selecting **Verify backup integrity, do not restore the data**.
This step is optional but strongly recommended.
A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
Restoring from a backup
-----------------------
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/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 it or select it and hit **OK**.
3. There are three options you may select when restoring from a 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.
**Note:** The passphrase which was supplied when the backup was created is 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.
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**.
**Note:** When restoring from a dom0 backup, a new directory will be created in the current dom0 home directory, and the contents from the backup will be placed inside this new directory.
This is intentional, as it allows users to have explicit control over which files and settings get applied in dom0.
If the contents from the dom0 backup were instead to overwrite the existing files in dom0's home directory, unexpected and undesired configuration changes could occur.
However, if you do wish to move all files from the dom0 backup out of the subdirectory into your current dom0 home directory (overwriting any existing files in the process), you may do so by following the instructions [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
Just remember that this can cause unexpected and desired configuration changes in dom0, depending on exactly which files you're adding and replacing.
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.
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!
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 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
-----
- 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).

66
user/how-to-guides/how-to-copy-and-move-files.md Normal file
View file

@ -0,0 +1,66 @@
---
lang: en
layout: doc
permalink: /doc/how-to-copy-and-move-files/
redirect_from:
- /doc/copying-files/
- /en/doc/copying-files/
- /doc/CopyingFiles/
- /wiki/CopyingFiles/
ref: 191
title: How to Copy and Move Files
---
*This page is about copying and moving files.
If you wish to simply copy and paste text, that can be done more easily using the inter-qube clipboard.
See [copying and pasting text between qubes](/doc/copy-paste/).
For dom0, see [copying from (and to) dom0](/doc/copy-from-dom0/).*
Qubes OS supports the secure copying and moving of files and directories (folders) between qubes.
For simplicity, these instructions will refer to copying/moving a single file, but they apply equally well to groups of files and directories, which are copied recursively.
1. Open a file manager in the qube containing the file you wish to copy (the source qube), right-click on the file you wish to copy or move, and select `Copy to Other AppVM...` or `Move to Other AppVM...`.
2. A dialog box will appear in dom0 asking for the name of the target qube (qube B).
Enter or select the desired destination qube name.
3. If the target qube is not already running, it will be started automatically, and the file will be copied there.
It will show up in this directory (which will automatically be created if it does not already exist):
/home/user/QubesIncoming/<source_qube>/<filename>
If you selected **Move** rather than **Copy**, the original file in the source qube will be deleted.
(Moving a file is equivalent to copying the file, then deleting the original.)
4. If you wish, you may now move the file in the target qube to a different directory and delete the `/home/user/QubesIncoming/` directory when no longer needed.
The same operations are also available via these command-line tools:
```
qvm-copy [--without-progress] file [file]+
```
```
qvm-move [--without-progress] file [file]+
```
Security
--------
The inter-qube file copy system is secure because it doesn't allow other qubes to steal the files that are being copied, and it doesn't allow the source qube to overwrite arbitrary files on the destination qube.
Moreover, this system doesn't use any sort of virtual block device for file copy.
Instead, we use Xen shared memory, which eliminates a lot of processing of untrusted data.
For example, the receiving qube is *not* forced to parse untrusted partitions or file systems.
In this respect, the inter-qube file copy system provides even more security than file copy between two physically separated (air-gapped) machines!
(See [Software compartmentalization vs. physical separation](https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf) for more on this.)
However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes is always potentially insecure if the data will be parsed in the target qube.
This is because the data that we copy could try to exploit some hypothetical bug in software running in the target qube.
For example, a seemingly-innocent JPEG that we copy from an untrusted qube might contain a specially-crafted exploit for a bug in a JPEG-parsing application in the target qube.
This is a general problem and applies to any data transfer from *less trusted* to *more trusted* qubes.
It even applies to the scenario of copying files between air-gapped machines.
Therefore, you should always copy data only from *more trusted* to *less trusted* qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/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.

88
user/how-to-guides/how-to-copy-and-paste-text.md Normal file
View file

@ -0,0 +1,88 @@
---
lang: en
layout: doc
permalink: /doc/how-to-copy-and-paste-text/
redirect_from:
- /doc/copy-paste/
- /en/doc/copy-paste/
- /doc/CopyPaste/
- /wiki/CopyPaste/
ref: 196
title: How to Copy and Paste Text
---
*This page is about copying and pasting plain text.
If you wish to copy more complex data, such as rich text or images, see [copying and moving files between qubes](/doc/copying-files/).
For dom0, see [copying from (and to) dom0](/doc/copy-from-dom0/).*
Qubes OS features a secure inter-qube clipboard that allows you to copy and paste text between qubes.
In order to copy text from qube A to qube B:
1. Select text from the source app in qube A, then copy it normally (e.g., by pressing Ctrl+C).
2. With the source app in qube A still in focus, press Ctrl+Shift+C.
This copies the text from qube A's clipboard to the inter-qube clipboard.
3. Select the target app in qube B and press Ctrl+Shift+V.
This copies the text from the inter-qube clipboard to qube B's clipboard and clears the inter-qube clipboard, ensuring that only qube B will have access to the copied text.
4. Paste the text in the target app in qube B normally (e.g., by pressing Ctrl+V).
This process might look complicated at first glance, but in practice it is actually very easy and fast once you get used to it.
At the same time, it provides you with full control over exactly which qube receives the content of the inter-qube clipboard every time.
Security
--------
The inter-qube clipboard system is secure because it doesn't allow any qube other than your selected target to steal any contents from the inter-qube clipboard.
Without such a system in place, any password you were to copy from the password manager in your vault qube to another qube, for example, would immediately be leaked to every other running qube in the system, including qubes that are untrusted by default, such as `sys-net`.
By giving you precise control over exactly which qube receives the inter-qube clipboard content, then immediately wiping the inter-qube clipboard afterward, Qubes OS protects the confidentiality of the text being copied.
However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* qube is always potentially insecure, since the data that we copy could exploit some hypothetical bug in the target qube.
For example, the seemingly-innocent link that we copy from an untrusted qube could turn out to be a large buffer of junk that, when pasted into the target qube's word processor, could exploit a hypothetical bug in the undo buffer.
This is a general problem and applies to any data transfer from *less trusted* to *more trusted* qubes.
It even applies to copying files between physically separate (air-gapped) machines.
Therefore, you should always copy clipboard data only from *more trusted* to *less trusted* qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/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, as well as [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06e01) from qubes-devel.
### Focus stealing
The above discussion assumes that you control which window is focused in dom0 at the time of the paste.
However, if your dom0 window manager is configured to give focus to newly created windows (which, as of Qubes 4.0, is true in the default install with Xfce), then a malicious qube could "steal the focus" by creating a window just before you press Ctrl+Shift+V, and it would receive the data instead of your intended target.
(Focus stealing is a risk any time you are typing confidential data, but a Qubes clipboard paste probably presents the greatest risk of leaking an entire password before you have time to react.)
You may be able to mitigate this risk by changing the window manager configuration.
For example, with Xfce, you could run `xfwm4-settings` in dom0, go to the "Focus" tab, and un-check "Automatically give focus to newly created windows".
However, we have not confirmed whether such settings are sufficient to prevent a malicious qube from stealing the focus in all cases.
Clipboard automatic policy enforcement
--------------------------------------
The Qubes clipboard [RPC policy](/doc/rpc-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
~~~
If you edit a line in this file, you must uncomment it (by removing the initial `#` character), or else it will have no effect.
VMs need to be restarted in order for changes in `/etc/qubes/guid.conf` to take effect.

86
user/how-to-guides/how-to-copy-from-dom0.md Normal file
View file

@ -0,0 +1,86 @@
---
lang: en
layout: doc
permalink: /doc/how-to-copy-from-dom0/
redirect_from:
- /doc/copy-from-dom0/
- /doc/copy-to-dom0/
- /en/doc/copy-to-dom0/
- /doc/CopyToDomZero/
- /wiki/CopyToDomZero/
ref: 198
title: How to Copy from Dom0
---
This page covers copying files and clipboard text between [dom0](/doc/glossary/#dom0) and [domUs](/doc/glossary/#domu).
Since dom0 is special, the processes are different from [copying and pasting text between qubes](/doc/copy-paste/) and [copying and moving files between qubes](/doc/copying-files/).
## Copying **from** dom0
### Copying files from dom0
To copy a file from dom0 to a VM, simply use `qvm-copy-to-vm`:
```
qvm-copy-to-vm <target_vm> <file>
```
The file will arrive in the target VM in the `/home/user/QubesIncoming/dom0/` directory.
### Copying and pasting clipboard text from dom0
Use the **Qubes Clipboard** widget:
1. Copy text to the clipboard normally in dom0 (e.g., by pressing Ctrl+C).
2. Click the **Qubes Clipboard** icon in the Notification Area.
3. Click "Copy dom0 clipboard".
This displays a notification that text has been copied to the inter-qube clipboard.
4. Press Ctrl+Shift+V in the target qube.
This pastes the inter-qube clipboard contents into the target qube's normal clipboard.
5. Paste normally within that qube (e.g., by pressing Shift+V).
Alternatively, you can put your text in a file, then [copy it as a file](#copying-files-from-dom0).
Or, you can write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`.
Then use Ctrl+Shift+V to paste the data to the target qube.
### Copying logs from dom0
In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply:
1. Right-click on the desired qube in the Qube Manager.
2. Click "Logs."
3. Click on the desired log.
4. Click "Copy to Qubes clipboard."
You may now paste the log contents in qube as you normally would (e.g., Ctrl+Shift+V, then Ctrl+V).
## Copying **to** dom0
Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system.
For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0).
There should normally be few reasons for the user to want to copy anything from domUs to dom0, as dom0 only acts as a "thin trusted terminal", and no user applications run there.
Sometimes, new users feel the urge to copy a desktop wallpaper image into dom0, but that is not necessary.
A safer approach is simply to display the image in [full-screen mode](/doc/full-screen-mode/) in an AppVM, then take a screenshot from dom0, which results in exactly the image needed for a wallpaper, created securely and natively in dom0.
If you are determined to copy some files to dom0 anyway, you can use the following method.
(If you want to copy text, first save it into a text file.)
Run this command in a dom0 terminal:
```
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
```
Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
```
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'
```

73
user/how-to-guides/how-to-enter-fullscreen-mode.md Normal file
View file

@ -0,0 +1,73 @@
---
lang: en
layout: doc
permalink: /doc/how-to-enter-fullscreen-mode/
redirect_from:
- /doc/full-screen-mode/
- /en/doc/full-screen-mode/
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
ref: 205
title: How to Enter Fullscreen Mode
---
What is fullscreen mode?
-------------------------
Normally, the 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/) page for examples.
Why is fullscreen 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 know if the applications/VM really "released" the full screen, or if it has started emulating the whole desktop and is pretending 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 fullscreen mode
------------------------------
However, it is possible to deal with fullscreen mode in a secure way assuming there are mechanisms that can be used at any time to switch between windows or show the full desktop and that cannot be intercepted by the VM.
The simplest example is the use of Alt+Tab for switching between windows, which is a shortcut handled by dom0.
Other examples such mechanisms are the KDE "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 fullscreen mode for select VMs
----------------------------------------
You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen" or pressing `alt` + `f11`.
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen" or simply press `alt` + `f11`.
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.
As an alternative to the Xfce4 method, you can enable fullscreen mode for select VMs by creating the following entry in the `/etc/qubes/guid.conf` file in dom0:
~~~
VM: {
personal: {
allow_fullscreen = true;
};
};
~~~
The string 'personal' above is an example only and should be replaced by the actual name of the VM for which you want to enable this functionality.
**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)).
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.

187
user/how-to-guides/how-to-get-started.md Normal file
View file

@ -0,0 +1,187 @@
---
lang: en
layout: doc
permalink: /doc/how-to-get-started/
redirect_from:
- /doc/getting-started/
- /getting-started/
- /en/doc/getting-started/
- /doc/GettingStarted/
- /wiki/GettingStarted/
ref: 190
title: How to Get Started
---
After [downloading](/downloads/) and [installing](/doc/installation-guide/) Qubes OS, let's cover some basic concepts.
Introduction
------------
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)](/doc/glossary/#vm) called [qubes](/doc/glossary/#qube).
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a [security domain](/doc/glossary/#domain) (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template](/doc/glossary/#templatevm), although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
This is important, as it means that if a qube is ever compromised, the template on which it's based (and any other qubes based on that template) will still be safe.
So, creating a large number of qubes is cheap: each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
If you've installed Qubes OS using the default options, a few qubes have already been created for you:
- work
- personal
- untrusted
- vault
Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors.
The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube.
This is designed to allow you to quickly and easily identify the trust level of a given window at a glance.
Most Qubes OS users associate red with what's untrusted and dangerous (like a red light -- stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle.
This color scheme also extends to include blue and black, which are usually interpreted as indicating progressively more trusted domains than green, with black being ultimately trusted.
However, it's totally up to you how you'd like to interpret these colors.
Qubes OS doesn't assume anything about these colors.
When you make a new qube, the system doesn't do anything special to it depending on whether it's black or red, for example.
The only difference is which color you see and the meaning you assign to that color in your mind.
For example, you could use the colors to show that qubes belong to the same domain.
You might use three or four qubes for work activities and give them all the same distinct color label, for instance.
It's entirely up to you.
![snapshot_40.png](/attachment/wiki/GettingStarted/r4.0-snapshot_40.png)
In addition to qubes and templates, there's one special domain called [dom0](/doc/glossary/#dom0), where many system tools and the desktop manager run.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including templates and black-labeled qubes).
If dom0 were ever compromised, it would be "game over."
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the window and desktop managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).
(That's what your qubes are for!)
GUI and command-line tools
--------------------------
All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal.
Opening a terminal in dom0 can be done in several ways:
- Go to the Application Launcher and click **Terminal Emulator**.
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
- The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage.
- The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes.
- The **Disk Space Widget** will notify you if you're ever running out of disk space.
- The **Updates Widget** will inform you when template updates are available.
![q40_widgets.png](/attachment/wiki/GettingStarted/r4.0-q40_widgets.png)
For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system.
Starting apps
-------------
Apps can be started either by using the shortcuts in the Application Launcher menu or by using the command line (i.e., a terminal running in dom0).
You can start apps directly from the Application Launcher or the Application Finder (`Alt+F3`).
Each qube has its own menu directory under the scheme `Domain: <name>`.
After navigating into one of these directories, simply click on the application you'd like to start:
![menu1.png](/attachment/wiki/GettingStarted/r4.0-menu1.png)
![menu2.png](/attachment/wiki/GettingStarted/r4.0-menu2.png)
By default, each qube's menu contains only a few shortcuts.
If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab.
To start apps from the terminal in dom0, type:
```shell_session
$ qvm-run <qube_name> <app_command> [arguments]
```
e.g.:
```shell_session
$ qvm-run untrusted firefox
```
This command will start the qube if it is not already running.
Adding, removing, and listing qubes
-----------------------------------
You can easily create a new qube with the **Create Qubes VM** option in the Application Launcher.
If you need to add or remove qubes, simply use the Qube Manager's **Add** and **Remove** buttons.
You can also add, remove, and list qubes from the command line using the following tools:
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
How many qubes do I need?
-------------------------
That's a great question, but there's no one-size-fits-all answer.
It depends on the structure of your digital life, and this is at least a little different for everyone.
If you plan on using your system for work, then it also depends on what kind of job you do.
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily [copy](/doc/copying-files/) any files you need to the newly created qube.
Still not sure?
You might find it helpful to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes OS architects partitions her digital life into security domains.
Important tasks
---------------
It's very important to [keep Qubes updated](/doc/updating-qubes-os/) to ensure you have the latest security updates.
Frequently updating is one of the best ways to remain secure against new threats.
It's also very important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system](/doc/backup-restore/) allows you to do this securely and easily.
Here are some other tasks you're likely to want to perform.
(A full list is available in the [Common Tasks](/doc/#common-tasks) section of the documentation.)
- [Copying and Pasting Text Between Domains](/doc/copy-paste/)
- [Copying and Moving Files Between Domains](/doc/copying-files/)
- [Copying from (and to) dom0](/doc/copy-from-dom0/)
- [Fullscreen Mode](/doc/full-screen-mode/)
- [DisposableVMs](/doc/disposablevm/)
- [Device Handling](/doc/device-handling/) (block, USB, and PCI devices)
If you encounter any problems, please visit the [Help, Support, and Mailing Lists](/support/) page.
<hr class="more-top more-bottom">
<div class="row">
<div class="col-lg-4 col-md-4 more-bottom">
<h2>Compatible Hardware</h2>
<p>Make sure your hardware is compatible, as Qubes OS cannot run on every type of computer. Also, check out <a href="/doc/certified-laptops/">Qubes-certified Laptops</a>.</p>
<a href="/hcl/" class="btn btn-primary">
<i class="fa fa-laptop"></i> Hardware Compatibility List
</a>
</div>
<div class="col-lg-4 col-md-4 more-bottom">
<h2>Downloads</h2>
<p>Download an ISO, learn how to verify its authenticity and integrity, and follow our guides to install Qubes OS. Looking for the source code? You'll find it on <a href="https://github.com/QubesOS">GitHub</a>.</p>
<a href="/downloads/" class="btn btn-primary">
<i class="fa fa-download"></i> Downloads
</a>
</div>
<div class="col-lg-4 col-md-4">
<h2>Documentation</h2>
<p>Peruse our extensive library of documentation for users and developers of Qubes OS. You can even help us <a href="/doc/doc-guidelines/">improve</a> it!</p>
<a href="/doc/" class="btn btn-primary">
<i class="fa fa-book"></i> Documentation
</a>
</div>
</div>

297
user/how-to-guides/how-to-install-software.md Normal file
View file

@ -0,0 +1,297 @@
---
lang: en
layout: doc
permalink: /doc/how-to-install-software/
redirect_from:
- /doc/software-update-domu/
- /doc/software-update-vm/
- /en/doc/software-update-vm/
- /doc/SoftwareUpdateVM/
- /wiki/SoftwareUpdateVM/
ref: 189
title: How to Install Software
---
This page explains how to install software in TemplateVMs and StandaloneVMs.
Advanced users may also be interested in learning [how to install software in dom0](/doc/how-to-install-software-in-dom0).
## Installing software in TemplateVMs
To permanently install new software in a TemplateVM:
1. Start the TemplateVM.
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs](/doc/glossary/#templatebasedvm) based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs](/doc/glossary/#templatebasedvm)' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
These new shortcuts will appear in the Applications Menu.
(If you encounter problems, see [here](/doc/managing-appvm-shortcuts/) for troubleshooting.)
![[The Applications tab in Qube Settings](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)
## Updating software in TemplateVMs
See [Updating Qubes OS](/doc/updating-qubes-os/).
## Testing repositories
If you wish to install updates that are still in [testing](/doc/testing), you must enable the appropriate testing repositories.
### Fedora
There are three Qubes VM testing repositories (where `*` denotes the Release):
- `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository
- `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes
- `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
Example commands:
~~~
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
~~~
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-*.repo`.
### Debian
Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
- `*-testing` -- testing packages that will eventually land in the stable (`current`) repository
- `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes
- `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages
To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`.
## Contributed package repository
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## StandaloneVMs
When you create a [StandaloneVM](/doc/standalone-and-hvm/) from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
After the moment of creation, the StandaloneVM is completely independent from the TemplateVM.
Therefore, it will not be updated when the TemplateVM is updated.
Rather, it must be updated individually.
The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs.
## Advanced
The following sections cover advanced topics pertaining to installing and updating software in domUs.
### RPMFusion for Fedora TemplateVMs
If you would like to enable the [RPM Fusion](https://rpmfusion.org/) repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion](https://rpmfusion.org/) for details):
~~~
sudo dnf config-manager --set-enabled rpmfusion-free
sudo dnf config-manager --set-enabled rpmfusion-free-updates
sudo dnf config-manager --set-enabled rpmfusion-nonfree
sudo dnf config-manager --set-enabled rpmfusion-nonfree-updates
sudo dnf upgrade --refresh
~~~
This will permanently enable the RPM Fusion repos.
If you install software from here, it's important to keep these repos enabled so that you can receiving future updates.
If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them.
### Reverting changes to a TemplateVM
Perhaps you've just updated your TemplateVM, and the update broke your template.
Or perhaps you've made a terrible mistake, like accidentally confirming the installation of an unsigned package that could be malicious.
If you want to undo changes to a TemplateVM, there are three basic methods:
1. **Root revert.**
This is appropriate for misconfigurations, but not for security concerns.
It will preserve your customizations.
2. **Reinstall the template.**
This is appropriate for both misconfigurations and security concerns, but you will lose all customizations.
3. **Full revert.**
This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations.
However, it is a bit more complex.
#### Root revert
**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
This means that if you have already restarted the TemplateVM, using this command is unlikely to help, and you'll likely want to reinstall it from the repository instead.
On the other hand, if the template is already broken or compromised, it won't hurt to try reverting first.
Just make sure to **back up** all of your data and changes first!
1. Shut down `<template>`.
If you've already just shut it down, do **not** start it again (see above).
2. In a dom0 terminal:
```
qvm-volume revert <template>:root
```
#### Reinstall the template
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
#### Full revert
This is like the simple revert, except:
- You must also revert the private volume with `qvm-volume revert <template>:private`.
This requires you to have an old revision of the private volume, which does not exist with the current default config.
However, if you don't have anything important in the private volume (likely for a TemplateVM), then you can work around this by just resetting the private volume with `qvm-volume import --no-resize <template>:private /dev/null`.
- The saved revision of the volumes must be uncompromised.
With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action.
### Temporarily allowing networking for software installation
Some third-party applications cannot be installed using the standard 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 from package managers.
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 allows access only from package managers.
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).
There are two services (`qvm-service`, [service framework](/doc/qubes-service/)):
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
Both the old and new names work.
The defaults listed above are applied if the service is not explicitly listed in the services tab.
#### Technical details
The updates proxy uses RPC/qrexec.
The proxy is configured in qrexec policy in dom0: `/etc/qubes-rpc/policy/qubes.UpdatesProxy`.
By default this is set to 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):
```shell_session
# 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
@tag:whonix-updatevm @default allow,target=sys-whonix
@tag:whonix-updatevm @anyvm deny
# other templates use sys-net
@type:TemplateVM @default allow,target=sys-net
@anyvm @anyvm deny
```
### Installing Snap Packages
Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an AppVM you need to take the following steps:
1. In the **TemplateVM** you must install `snapd` and `qubes-snapd-helper`. Open a terminal in the TemplateVM and run:
```shell_session
[user@fedora-30-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:55:39 ago on Thu Nov 14 09:26:47 2019.
Dependencies resolved.
========================================================================================================
Package Arch Version Repository Size
========================================================================================================
Installing:
snapd x86_64 2.42.1-1.fc30 updates 17 M
qubes-snapd-helper noarch 1.0.1-1.fc30 qubes-vm-r4.0-current 10 k
Installing dependencies:
[...]
Transaction Summary
========================================================================================================
Install 20 Packages
Total download size: 37 M
Installed size: 121 M
Is this ok [y/N]: y
Downloading Packages:
[..]
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed!
[...]
Last metadata expiration check: 0:57:08 ago on Thu Nov 14 09:26:47 2019.
Notifying dom0 about installed applications
Installed:
snapd-2.42.1-1.fc30.x86_64 qubes-snapd-helper-1.0.1-1.fc30.noarch
[...]
Complete!
```
You may see the following message:
```
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed!
```
This is expected and you can safely continue.
Shutdown the TemplateVM:
```shell_session
[user@fedora-30-snap-demo ~]$ sudo shutdown -h now
```
2. Now open the **AppVM** in which you would like to install the Snap application and run a terminal:
```shell_session
[user@snap-demo-AppVM ~]$ snap install <package>
```
When the install is complete you can close the terminal window.
3. Refresh the Applications list for the AppVM.
In the Qubes Menu for the **AppVM*** launch the Qube Settings.
Then go to the Applications tab and click "Refresh Applications"
The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running.
### Autostarting Installed Applications
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
1. Open a terminal in the **AppVM** where you would like the app to launch.
2. List the names of the available desktop shortcuts by running the command `ls /usr/share/applications` and find the exact name of the shortcut to the app you want to autostart:
```shell_session
[user@example-AppVM ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop
eog.desktop
firefox.desktop
...
xterm.desktop
yelp.desktop
```
3. Create the autostart directory:
```
[user@example-AppVM ~]$ mkdir -p ~/.config/autostart
```
4. Make a link to the desktop app file you'd like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
```
[user@example-AppVM ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
```
Note that the app will autostart only when the AppVM starts. If you would like the AppVM to autostart, select the "Start qube automatically on boot" checkbox in the AppVM's Qube Settings.

74
user/how-to-guides/how-to-update.md Normal file
View file

@ -0,0 +1,74 @@
---
lang: en
layout: doc
permalink: /doc/how-to-update/
redirect_from:
- /doc/updating-qubes-os/
ref: 200
title: How to Update
---
*This page is about updating your system while staying on the same [supported version of Qubes OS](/doc/supported-versions/#qubes-os).
If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see the [Upgrade Guides](/doc/upgrade/).*
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures.
Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below.
(By contrast, <a href="/doc/software-update-domu/#installing-software-in-templatevms">installing</a> packages using direct package manager commands is fine.)
</div>
## Security updates
Security updates are an extremely important part of keeping your Qubes installation secure.
When there is an important security issue, we will issue a [Qubes Security Bulletin (QSB)](/security/bulletins/) via the [Qubes Security Pack (`qubes-secpack`)](/security/pack/).
It is very important to read each new QSB and follow any user instructions it contains.
Most of the time, simply [updating your system normally](#routine-updates) will be sufficient to obtain security updates.
However, in some cases, special action may be required on your part, which will be explained in the QSB.
## Routine updates
It is important to keep your Qubes OS system up-to-date to ensure you have the latest [security updates](#security-updates), as well as the latest non-security enhancements and bug fixes.
Fully updating your Qubes OS system means updating:
- [Dom0](/doc/software-update-dom0/)
- [TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms)
- [StandaloneVMs](/doc/software-update-domu/#standalonevms) (if you have any)
You can accomplish this using the **Qubes Update** tool.
[![Qubes Update](/attachment/wiki/QubesScreenshots/r4.0-software-update.png)](/attachment/wiki/QubesScreenshots/r4.0-software-update.png)
By default, the Qubes Update tool will appear as an icon in the Notification Area when updates are available.
[![Qube Updates Available](/attachment/wiki/QubesScreenshots/r4.0-qube-updates-available.png)](/attachment/wiki/QubesScreenshots/r4.0-qube-updates-available.png)
However, you can also start the tool manually by selecting it in the Applications Menu under "System Tools."
Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting "Enable updates for qubes without known available updates," then selecting all desired items from the list and clicking "Next."
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Advanced users and developers:</b> For the command-line equivalents of using the <b>Qubes Update</b> tool, see the Salt formulae <a href="/doc/salt/#updatequbes-dom0"><code>update.qubes-dom0</code></a> and <a href="/doc/salt/#updatequbes-vm"><code>update.qubes-vm</code></a>. For enabling testing repos, see <a href="/doc/testing/">Testing new releases and updates</a>.
</div>
## Upgrading to stay on a supported release
The above covers updating *within* a given operating system release.
Eventually, however, most operating system releases will reach [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life), after which point they will no longer be supported.
This applies to [Qubes OS itself](/doc/supported-versions/#qubes-os) as well as operating systems used for TemplateVMs and StandaloneVMs, such as [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/).
It is very important to use only supported releases, since generally only supported releases receive security updates.
This means that you must periodically upgrade to a newer release before your current release reaches EOL.
In the case of Qubes OS itself, we will always [announce](/news/categories/#releases) when a given Qubes OS release is approaching and has reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
Again, you can always see the current support status for all Qubes OS releases [here](/doc/supported-versions/#qubes-os).
Periodic upgrades are also important for TemplateVMs and StandaloneVMs.
For example, you might be using a [Fedora TemplateVM](/doc/templates/fedora/).
The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project.
They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL.
You can always find out when an operating system reaches EOL from the upstream project that maintains it, but we also make EOL [announcements](/news/categories/#announcements) and publish guides for official TemplateVM operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides](/doc/templates/fedora/#upgrading) and the [Debian upgrade guides](/doc/templates/debian/#upgrading)).
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-versions/#note-on-dom0-and-eol).

258
user/how-to-guides/how-to-use-block-storage-devices.md Normal file
View file

@ -0,0 +1,258 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-block-storage-devices/
redirect_from:
- /doc/block-devices/
- /doc/stick-mounting/
- /en/doc/stick-mounting/
- /doc/StickMounting/
- /wiki/StickMounting/
ref: 193
title: How to Use Block Storage Devices
---
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data".
## Using The GUI to Attach a Drive
(**Note:** In the present context, the term "USB drive" 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 OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
Attaching USB drives is integrated into the Devices Widget: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
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.
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device](/doc/usb-devices/).
Entries without a number (e.g. here `sda`) are the whole block-device.
Other entries are partitions of that block-device (e.r. here `sda1`).
The simplest option is to attach the entire block drive.
In our example, this is `sys-usb: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:** attaching individual partitions (e.g. `sys-usb:sda1`) 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.
## Block Devices in VMs
If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number.
If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi2 mnt
```
where `xvdi2` needs to be replaced with the partition you want to mount.
This will make your drive content accessible under `~/mnt`.
Beware that when you attach a whole block device, partitions can be identified by their trailing integer (i.e. `/dev/xvdi2` for the second partition, `/dev/xvdi` for the whole device), whereas if you attach a single partition, the partition has *no trailing integer*.
If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on.
To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option](#frontend-dev).
## Command Line Tool Guide
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`.
`qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns.
So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node.
In case of a USB-drive, make sure it's attached to your computer.
If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`)
1. In a dom0 console (running as a normal user), list all available block devices:
```
qvm-block
```
This will list all available block devices in your system across all VMs.
The name of the qube hosting the block device is displayed before the colon in the device ID.
The string after the colon is the ID of the device used within the qube, like so:
```
sourceVM:sdb Cruzer () 4GiB
sourceVM:sdb1 Disk () 2GiB
```
2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so:
```
qvm-block attach work 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, e.g. `sdb1`.
3. The block device 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 (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible:
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
4. When you finish using the block device, 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
```
5. In a dom0 console, detach the device
```
qvm-block detach work sys-usb:sdb
```
6. You may now remove the device or attach it to another qube.
## Recovering From Premature Device Destruction
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
To recover from this error state, in dom0 run
```
virsh detach-disk targetVM xvdi
```
(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node](#frontend-dev).)
However, if the block device originated in dom0, you will have to refer to the next section.
### What if I removed the device before detaching it from the VM?
Currently (until issue [1082](https://github.com/QubesOS/qubes-issues/issues/1082) gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
If this isn't an option, you can manually recover from the situation by following these 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 the `xl block-attach` command.
It is important to use the same "frontend" device name (by default, `xvdi`).
You can get it from the `qvm-block` listing:
```shell_session
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as '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:
* `testvm` - name of target qube to which device was attached - listed in 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 the 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 VM Manager or the `qvm-block -d` command.
## Attaching a File
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
1. In the linux sourceVM run
```
sudo losetup -f --show /path/to/file
```
[This command](https://linux.die.net/man/8/losetup) will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available.
Afterwards it prints the device-node-name it found.
2. If you want to use the GUI, you're done.
Click the Device Manager ![device manager icon](/attachment/wiki/Devices/media-removable.png) and select the `loop0`-device to attach it to another qube.
If you rather use the command line, continue:
In dom0, run `qvm-block` to display known block devices.
The newly created loop device should show up:
```shell_session
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
sourceVM:loop0 /path/to/file
```
3. Attach the `loop0`-device using qvm-block as usual:
```
qvm-block a targetVM sourceVM:loop0
```
4. After detaching, destroy the loop-device inside the sourceVM as follows:
```
sudo losetup -d /dev/loop0
```
## Additional Attach Options
Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option.
(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
### frontend-dev
This option allows you to specify the name of the device node made available in the targetVM.
This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order.
(The next one tried will be `xvdj`, then `xvdk`, and so on ...)
usage example:
```
qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
```
This command will attach the partition `sda1` to `work` as `/dev/xvdz`.
### read-only
Attach device in read-only mode.
Protects the block device in case you don't trust the targetVM.
If the device is a read-only device, this option is forced true.
usage example:
```
qvm-block a work sys-usb:sda1 -o read-only=true
```
There exists a shortcut to set read-only `true`, `--ro`:
```
qvm-block a work sys-usb:sda1 --ro
```
The two commands are equivalent.
### devtype
Usually, a block device is attached as disk.
In case you need to attach a block device as cdrom, this option allows that.
usage example:
```
qvm-block a work sys-usb:sda1 -o devtype=cdrom
```
This option accepts `cdrom` and `disk`, default is `disk`.

160
user/how-to-guides/how-to-use-devices.md Normal file
View file

@ -0,0 +1,160 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-devices/
redirect_from:
- /doc/device-handling/
- /doc/external-device-mount-point/
- /en/doc/external-device-mount-point/
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
ref: 188
title: How to Use Devices
---
This is an overview of device handling in Qubes OS.
For specific devices ([block](/doc/block-devices/), [USB](/doc/usb-devices/) and [PCI](/doc/pci-devices/) devices), please visit their respective pages.
**Important security warning:** Device handling comes with many security implications.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/)**.
## Introduction ##
The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget.
In Qubes 3.X, the Qubes VM Manager dealt with attachment as well.
This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
There are currently four categories of devices Qubes understands:
- Microphones
- Block devices
- USB devices
- PCI devices
Microphones, block devices and USB devices can be attached with the GUI-tool.
PCI devices can be attached using the Qube Settings, but require a VM reboot.
## General Qubes Device Widget Behavior And Handling ##
When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive](/attachment/wiki/Devices/media-removable.png) several device-classes separated by lines are displayed as tooltip.
Block devices are displayed on top, microphones one below and USB-devices at the bottom.
On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
### Attaching Using The Widget ###
Click the tray icon.
Hover on a device you want to attach to a VM.
A list of running VMs (except dom0) appears.
Click on one and your device will be attached!
### Detaching Using The Widget ###
To detach a device, click the Qubes Devices Widget icon again.
Attached devices are displayed in bold.
Hover the one you want to detach.
A list of VMs appears, one showing the eject symbol: ![eject icon](/attachment/wiki/Devices/media-eject.png)
### Attaching a Device to Several VMs ###
Only `mic` should be attached to more than one running VM.
You may *assign* a device to more than one VM (using the `--persistent` option), however, only one of them can be started at the same time.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`](https://github.com/QubesOS/qubes-issues/issues/4692) which will allow you to *attach* a block device to two running VMs.
Don't do that!
## General `qvm-device` Command Line Tool Behavior ##
All devices, including PCI-devices, may be attached from the commandline using the `qvm-device`-tools.
### Device Classes ###
`qvm-device` expects DEVICE_CLASS as first argument.
DEVICE_CLASS can be one of
- `pci`
- `usb`
- `block`
- `mic`
### Actions ###
`qvm-device` supports three actions:
- `list` (ls, l) - list all devices of DEVICE_CLASS
- `attach` (at, a) - attach a specific device of DEVICE_CLASS
- `detach` (dt, d) - detach a specific device of DEVICE_CLASS
### Global Options ###
These three options are always available:
- `--help`, `-h` - show help message and exit
- `--verbose`, `-v` - increase verbosity
- `--quiet`, `-q` - decrease verbosity
A full command consists of one DEVICE_CLASS and one action.
If no action is given, list is implied.
DEVICE_CLASS however is required.
**SYNOPSIS**:
`qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
## Actions
Actions are applicable to every DEVICE_CLASS and expose some additional options.
### Listing Devices
The `list` action lists known devices in the system.
`list` accepts VM-names to narrow down listed devices.
Devices available in, as well as attached to the named VMs will be listed.
`list` accepts two options:
- `--all` - equivalent to specifying every VM name after `list`.
No VM-name implies `--all`.
- `--exclude` - exclude VMs from `--all`.
Requires `--all`.
**SYNOPSIS**
`qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]`
### Attaching Devices
The `attach` action assigns an exposed device to a VM.
This makes the device available in the VM it's attached to.
Required argument are targetVM and sourceVM:deviceID.
(sourceVM:deviceID can be determined from `list` output)
`attach` accepts two options:
- `--persistent` - attach device on targetVM-boot.
If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
- `--option`, `-o` - set additional options specific to DEVICE_CLASS.
**SYNOPSIS**
`qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]`
### Detaching Devices
The `detach` action removes an assigned device from a targetVM.
It won't be available afterwards anymore.
Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.*
`detach` accepts no options.
**SYNOPSIS**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`

190
user/how-to-guides/how-to-use-disposablevms.md Normal file
View file

@ -0,0 +1,190 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-disposablevms/
redirect_from:
- /doc/disposablevm/
- /doc/dispvm/
- /en/doc/dispvm/
- /doc/DisposableVms/
- /wiki/DisposableVMs/
ref: 203
title: How to Use DisposableVMs
---
A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
DisposableVMs 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 DisposableVM` option on a file will launch a DisposableVM for just that file.
Changes made to a file opened in a DisposableVM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
DisposableVMs can be launched either directly from dom0's Start Menu or terminal window, or from within AppVMs.
While running, DisposableVMs will appear in Qubes VM Manager with the name `disp####`.
[![disposablevm-example.png](/attachment/wiki/DisposableVms/disposablevm-example.png)](/attachment/wiki/DisposableVms/disposablevm-example.png)
This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
## Security
If a [DisposableVM Template](/doc/glossary/#disposablevm-template) becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM.
### DisposableVMs and Local Forensics
At this time, DisposableVMs 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).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## DisposableVMs and Networking
Similarly to how AppVMs are based on their underlying [TemplateVM](/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](/doc/glossary/#disposablevm-template).
R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default DisposableVM 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` DisposableVM Template available for your use.
You can set any AppVM to have the ability to act as a DisposableVM Template with:
```
qvm-prefs <vmname> template_for_dispvms True
```
The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM 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 DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM.
This can also be changed from the command line with:
```
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
```
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 DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings.
NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the DisposableVM Template on which it is based.
This is a change in behaviour from R3.2, where DisposableVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DisposableVM Template on which it is based.
For example, if an AppVM uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM 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 DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net.
A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DisposableVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DisposableVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu.
Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu.
**Important Notes:**
Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command:
```
qvm-features <DISPOSABLEVM> appmenus-dispvm 1
```
To launch a DisposableVM Template from the command line, in dom0 please type the following:
```
qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
```
## Opening a file in a DisposableVM via GUI
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "View in DisposableVM" or "Edit in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png)
## Opening a fresh web browser instance in a new DisposableVM
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png)
## Opening a file in a DisposableVM via command line (from AppVM)
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
## Starting an arbitrary program in a DisposableVM from an AppVM
Sometimes it can be useful to start an arbitrary program in a DisposableVM.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
Starting an arbitrary program can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '@dispvm' xterm
~~~
The created DisposableVM 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 DisposableVM via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
It is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
~~~
$ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
~~~
The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube
Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in DisposableVMs.
Obviously, you can't use the default DisposableVM Template, since it has no networking, so you need to be able to specify a different DisposableVM Template.
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> https://www.qubes-os.org
~~~
This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
#### Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
~~~
@anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
~~~
This line means:
- FROM: Any VM
- TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
In other words, any VM will be allowed to create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` and open a URL inside of that DisposableVM.
More information about RPC policies for DisposableVMs can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing DisposableVMs
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).

25
user/how-to-guides/how-to-use-optical-discs.md Normal file
View file

@ -0,0 +1,25 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-optical-discs/
redirect_from:
- /doc/optical-discs/
- /doc/recording-optical-discs/
- /en/doc/recording-optical-discs/
ref: 204
title: How to Use Optical Discs
---
Passthrough reading and recording (a.k.a., "burning") are not supported by Xen.
Currently, the only options for reading and recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0.
(**Caution:** This option is [potentially dangerous](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to.
Typically this would be `sr0`.
For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`.
You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`.

145
user/how-to-guides/how-to-use-pci-devices.md Normal file
View file

@ -0,0 +1,145 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-pci-devices/
redirect_from:
- /doc/pci-devices/
- /doc/assigning-devices/
- /en/doc/assigning-devices/
- /doc/AssigningDevices/
- /wiki/AssigningDevices/
ref: 197
title: How to Use PCI Devices
---
*This page is part of [device handling in qubes](/doc/device-handling/).*
**Warning:** Only dom0 exposes PCI devices.
Some of them are strictly required in dom0 (e.g., the host bridge).
You may end up with an unusable system by attaching the wrong PCI device to a VM.
PCI passthrough should be safe by default, but non-default options may be required.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#pci-security)** before deviating from default behavior.
## Introduction
Unlike other devices ([USB](/doc/usb-devices/), [block](/doc/block-devices/), mic), PCI devices need to be attached on VM-bootup.
Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported.
The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install.
While this covers most use cases, there are some occasions when you may want to manually attach one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually attach.
Some devices expose multiple functions with distinct BDF-numbers.
Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM.
This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations](/doc/device-handling-security/#pci-security).
In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM.
This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
## Attaching Devices Using the GUI
The qube settings for a VM offers the "Devices"-tab.
There you can attach PCI-devices to a qube.
1. To reach the settings of any qube either
- Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu](/attachment/wiki/Devices/qubes-appmenu-select.png)\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
- Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
- Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
2. Select the "Devices" tab on the top bar.
3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
4. You're done.
If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached.
5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab).
If that doesn't help, read on to learn how to disable the strict reset requirement!
## `qvm-pci` Usage
The `qvm-pci` tool allows PCI attachment and detachment.
It's a shortcut for [`qvm-device pci`](/doc/device-handling/#general-qubes-device-widget-behavior-and-handling).
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
```
qvm-pci
```
This will show you the `backend:BDF` (Bus_Device.Function) address of each PCI device.
It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to attach, then attach it like this:
```
qvm-pci attach targetVM sourceVM:[BDF] --persistent
```
Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option.
For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this:
```
qvm-pci attach work dom0:00_1a.0 --persistent
```
## Possible Issues
Visit the [PCI Troubleshooting guide](/doc/pci-troubleshooting/) to see issues that may arise due to PCI devices and how to troubleshoot them.
## Additional Attach Options
Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option.
(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
`qvm-pci` exposes two additional options.
Both are intended to fix device or driver specific issues, but both come with [heavy security implications](/doc/device-handling-security/#pci-security)! **Make sure you understand them before continuing!**
### no-strict-reset
Do not require PCI device to be reset before attaching it to another VM.
This may leak usage data even without malicious intent!
usage example:
```
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
```
### permissive
Allow write access to full PCI config space instead of whitelisted registers.
This increases attack surface and possibility of [side channel attacks](https://en.wikipedia.org/wiki/Side-channel_attack).
usage example:
```
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
```
## Bringing PCI Devices Back to dom0
By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0.
This is an intended feature.
A device which was previously attached to a VM less trusted than dom0 (which, in Qubes, is *all* of them) could attack dom0 if it were automatically reattached there.
In order to re-enable the device in dom0, either:
- Reboot the physical machine. (Best practice)
or
- Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver.
Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
```
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
```
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!

158
user/how-to-guides/how-to-use-usb-devices.md Normal file
View file

@ -0,0 +1,158 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-usb-devices/
redirect_from:
- /doc/usb-devices/
- /doc/usb/
ref: 195
title: How to Use USB Devices
---
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/block-devices/) page.
**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
**Important security warning:** USB passthrough comes with many security implications.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
Whenever possible, attach a [block device](/doc/block-devices/) instead.
Examples of valid cases for USB-passthrough:
- [microcontroller programming](https://www.arduino.cc/en/Main/Howto)
- [external audio devices](/doc/external-audio/)
- [optical drives](/doc/recording-optical-discs/) for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/).
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
## Attaching And Detaching a USB Device
### With Qubes Device Manager
Click the device-manager-icon: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
A list of available devices appears.
USB-devices have a USB-icon to their right: ![usb icon](/attachment/wiki/Devices/generic-usb.png)
Hover on one device to display a list of VMs you may attach it to.
Click one of those.
The USB device will be attached to it.
You're done.
After you finished using the USB-device, you can detach it the same way 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 on the attached device to display a list of running VMs.
The one to which your device is connected will have an eject button ![eject icon](/attachment/wiki/Devices/media-eject.png) next to it.
Click that and your device will be detached.
### With The Command Line Tool
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
Listing available USB devices:
```shell_session
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
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:
```shell_session
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
Now, you can use your USB device (camera in this case) in the `work` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
When you finish, detach the device.
```shell_session
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
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_Optical_Mouse
```
## Maintenance And Customisation
### Creating And Using a USB qube
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
### Installation Of `qubes-usb-proxy`
To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
Under normal conditions, `qubes-usb-proxy` should already be installed and good to go.
If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Using USB Keyboards And Other Input Devices
**Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing!
Mouse and keyboard setup are part of [setting up a USB-qube](/doc/usb-qubes/#enable-a-usb-keyboard-for-login).
### Finding The Right USB Controller
Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it.
If you have multiple USB controllers, you must first figure out which PCI device is the right controller.
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
```
lsusb
```
For example, I want to attach a broadband modem to the NetVM.
In the output of `lsusb` it may be listed as something like:
```
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
```
(In this case, the device isn't fully identified)
The device is connected to USB bus \#3.
Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM.
To find the right controller, follow the usb bus:
```
readlink /sys/bus/usb/devices/usb3
```
This should output something like:
```
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/pci-devices/) to attach the controller to the targetVM.
For example, On R 4.0 the command would look something like
`qvm-pci attach --persistent personal dom0:00_1a.0`