mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-07-31 02:29:32 -04:00
Convert to RST
This is done using tools at https://github.com/maiska/qubes-translation-utilz, commit 4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
This commit is contained in:
Marek Marczykowski-Górecki
parent
e3db139fe3
commit
7e464d0f40
428 changed files with 32833 additions and 29703 deletions
|
|
@ -1,131 +0,0 @@
|
|||
---
|
||||
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. 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 -r backup_pass
|
||||
|
||||
3. Verify the integrity of the `private.img` file which houses your data.
|
||||
|
||||
~~~
|
||||
[user@restore ~]$ cd vm1/
|
||||
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" 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`.
|
||||
|
||||
4. Decrypt the `private.img` file.
|
||||
|
||||
~~~
|
||||
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -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 -md MD5 -pass pass:"$backup_pass" -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`.
|
||||
|
||||
5. 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.
|
||||
|
||||
6. 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.)
|
||||
|
||||
7. 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)
|
||||
142
user/how-to-guides/backup-emergency-restore-v2.rst
Normal file
142
user/how-to-guides/backup-emergency-restore-v2.rst
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
==============================
|
||||
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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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. 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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ read -r backup_pass
|
||||
|
||||
|
||||
|
||||
3. Verify the integrity of the ``private.img`` file which houses your data.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ cd vm1/
|
||||
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" 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``.
|
||||
|
||||
4. Decrypt the ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Note:** For multi-part files, a loop can be used:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
find -name 'private.img.*' | sort -V | while read f; do
|
||||
openssl enc -d -md MD5 -pass pass:"$backup_pass" -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``.
|
||||
|
||||
5. Decompress the decrypted ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.
|
||||
|
||||
6. Untar the decrypted and decompressed ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
#!/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.)
|
||||
|
||||
|
||||
|
||||
7. Mount the private.img file and access your data.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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>`__
|
||||
|
|
@ -1,144 +0,0 @@
|
|||
---
|
||||
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. 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 -r backup_pass
|
||||
|
||||
3. Verify the integrity of the `backup-header` file, which contains basic
|
||||
information about your backup.
|
||||
|
||||
[user@restore ~]$ openssl dgst -sha512 -hmac "$backup_pass" 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 4), 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`.
|
||||
|
||||
4. 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.
|
||||
|
||||
5. Verify the integrity of the `private.img` file which houses your data.
|
||||
|
||||
[user@restore ~]$ cd vm1/
|
||||
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" 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 4). A
|
||||
complete list of supported message digest algorithms can be found with
|
||||
`openssl list-message-digest-algorithms`.
|
||||
|
||||
6. Decrypt the `private.img` file.
|
||||
|
||||
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -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 4). A
|
||||
complete list of supported cipher algorithms can be found with `openssl
|
||||
list-cipher-algorithms`.
|
||||
|
||||
7. 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 4). 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
|
||||
|
||||
8. Untar the decrypted and decompressed `private.img` file.
|
||||
|
||||
[user@restore vm1]$ tar -xvf private.img.dec
|
||||
vm1/private.img
|
||||
|
||||
9. 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!
|
||||
|
||||
10. Success! If you wish to recover data from more than one VM in your backup,
|
||||
simply repeat steps 5--9 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
|
||||
146
user/how-to-guides/backup-emergency-restore-v3.rst
Normal file
146
user/how-to-guides/backup-emergency-restore-v3.rst
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
==============================
|
||||
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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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. 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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ read -r backup_pass
|
||||
|
||||
|
||||
|
||||
3. Verify the integrity of the ``backup-header`` file, which contains basic information about your backup.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ openssl dgst -sha512 -hmac "$backup_pass" 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 4), 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``.
|
||||
|
||||
|
||||
|
||||
4. Read the ``backup-header``. You’ll need some of this information later. The file will look similar to this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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 :doc:`Emergency Backup Recovery - format version 2 </user/how-to-guides/backup-emergency-restore-v2>` instead.
|
||||
|
||||
5. Verify the integrity of the ``private.img`` file which houses your data.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ cd vm1/
|
||||
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" 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 4). A complete list of supported message digest algorithms can be found with ``openssl list-message-digest-algorithms``.
|
||||
|
||||
|
||||
|
||||
6. Decrypt the ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -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 4). A complete list of supported cipher algorithms can be found with ``openssl list-cipher-algorithms``.
|
||||
|
||||
7. Decompress the decrypted ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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 4). For example, if you used ``bzip2``, then you should do this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
|
||||
[user@restore vm1]$ bunzip2 private.img.dec.bz2
|
||||
|
||||
|
||||
|
||||
8. Untar the decrypted and decompressed ``private.img`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore vm1]$ tar -xvf private.img.dec
|
||||
vm1/private.img
|
||||
|
||||
|
||||
|
||||
9. Mount the private.img file and access your data.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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!
|
||||
|
||||
|
||||
|
||||
10. Success! If you wish to recover data from more than one VM in your backup, simply repeat steps 5–9 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,202 +0,0 @@
|
|||
---
|
||||
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 is 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 by following the instructions on this page.
|
||||
|
||||
**Important:** You may wish to store a copy of these instructions with your
|
||||
Qubes backups. All Qubes documentation, including this page, is available in
|
||||
plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git
|
||||
repository.
|
||||
|
||||
## 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, [import and authenticate the Release 4 Signing
|
||||
Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
|
||||
|
||||
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
|
||||
|
||||
2. 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
|
||||
|
||||
3. 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.
|
||||
|
||||
4. Install `rpmdevtools`.
|
||||
|
||||
[user@restore ~]$ sudo dnf install rpmdevtools
|
||||
|
||||
5. Extract the `scrypt` binary from the RPM and make it conveniently
|
||||
available.
|
||||
|
||||
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
|
||||
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
|
||||
|
||||
## Emergency recovery instructions
|
||||
|
||||
**Note:** In the following example, the backup file is both *encrypted* and
|
||||
*compressed*.
|
||||
|
||||
1. Untar the backup metadata from the main backup file.
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
|
||||
backup-header backup-header.hmac qubes.xml.000.enc
|
||||
backup-header
|
||||
backup-header.hmac
|
||||
qubes.xml.000.enc
|
||||
|
||||
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 -r backup_pass
|
||||
|
||||
Type in your passphrase (it will be visible on screen!) and press Enter.
|
||||
|
||||
3. Verify the integrity of `backup-header` using `backup-header.hmac` (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
|
||||
hmac-algorithm=scrypt
|
||||
backup-id=20230405T123455-1234
|
||||
|
||||
5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
|
||||
there is a hyphen in `backup-id` in the file, whereas there is an underscore
|
||||
in `backup_id` in the variable you're setting.)
|
||||
|
||||
[user@restore ~]$ backup_id=20230405T123455-1234
|
||||
|
||||
6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
|
||||
|
||||
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
|
||||
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
|
||||
qubes.xml
|
||||
|
||||
- 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 of `gzip
|
||||
-d` in the command above. You might need to install a package of the same
|
||||
name (in this example, `bzip2`) through your distribution's package manager.
|
||||
|
||||
7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
|
||||
whose data you wish to restore. If you install the `xmlstarlet` package, the
|
||||
following command will convert `qubes.xml` to a friendlier listing for this
|
||||
purpose:
|
||||
|
||||
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
|
||||
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
|
||||
-n qubes.xml
|
||||
|
||||
anon-whonix
|
||||
debian-11
|
||||
default-mgmt-dvm
|
||||
disp2345
|
||||
fedora-37
|
||||
fedora-37-dvm
|
||||
personal vm123/
|
||||
sys-firewall
|
||||
sys-net
|
||||
sys-usb
|
||||
sys-whonix
|
||||
untrusted
|
||||
vault vm321/
|
||||
whonix-gw-16
|
||||
whonix-ws-16
|
||||
whonix-ws-16-dvm
|
||||
work
|
||||
|
||||
The example output above shows that the backup file includes a qube named
|
||||
`personal` and a qube named `vault`, with `backup-path` values of `vm123/`
|
||||
and `vm321/` respectively. (Every other listed qube was not selected to be
|
||||
included in the backup file.) Use the corresponding value to untar the
|
||||
necessary data files of the qube:
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
|
||||
|
||||
8. Verify and decrypt the backed up data, decompress it, and extract it.
|
||||
|
||||
[user@restore ~]$ find vm123/ -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
|
||||
vm123/private.img
|
||||
|
||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
||||
been tampered with.
|
||||
|
||||
Also see the note in step 6 about substituting a different compression
|
||||
program for `gzip`.
|
||||
|
||||
9. Mount `private.img` and access your data.
|
||||
|
||||
[user@restore ~]$ sudo mkdir /mnt/img
|
||||
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
|
||||
[user@restore ~]$ ls /mnt/img/home/user/
|
||||
example_data_file.txt
|
||||
...
|
||||
|
||||
Success! If you wish to recover data from more than one qube in your backup,
|
||||
simply repeat steps 7, 8, and 9 for each additional qube.
|
||||
219
user/how-to-guides/backup-emergency-restore-v4.rst
Normal file
219
user/how-to-guides/backup-emergency-restore-v4.rst
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
==============================
|
||||
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 is 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 by following the instructions on this page.
|
||||
|
||||
**Important:** You may wish to store a copy of these instructions with your Qubes backups. All Qubes documentation, including this page, is available in plain text format in the `qubes-doc <https://github.com/QubesOS/qubes-doc>`__ Git repository.
|
||||
|
||||
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 :doc:`verify signatures </project-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, :ref:`import and authenticate the Release 4 Signing Key <project-security/verifying-signatures:how to import and authenticate release signing keys>`.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
|
||||
|
||||
|
||||
|
||||
2. Download the ``scrypt`` RPM.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ dnf download scrypt
|
||||
|
||||
|
||||
Or, if that doesn’t work:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
|
||||
|
||||
|
||||
|
||||
3. Verify the signature on the ``scrypt`` RPM.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.
|
||||
|
||||
4. Install ``rpmdevtools``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ sudo dnf install rpmdevtools
|
||||
|
||||
|
||||
|
||||
5. Extract the ``scrypt`` binary from the RPM and make it conveniently available.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
|
||||
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Emergency recovery instructions
|
||||
-------------------------------
|
||||
|
||||
|
||||
**Note:** In the following example, the backup file is both *encrypted* and *compressed*.
|
||||
|
||||
1. Untar the backup metadata from the main backup file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
|
||||
backup-header backup-header.hmac qubes.xml.000.enc
|
||||
backup-header
|
||||
backup-header.hmac
|
||||
qubes.xml.000.enc
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ read -r backup_pass
|
||||
|
||||
|
||||
Type in your passphrase (it will be visible on screen!) and press Enter.
|
||||
|
||||
3. Verify the integrity of ``backup-header`` using ``backup-header.hmac`` (an encrypted *and integrity protected* version of ``backup-header``).
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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:
|
||||
|
||||
- :doc:`Emergency Backup Recovery without Qubes (v2) </user/how-to-guides/backup-emergency-restore-v2>`
|
||||
|
||||
- :doc:`Emergency Backup Recovery without Qubes (v3) </user/how-to-guides/backup-emergency-restore-v3>`
|
||||
|
||||
|
||||
|
||||
4. Read ``backup-header``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ cat backup-header
|
||||
version=4
|
||||
encrypted=True
|
||||
compressed=True
|
||||
compression-filter=gzip
|
||||
hmac-algorithm=scrypt
|
||||
backup-id=20230405T123455-1234
|
||||
|
||||
|
||||
|
||||
5. Set ``backup_id`` to the value in the last line of ``backup-header``. (Note that there is a hyphen in ``backup-id`` in the file, whereas there is an underscore in ``backup_id`` in the variable you’re setting.)
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ backup_id=20230405T123455-1234
|
||||
|
||||
|
||||
|
||||
6. Verify and decrypt, decompress, and extract the ``qubes.xml`` file.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
|
||||
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
|
||||
qubes.xml
|
||||
|
||||
|
||||
|
||||
- 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 of ``gzip -d`` in the command above. You might need to install a package of the same name (in this example, ``bzip2``) through your distribution’s package manager.
|
||||
|
||||
|
||||
|
||||
7. Search inside of the ``qubes.xml`` file for the ``backup-path`` of the qube whose data you wish to restore. If you install the ``xmlstarlet`` package, the following command will convert ``qubes.xml`` to a friendlier listing for this purpose:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
|
||||
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
|
||||
-n qubes.xml
|
||||
|
||||
anon-whonix
|
||||
debian-11
|
||||
default-mgmt-dvm
|
||||
disp2345
|
||||
fedora-37
|
||||
fedora-37-dvm
|
||||
personal vm123/
|
||||
sys-firewall
|
||||
sys-net
|
||||
sys-usb
|
||||
sys-whonix
|
||||
untrusted
|
||||
vault vm321/
|
||||
whonix-gw-16
|
||||
whonix-ws-16
|
||||
whonix-ws-16-dvm
|
||||
work
|
||||
|
||||
|
||||
The example output above shows that the backup file includes a qube named ``personal`` and a qube named ``vault``, with ``backup-path`` values of ``vm123/`` and ``vm321/`` respectively. (Every other listed qube was not selected to be included in the backup file.) Use the corresponding value to untar the necessary data files of the qube:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
|
||||
|
||||
|
||||
|
||||
8. Verify and decrypt the backed up data, decompress it, and extract it.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ find vm123/ -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
|
||||
vm123/private.img
|
||||
|
||||
|
||||
If this pipeline fails, it is likely that the backup is corrupted or has been tampered with.
|
||||
Also see the note in step 6 about substituting a different compression program for ``gzip``.
|
||||
|
||||
9. Mount ``private.img`` and access your data.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@restore ~]$ sudo mkdir /mnt/img
|
||||
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
|
||||
[user@restore ~]$ ls /mnt/img/home/user/
|
||||
example_data_file.txt
|
||||
...
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Success! If you wish to recover data from more than one qube in your backup, simply repeat steps 7, 8, and 9 for each additional qube.
|
||||
|
|
@ -1,215 +0,0 @@
|
|||
---
|
||||
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/* ~/backup/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 app qube**. 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 **app qube**.
|
||||
|
||||
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 template 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**.
|
||||
|
||||
In case that applications are not shown, i.e. "No applications found", open the
|
||||
settings of the qube -> select `Applications` -> click `Refresh applications`.
|
||||
|
||||
When a restored application qube refreshes, the application lists will open the template qubes on which it is based. In that case the template qube should also be restored, if it is missing the default qube will be assigned.
|
||||
The updated list of the installed software can be seen on the left and adjusted accordingly to the user's needs.
|
||||
|
||||
**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 undesired 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).
|
||||
157
user/how-to-guides/how-to-back-up-restore-and-migrate.rst
Normal file
157
user/how-to-guides/how-to-back-up-restore-and-migrate.rst
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
====================================
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ mkdir -p ~/backup/etc/qubes/
|
||||
$ cp -a /etc/qubes/* ~/backup/etc/qubes/
|
||||
$ mkdir ~/backup/etc/qubes-rpc/
|
||||
$ cp -a /etc/qubes-rpc/* ~/backup/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 app qube**. If you wish to send your backup to a :doc:`USB mass storage device </user/how-to-guides/how-to-use-usb-devices>`, 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 :doc:`USB mass storage device </user/how-to-guides/how-to-use-usb-devices>`, 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 **app qube**.
|
||||
|
||||
|
||||
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 template 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**.
|
||||
|
||||
|
||||
|
||||
In case that applications are not shown, i.e. “No applications found”, open the settings of the qube -> select ``Applications`` -> click ``Refresh applications``.
|
||||
|
||||
When a restored application qube refreshes, the application lists will open the template qubes on which it is based. In that case the template qube should also be restored, if it is missing the default qube will be assigned. The updated list of the installed software can be seen on the left and adjusted accordingly to the user’s needs.
|
||||
|
||||
**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 undesired 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:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Qubes R4 or newer </user/how-to-guides/backup-emergency-restore-v4>
|
||||
|
||||
Qubes R3 </user/how-to-guides/backup-emergency-restore-v3>
|
||||
|
||||
Qubes R2 or older </user/how-to-guides/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 <https://www.qubes-os.org/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>`__.
|
||||
|
||||
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
---
|
||||
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/how-to-copy-and-paste-text/).
|
||||
For dom0, see [copying from (and to) dom0](/doc/how-to-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.
|
||||
51
user/how-to-guides/how-to-copy-and-move-files.rst
Normal file
51
user/how-to-guides/how-to-copy-and-move-files.rst
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
==========================
|
||||
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* :doc:`copying and pasting text between qubes </user/how-to-guides/how-to-copy-and-paste-text>` *. For dom0, see* :doc:`copying from (and to) dom0 </user/how-to-guides/how-to-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):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
/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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-copy [--without-progress] file [file]+
|
||||
|
||||
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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.
|
||||
|
|
@ -1,99 +0,0 @@
|
|||
---
|
||||
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/how-to-copy-and-move-files/).
|
||||
For dom0, see [copying from (and to) dom0](/doc/how-to-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" app qube (and it is highly recommended that you do not), then you should edit the policy as follows:
|
||||
|
||||
~~~
|
||||
@anyvm vault deny
|
||||
@anyvm @anyvm ask
|
||||
~~~
|
||||
|
||||
Automatic clipboard wiping
|
||||
--------------------------
|
||||
|
||||
By default data pasted into a qube will remain there until user copies something else or restarts the qube. It's possible to make the `qubes-gui` process inside a qube wipe the clipboard automatically after a minute from the last paste operation. This helps protect users from accidentally pasting the old content of the clipboard like a password in the wrong place like a browser search bar. Since qubes don't share the same clipboard, software like KeePassXC isn't able to automatically wipe the clipboard of other qubes.
|
||||
|
||||
To enable automatic wiping of the clipboard after a minute use `qvm-service`:
|
||||
|
||||
~~~
|
||||
qvm-service --enable VMNAME gui-agent-clipboard-wipe
|
||||
~~~
|
||||
|
||||
Shortcut configuration
|
||||
----------------------
|
||||
|
||||
The copy/paste shortcuts are configurable via `qvm-features`, e.g.
|
||||
|
||||
~~~
|
||||
qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
|
||||
qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'
|
||||
~~~
|
||||
|
||||
would change the *copy/paste to global clipboard* to the Win key plus c for copy, or v for paste.
|
||||
|
||||
You need to restart Qubes for the changes to take effect.
|
||||
90
user/how-to-guides/how-to-copy-and-paste-text.rst
Normal file
90
user/how-to-guides/how-to-copy-and-paste-text.rst
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
==========================
|
||||
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* :doc:`copying and moving files between qubes </user/how-to-guides/how-to-copy-and-move-files>` *. For dom0, see* :doc:`copying from (and to) dom0 </user/how-to-guides/how-to-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 :doc:`RPC policy </user/advanced-topics/rpc-policy>` is configurable in:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
/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” app qube (and it is highly recommended that you do not), then you should edit the policy as follows:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@anyvm vault deny
|
||||
@anyvm @anyvm ask
|
||||
|
||||
|
||||
|
||||
Automatic clipboard wiping
|
||||
--------------------------
|
||||
|
||||
|
||||
By default data pasted into a qube will remain there until user copies something else or restarts the qube. It’s possible to make the ``qubes-gui`` process inside a qube wipe the clipboard automatically after a minute from the last paste operation. This helps protect users from accidentally pasting the old content of the clipboard like a password in the wrong place like a browser search bar. Since qubes don’t share the same clipboard, software like KeePassXC isn’t able to automatically wipe the clipboard of other qubes.
|
||||
|
||||
To enable automatic wiping of the clipboard after a minute use ``qvm-service``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-service --enable VMNAME gui-agent-clipboard-wipe
|
||||
|
||||
|
||||
|
||||
Shortcut configuration
|
||||
----------------------
|
||||
|
||||
|
||||
The copy/paste shortcuts are configurable via ``qvm-features``, e.g.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
|
||||
qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'
|
||||
|
||||
|
||||
|
||||
would change the *copy/paste to global clipboard* to the Win key plus c for copy, or v for paste.
|
||||
|
||||
You need to restart Qubes for the changes to take effect.
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
---
|
||||
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/how-to-copy-and-paste-text/) and [copying and moving files between qubes](/doc/how-to-copy-and-move-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 app qube, 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'
|
||||
```
|
||||
86
user/how-to-guides/how-to-copy-from-dom0.rst
Normal file
86
user/how-to-guides/how-to-copy-from-dom0.rst
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
=====================
|
||||
How to copy from dom0
|
||||
=====================
|
||||
|
||||
|
||||
This page covers copying files and clipboard text between :ref:`dom0 <user/reference/glossary:dom0>` and :ref:`domUs <user/reference/glossary:domu>`. Since dom0 is special, the processes are different from :doc:`copying and pasting text between qubes </user/how-to-guides/how-to-copy-and-paste-text>` and :doc:`copying and moving files between qubes </user/how-to-guides/how-to-copy-and-move-files>`.
|
||||
|
||||
Copying *from* dom0
|
||||
-------------------
|
||||
|
||||
|
||||
Copying files from dom0
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
To copy a file from dom0 to a VM, simply use ``qvm-copy-to-vm``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 :doc:`full-screen mode </user/how-to-guides/how-to-enter-fullscreen-mode>` in an app qube, 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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``):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'
|
||||
|
||||
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
---
|
||||
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.
|
||||
63
user/how-to-guides/how-to-enter-fullscreen-mode.rst
Normal file
63
user/how-to-guides/how-to-enter-fullscreen-mode.rst
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
============================
|
||||
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 :doc:`screenshots </introduction/screenshots>` 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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.
|
||||
|
|
@ -1,502 +0,0 @@
|
|||
---
|
||||
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
|
||||
---
|
||||
|
||||
When you wish to install software in Qubes OS, you should generally install it
|
||||
in a [template](/doc/glossary/#template). For installing templates themselves,
|
||||
see [how to install a template](/doc/templates/#installing). Advanced users may
|
||||
also be interested in learning how to install software in
|
||||
[standalones](/doc/standalones-and-hvms/) and
|
||||
[dom0](/doc/how-to-install-software-in-dom0).
|
||||
|
||||
Qubes OS is effectively a "meta" operating system (OS) that can run almost any
|
||||
arbitrary OS inside of itself. For example, the way software is normally
|
||||
installed in a Linux distribution ("distro") is quite different from the way
|
||||
software is normally installed in Windows. This isn't up to Qubes. Qubes is
|
||||
just the framework in which you're running these other OSes. Therefore, if you
|
||||
want to install software in a Linux template, for example, you should do so in
|
||||
whatever way is normal for that Linux distro. Most Linux software is
|
||||
distributed via [packages](https://en.wikipedia.org/wiki/Package_format), which
|
||||
are stored in [software
|
||||
repositories](https://en.wikipedia.org/wiki/Software_repository) ("repos").
|
||||
[Package managers](https://en.wikipedia.org/wiki/Package_manager) handle
|
||||
downloading, installing, updating, and removing packages. (Again, none of this
|
||||
is Qubes-specific.) If you're not familiar with how software is normally
|
||||
installed in Linux distros via package managers or the software you want
|
||||
doesn't seem to be available in your distro's repos (or you're in another
|
||||
situation not covered on this page), please read this [community guide to
|
||||
installing software in Qubes](https://forum.qubes-os.org/t/9991/).
|
||||
|
||||
The following instructions explain how to permanently install new software in a
|
||||
template. There are different instructions for software from the default
|
||||
repositories and all other software. (If you're not sure, try the default
|
||||
repositories first.)
|
||||
|
||||
|
||||
## Installing software from default repositories
|
||||
|
||||
1. Start the template.
|
||||
|
||||
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.:
|
||||
- Fedora: `sudo dnf install <PACKAGE_NAME>`
|
||||
- Debian: `sudo apt install <PACKAGE_NAME>`
|
||||
|
||||
4. Shut down the template.
|
||||
|
||||
5. Restart all qubes based on the template.
|
||||
|
||||
6. (Recommended) In the relevant qubes' **Settings > 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/app-menu-shortcut-troubleshooting/) for troubleshooting.)
|
||||
|
||||
](/attachment/doc/r4.1-dom0-appmenu-select.png)
|
||||
|
||||
|
||||
## Installing software from other sources
|
||||
|
||||
Some software is not available from the default repositories and must be
|
||||
downloaded and installed from another source. Depending on the installation method,
|
||||
you may either use the updates proxy or direct networking.
|
||||
|
||||
### Using the updates proxy
|
||||
|
||||
If you are still using the distribution package manager, updates will likely still
|
||||
work over the updates proxy without needing to give the TemplateVM direct network access.
|
||||
|
||||
If you are using another installation method fetching remote resources, you might still
|
||||
be able to use the updates proxy by making the tools aware of the proxy. For many tools,
|
||||
it is enough to export the following environment variables in your shell session before
|
||||
proceeding:
|
||||
|
||||
```sh
|
||||
$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
|
||||
HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
|
||||
ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \
|
||||
NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY
|
||||
```
|
||||
|
||||
### Using direct networking
|
||||
|
||||
**Warning:** This method gives your template direct network access, which is
|
||||
[risky](#why-dont-templates-have-normal-network-access). This method is **not**
|
||||
recommended for trusted templates. Moreover, depending on how you install this
|
||||
software, it may not get updated automatically when you [update Qubes
|
||||
normally](/doc/how-to-update/), which means you may have to update it manually
|
||||
yourself.
|
||||
|
||||
This method assumes that you are trying to follow instructions to install some piece
|
||||
of software in a normal operating system, except *that* operating system is running as a
|
||||
template in Qubes OS.
|
||||
|
||||
1. (Recommended) Clone the desired template (since this new template will
|
||||
probably be less trusted than the original).
|
||||
|
||||
2. (Recommended) In the new template's **Settings > Basic** tab, change the
|
||||
color label from black to red (or another color that signifies to you that
|
||||
the template is less trusted).
|
||||
|
||||
3. In the new template's **Settings > Basic** tab, change the **Networking**
|
||||
value from `default (none) (current)` to `sys-firewall` (or whichever
|
||||
network-providing qube you wish to use).
|
||||
|
||||
4. (Recommended) In the new template's **Settings > Firewall rules** tab,
|
||||
select "Limit outgoing Internet connections to..." and tick "Allow full
|
||||
access for 5 min." (This can help in case you forget to remove network
|
||||
access later.)
|
||||
|
||||
5. Follow the normal instructions for installing your software in the new
|
||||
template. For example, open a terminal and enter the commands as instructed.
|
||||
**Warning:** If you don't fully understand the commands you're entering,
|
||||
then this can be extremely risky, and the template should be regarded as
|
||||
*completely untrusted*.
|
||||
|
||||
6. (Recommended) In the new template's **Settings > Basic** tab, change the
|
||||
**Networking** value from `sys-firewall (current)` (or whichever
|
||||
network-providing qube you chose) back to `default (none)`.
|
||||
|
||||
7. Shut down the new template.
|
||||
|
||||
8. Create or assign your desired app qubes to use the new template. If any app
|
||||
qubes were already assigned to the new template, restart them.
|
||||
|
||||
9. (Recommended) In the relevant qubes' **Settings > 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/app-menu-shortcut-troubleshooting/) for troubleshooting.)
|
||||
|
||||
](/attachment/doc/r4.1-dom0-appmenu-select.png)
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If things are still not working as expected:
|
||||
|
||||
- Review the instructions very carefully, making sure you follow each step.
|
||||
- Make sure you **shut down the template after installing your software**.
|
||||
- Make sure you **restart your app qube *after* shutting down your template**.
|
||||
- Make sure your app qube is assigned to the right template.
|
||||
- If your software requires special files or directories to be persistent, and
|
||||
you're an advanced user, see [standalones and
|
||||
HVMs](/doc/standalones-and-hvms/) and [how to make any file persistent
|
||||
(bind-dirs)](/doc/bind-dirs/).
|
||||
- [Ask for help.](/support/)
|
||||
|
||||
|
||||
## How to update software
|
||||
|
||||
Please see [How to Update](/doc/how-to-update/).
|
||||
|
||||
|
||||
## Why don't templates have normal network access?
|
||||
|
||||
In order to protect you from performing risky activities in templates, they do
|
||||
not have normal network access by default. Instead, templates use an
|
||||
[updates-proxy](#updates-proxy) which allows you to install and update software using
|
||||
the distribution's package manager over the proxy connection.
|
||||
**The updates proxy is already set up to work automatically out-of-the-box and
|
||||
requires no special action from you.**
|
||||
Most users should simply follow the normal instructions for [installing software
|
||||
from default repositories](#installing-software-from-default-repositories)
|
||||
and [updating](/doc/how-to-update/) software. If your software is not available
|
||||
in the default repositories, see [installing software from other
|
||||
sources](#installing-software-from-other-sources).
|
||||
|
||||
|
||||
## Advanced
|
||||
|
||||
The following sections cover advanced topics pertaining to installing and
|
||||
updating software in qubes.
|
||||
|
||||
|
||||
### Testing repositories
|
||||
|
||||
If you wish to install updates that are still in [testing](/doc/testing), you
|
||||
must enable the appropriate testing repositories.
|
||||
|
||||
**Note:** The following repos are in templates and standalones. For dom0 testing
|
||||
repos, see [here](/doc/how-to-install-software-in-dom0/#testing-repositories).
|
||||
For testing new templates, please see [here](/doc/testing/#templates).
|
||||
|
||||
|
||||
#### 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`.
|
||||
|
||||
|
||||
### Standalones
|
||||
|
||||
The process for installing and updating software in
|
||||
[standalones](/doc/glossary/#standalone) is the same as described above for
|
||||
templates, except no qubes are based on standalones, so there are no other
|
||||
qubes to restart.
|
||||
|
||||
|
||||
### RPMFusion for Fedora templates
|
||||
|
||||
If you would like to enable the [RPM Fusion](https://rpmfusion.org/)
|
||||
repositories, open a Terminal of the template 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 setopt rpmfusion-free.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
|
||||
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 template
|
||||
|
||||
Perhaps you've just updated your template, 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 template, 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 template was run, but **not** before.* This means that if you have
|
||||
already restarted the template, 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 template](/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 template),
|
||||
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.
|
||||
|
||||
|
||||
### Updates proxy
|
||||
|
||||
Updates proxy is a service which allows access from package managers
|
||||
configured to use the proxy by default, but can be used by any other
|
||||
program that accepts proxy arguments.
|
||||
The purpose of the proxy, instead of direct network access, is meant to
|
||||
mitigate user errors of using applications such as the browser in the
|
||||
template. Not necessarily what part of the network they can access, but only
|
||||
to applications trusted by the user, configured to use the proxy.
|
||||
The http proxy (tinyproxy) does not filter traffic because it is hard to list
|
||||
all the repository mirrors and keep that list up to date). it also does not
|
||||
cache anything.
|
||||
|
||||
The proxy is running in selected VMs (by default all the NetVMs (1)) and
|
||||
intercepts traffic directed to 127.0.0.1:8082. Thanks to such
|
||||
configuration all the VMs can use the same proxy address.
|
||||
If the VM is configured to have access to the updates proxy
|
||||
(2), the startup scripts will automatically configure dnf/apt 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.1 (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 app qube you need to take the following steps:
|
||||
|
||||
1. In the **template** you must install `snapd` and `qubes-snapd-helper`. Open
|
||||
a terminal in the template and run:
|
||||
|
||||
```shell_session
|
||||
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
|
||||
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
|
||||
Dependencies resolved.
|
||||
========================================================================================================
|
||||
Package Arch Version Repository Size
|
||||
========================================================================================================
|
||||
Installing:
|
||||
snapd x86_64 2.56.2-4.fc36 updates 14 M
|
||||
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
|
||||
Installing dependencies:
|
||||
[...]
|
||||
|
||||
Transaction Summary
|
||||
========================================================================================================
|
||||
Install 19 Packages
|
||||
|
||||
Total download size: 27 M
|
||||
Installed size: 88 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:33:05 ago on Thu 03 Nov 2022 04:34:06.
|
||||
Notifying dom0 about installed applications
|
||||
|
||||
Installed:
|
||||
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.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 template:
|
||||
|
||||
```shell_session
|
||||
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
|
||||
```
|
||||
|
||||
2. Now open the **app qube** in which you would like to install the Snap
|
||||
application and run a terminal:
|
||||
|
||||
```shell_session
|
||||
[user@snap-demo-app qube ~]$ snap install <package>
|
||||
```
|
||||
|
||||
When the install is complete you can close the terminal window.
|
||||
|
||||
3. Refresh the Applications list for the app qube. In the Qubes Menu for the
|
||||
**app qube** 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 app qube's list of available applications. At this point the
|
||||
snap will be persistent within the app qube and will receive updates when
|
||||
the app qube 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 **app
|
||||
qube**. 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 **app qube** 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-app qube ~]$ ls /usr/share/applications/
|
||||
bluetooth-sendto.desktop
|
||||
eog.desktop
|
||||
firefox.desktop
|
||||
...
|
||||
xterm.desktop
|
||||
yelp.desktop
|
||||
```
|
||||
|
||||
3. Create the autostart directory:
|
||||
|
||||
```
|
||||
[user@example-app qube ~]$ 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-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
|
||||
```
|
||||
|
||||
Note that the app will autostart only when the app qube starts. If you would
|
||||
like the app qube to autostart, select the "Start qube automatically on boot"
|
||||
checkbox in the app qube's Qube Settings.
|
||||
409
user/how-to-guides/how-to-install-software.rst
Normal file
409
user/how-to-guides/how-to-install-software.rst
Normal file
|
|
@ -0,0 +1,409 @@
|
|||
=======================
|
||||
How to install software
|
||||
=======================
|
||||
|
||||
|
||||
When you wish to install software in Qubes OS, you should generally install it in a :ref:`template <user/reference/glossary:template>`. For installing templates themselves, see :ref:`how to install a template <user/templates/templates:installing>`. Advanced users may also be interested in learning how to install software in :doc:`standalones </user/advanced-topics/standalones-and-hvms>` and :doc:`dom0 </user/advanced-topics/how-to-install-software-in-dom0>`.
|
||||
|
||||
Qubes OS is effectively a “meta” operating system (OS) that can run almost any arbitrary OS inside of itself. For example, the way software is normally installed in a Linux distribution (“distro”) is quite different from the way software is normally installed in Windows. This isn’t up to Qubes. Qubes is just the framework in which you’re running these other OSes. Therefore, if you want to install software in a Linux template, for example, you should do so in whatever way is normal for that Linux distro. Most Linux software is distributed via `packages <https://en.wikipedia.org/wiki/Package_format>`__, which are stored in `software repositories <https://en.wikipedia.org/wiki/Software_repository>`__ (“repos”). `Package managers <https://en.wikipedia.org/wiki/Package_manager>`__ handle downloading, installing, updating, and removing packages. (Again, none of this is Qubes-specific.) If you’re not familiar with how software is normally installed in Linux distros via package managers or the software you want doesn’t seem to be available in your distro’s repos (or you’re in another situation not covered on this page), please read this `community guide to installing software in Qubes <https://forum.qubes-os.org/t/9991/>`__.
|
||||
|
||||
The following instructions explain how to permanently install new software in a template. There are different instructions for software from the default repositories and all other software. (If you’re not sure, try the default repositories first.)
|
||||
|
||||
Installing software from default repositories
|
||||
---------------------------------------------
|
||||
|
||||
|
||||
1. Start the template.
|
||||
|
||||
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.:
|
||||
|
||||
- Fedora: ``sudo dnf install <PACKAGE_NAME>``
|
||||
|
||||
- Debian: ``sudo apt install <PACKAGE_NAME>``
|
||||
|
||||
|
||||
|
||||
4. Shut down the template.
|
||||
|
||||
5. Restart all qubes based on the template.
|
||||
|
||||
6. (Recommended) In the relevant qubes’ **Settings > 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 :doc:`here </user/troubleshooting/app-menu-shortcut-troubleshooting>` for troubleshooting.)
|
||||
|
||||
|
||||
|
||||
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
|
||||
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
|
||||
|
||||
|
||||
|
||||
Installing software from other sources
|
||||
--------------------------------------
|
||||
|
||||
|
||||
Some software is not available from the default repositories and must be downloaded and installed from another source. Depending on the installation method, you may either use the updates proxy or direct networking.
|
||||
|
||||
Using the updates proxy
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
If you are still using the distribution package manager, updates will likely still work over the updates proxy without needing to give the TemplateVM direct network access.
|
||||
|
||||
If you are using another installation method fetching remote resources, you might still be able to use the updates proxy by making the tools aware of the proxy. For many tools, it is enough to export the following environment variables in your shell session before proceeding:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
|
||||
HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
|
||||
ALL_PROXY=$HTTP_PROXY all_proxy=$ALL_PROXY \
|
||||
NO_PROXY=127.0.0.1 no_proxy=$NO_PROXY
|
||||
|
||||
|
||||
Using direct networking
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
**Warning:** This method gives your template direct network access, which is `risky <#why-dont-templates-have-normal-network-access>`__. This method is **not** recommended for trusted templates. Moreover, depending on how you install this software, it may not get updated automatically when you :doc:`update Qubes normally </user/how-to-guides/how-to-update>`, which means you may have to update it manually yourself.
|
||||
|
||||
This method assumes that you are trying to follow instructions to install some piece of software in a normal operating system, except *that* operating system is running as a template in Qubes OS.
|
||||
|
||||
1. (Recommended) Clone the desired template (since this new template will probably be less trusted than the original).
|
||||
|
||||
2. (Recommended) In the new template’s **Settings > Basic** tab, change the color label from black to red (or another color that signifies to you that the template is less trusted).
|
||||
|
||||
3. In the new template’s **Settings > Basic** tab, change the **Networking** value from ``default (none) (current)`` to ``sys-firewall`` (or whichever network-providing qube you wish to use).
|
||||
|
||||
4. (Recommended) In the new template’s **Settings > Firewall rules** tab, select “Limit outgoing Internet connections to…” and tick “Allow full access for 5 min.” (This can help in case you forget to remove network access later.)
|
||||
|
||||
5. Follow the normal instructions for installing your software in the new template. For example, open a terminal and enter the commands as instructed. **Warning:** If you don’t fully understand the commands you’re entering, then this can be extremely risky, and the template should be regarded as *completely untrusted*.
|
||||
|
||||
6. (Recommended) In the new template’s **Settings > Basic** tab, change the **Networking** value from ``sys-firewall (current)`` (or whichever network-providing qube you chose) back to ``default (none)``.
|
||||
|
||||
7. Shut down the new template.
|
||||
|
||||
8. Create or assign your desired app qubes to use the new template. If any app qubes were already assigned to the new template, restart them.
|
||||
|
||||
9. (Recommended) In the relevant qubes’ **Settings > 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 :doc:`here </user/troubleshooting/app-menu-shortcut-troubleshooting>` for troubleshooting.)
|
||||
|
||||
|
||||
|
||||
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
|
||||
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
|
||||
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
|
||||
If things are still not working as expected:
|
||||
|
||||
- Review the instructions very carefully, making sure you follow each step.
|
||||
|
||||
- Make sure you **shut down the template after installing your software**.
|
||||
|
||||
- Make sure you **restart your app qube after shutting down your template**.
|
||||
|
||||
- Make sure your app qube is assigned to the right template.
|
||||
|
||||
- If your software requires special files or directories to be persistent, and you’re an advanced user, see :doc:`standalones and HVMs </user/advanced-topics/standalones-and-hvms>` and :doc:`how to make any file persistent (bind-dirs) </user/advanced-topics/bind-dirs>`.
|
||||
|
||||
- :doc:`Ask for help. </introduction/support>`
|
||||
|
||||
|
||||
|
||||
How to update software
|
||||
----------------------
|
||||
|
||||
|
||||
Please see :doc:`How to Update </user/how-to-guides/how-to-update>`.
|
||||
|
||||
Why don't templates have normal network access?
|
||||
-----------------------------------------------
|
||||
|
||||
|
||||
In order to protect you from performing risky activities in templates, they do not have normal network access by default. Instead, templates use an `updates-proxy <#updates-proxy>`__ which allows you to install and update software using the distribution’s package manager over the proxy connection. **The updates proxy is already set up to work automatically out-of-the-box and requires no special action from you.** Most users should simply follow the normal instructions for `installing software from default repositories <#installing-software-from-default-repositories>`__ and :doc:`updating </user/how-to-guides/how-to-update>` software. If your software is not available in the default repositories, see `installing software from other sources <#installing-software-from-other-sources>`__.
|
||||
|
||||
Advanced
|
||||
--------
|
||||
|
||||
|
||||
The following sections cover advanced topics pertaining to installing and updating software in qubes.
|
||||
|
||||
Testing repositories
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
If you wish to install updates that are still in :doc:`testing </user/downloading-installing-upgrading/testing>`, you must enable the appropriate testing repositories.
|
||||
|
||||
**Note:** The following repos are in templates and standalones. For dom0 testing repos, see :ref:`here <user/advanced-topics/how-to-install-software-in-dom0:testing repositories>`. For testing new templates, please see :ref:`here <user/downloading-installing-upgrading/testing:templates>`.
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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``.
|
||||
|
||||
Standalones
|
||||
^^^^^^^^^^^
|
||||
|
||||
|
||||
The process for installing and updating software in :ref:`standalones <user/reference/glossary:standalone>` is the same as described above for templates, except no qubes are based on standalones, so there are no other qubes to restart.
|
||||
|
||||
RPMFusion for Fedora templates
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
If you would like to enable the `RPM Fusion <https://rpmfusion.org/>`__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion <https://rpmfusion.org/>`__ for details):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo dnf config-manager setopt rpmfusion-free.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
|
||||
sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
|
||||
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 template
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Perhaps you’ve just updated your template, 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 template, 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 template was run, but* **not** *before.* This means that if you have already restarted the template, 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-volume revert <template>:root
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reinstall the template
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Please see :doc:`How to Reinstall a template </user/how-to-guides/how-to-reinstall-a-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 template), 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.
|
||||
|
||||
|
||||
|
||||
Updates proxy
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Updates proxy is a service which allows access from package managers configured to use the proxy by default, but can be used by any other program that accepts proxy arguments. The purpose of the proxy, instead of direct network access, is meant to mitigate user errors of using applications such as the browser in the template. Not necessarily what part of the network they can access, but only to applications trusted by the user, configured to use the proxy. The http proxy (tinyproxy) does not filter traffic because it is hard to list all the repository mirrors and keep that list up to date). it also does not cache anything.
|
||||
|
||||
The proxy is running in selected VMs (by default all the NetVMs (1)) and intercepts traffic directed to 127.0.0.1:8082. Thanks to such configuration all the VMs can use the same proxy address. If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf/apt 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``, :doc:`service framework </user/advanced-topics/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.1 (with Whonix installed, but not set as default UpdateVM for all templates):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# 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 app qube you need to take the following steps:
|
||||
|
||||
1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
|
||||
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
|
||||
Dependencies resolved.
|
||||
========================================================================================================
|
||||
Package Arch Version Repository Size
|
||||
========================================================================================================
|
||||
Installing:
|
||||
snapd x86_64 2.56.2-4.fc36 updates 14 M
|
||||
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
|
||||
Installing dependencies:
|
||||
[...]
|
||||
|
||||
Transaction Summary
|
||||
========================================================================================================
|
||||
Install 19 Packages
|
||||
|
||||
Total download size: 27 M
|
||||
Installed size: 88 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:33:05 ago on Thu 03 Nov 2022 04:34:06.
|
||||
Notifying dom0 about installed applications
|
||||
|
||||
Installed:
|
||||
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch
|
||||
[...]
|
||||
Complete!
|
||||
|
||||
You may see the following message:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 template:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
|
||||
|
||||
|
||||
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@snap-demo-app qube ~]$ snap install <package>
|
||||
|
||||
When the install is complete you can close the terminal window.
|
||||
|
||||
3. Refresh the Applications list for the app qube. In the Qubes Menu for the **app qube** 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 app qube’s list of available applications. At this point the snap will be persistent within the app qube and will receive updates when the app qube 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 **app qube**. 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 **app qube** 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@example-app qube ~]$ ls /usr/share/applications/
|
||||
bluetooth-sendto.desktop
|
||||
eog.desktop
|
||||
firefox.desktop
|
||||
...
|
||||
xterm.desktop
|
||||
yelp.desktop
|
||||
|
||||
|
||||
3. Create the autostart directory:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@example-app qube ~]$ 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Note that the app will autostart only when the app qube starts. If you would like the app qube to autostart, select the “Start qube automatically on boot” checkbox in the app qube’s Qube Settings.
|
||||
|
|
@ -1,596 +0,0 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/how-to-organize-your-qubes/
|
||||
title: How to organize your qubes
|
||||
---
|
||||
|
||||
When people first learn about Qubes OS, their initial reaction is often, "Wow,
|
||||
this looks really cool! But... what can I actually *do* with it?" It's not
|
||||
always obvious which qubes you should create, what you should do in each one,
|
||||
and whether your organizational ideas makes sense from a security or usage
|
||||
perspective.
|
||||
|
||||
Each qube is essentially a secure compartment, and you can create as many of
|
||||
them as you like and connect them to each other in various ways. They're sort
|
||||
of like Lego blocks in the sense that you can build whatever you want. But if
|
||||
you're not sure what to build, then this open-ended freedom can be daunting.
|
||||
It's a bit like staring at a blank document when you first sit down to write
|
||||
something. The possibilities are endless, and you may not know where to begin!
|
||||
|
||||
The truth is that no one else can tell you *exactly* how you should organize
|
||||
your qubes, as there is no single correct answer to that question. It depends
|
||||
on your needs, desires, and preferences. Every user's optimal setup will be
|
||||
different. However, what we *can* do is provide you with some illustrative
|
||||
examples based on questionnaires and interviews with Qubes users and
|
||||
developers, as well as our own personal experience and insight from using Qubes
|
||||
over the years. You may be able to adapt some of these examples to fit your own
|
||||
unique situation. More importantly, walking you through the rationale behind
|
||||
various decisions will teach you how to apply the same thought process to your
|
||||
own organizational decisions. Let's begin!
|
||||
|
||||
|
||||
## Alice, the software developer
|
||||
|
||||
Alice is a freelance dev who works on several projects for different clients
|
||||
simultaneously. The projects have varying requirements and often different
|
||||
build environments. She has a separate set of qubes for each project. She keeps
|
||||
them organized by coming up with a naming scheme, such as:
|
||||
|
||||
```
|
||||
clientA-code
|
||||
clientA-build
|
||||
clientA-test
|
||||
clientA-prod
|
||||
projectB-code
|
||||
projectB-build-test
|
||||
projectB-prod
|
||||
...
|
||||
```
|
||||
|
||||
This helps her keep groups of qubes organized in a set. Some of her qubes are
|
||||
based on [Debian templates](/doc/templates/debian/), while others are based on
|
||||
[Fedora templates](/doc/templates/fedora/). The reason for this is that some
|
||||
software packages are more readily available in one distribution as opposed to
|
||||
the other. Alice's setup looks like this:
|
||||
|
||||
[](/attachment/doc/howto_use_qubes_alice_1.png)
|
||||
|
||||
- **Several qubes for writing code.** Here's where she runs her IDE, commits
|
||||
code, and signs her commits. These qubes are based on different templates
|
||||
depending on which tools and which development environment she needs. In
|
||||
general, Alice likes to have a separate qube of this type for each client or
|
||||
each project. This allows her to keep everything organized and avoid
|
||||
accidentally mixing up any access credentials or client code, which could be
|
||||
disastrous. This also allows her to truthfully tell her clients that their
|
||||
code is always securely isolated from all her other clients. She likes to use
|
||||
the [Qubes firewall](/doc/firewall/) to restrict these qubes' network access
|
||||
to only the code repositories she needs in that qube in order to avoid
|
||||
accidentally interacting with anything else on her local network or on the
|
||||
internet. Alice also has some qubes of this type for personal programming
|
||||
projects that she works on just for fun when she has "free time" (whatever
|
||||
that is).
|
||||
|
||||
- **Several qubes for building and testing.** Again, Alice usually likes to
|
||||
have one of these for each client or project in order to keep things
|
||||
organized. However, this can become rather cumbersome and memory-intensive
|
||||
when many such qubes are running at the same time, so Alice will sometimes
|
||||
use the same qube for building and testing, or for multiple projects that
|
||||
require the same environment, when she decides that the marginal benefits of
|
||||
extra compartmentalization aren't worth the trouble. Here's where she pulls
|
||||
any dependencies she needs, compiles her code, runs her build toolchain, and
|
||||
tests her deliverables. In some cases, she finds it useful to use
|
||||
[standalones](/doc/standalones-and-hvms/) for these so that it's easier to
|
||||
quickly [install different pieces of software](/doc/how-to-install-software/)
|
||||
without having to juggle rebooting both the template and an app qube. She
|
||||
also sometimes finds it necessary (or just convenient) to make edits to
|
||||
config files in the root filesystem, and she'd rather not have to worry about
|
||||
losing those changes during an app qube reboot. She knows that she could use
|
||||
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
|
||||
she doesn't want to get bogged down doing with all that and figures it
|
||||
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
|
||||
OS doesn't judge her for this and just gives her the freedom to do things however
|
||||
she likes while keeping everything securely compartmentalized. At times like
|
||||
these, she takes comfort in knowing that things can be messy and disorganized
|
||||
*within* a qube while her overall digital life remains well-organized.
|
||||
|
||||
[](/attachment/doc/howto_use_qubes_alice_2.png)
|
||||
|
||||
- **Several email qubes.** Since Alice is a command-line aficionado, she likes
|
||||
to use a terminal-based email client, so both her work and personal email
|
||||
qubes are based on a template with
|
||||
[Mutt](https://forum.qubes-os.org/t/18989)
|
||||
installed. The email qubes where she sends and receives PGP-signed and
|
||||
encrypted email securely accesses the private keys in her PGP backend qube
|
||||
(more on that below). To guard against malicious attachments, she configured
|
||||
Mutt to open all attachment files in [disposable
|
||||
qubes](/doc/how-to-use-disposables/).
|
||||
|
||||
- **Several qubes for communication tools,** like Signal, Slack, Zoom,
|
||||
Telegram, IRC, and Discord. This is where she teleconferences and chats with
|
||||
clients. She uses [USB passthrough](/doc/how-to-use-usb-devices/) to attach
|
||||
her webcam to each qube as needed and detaches it afterward. Likewise, she
|
||||
gives each qube access to her microphone while it's needed, then removes
|
||||
access afterward. This way, she doesn't have to trust any given video chat
|
||||
program's mute button and doesn't have to worry about being spied on when
|
||||
she's not on a call. She also has a qube for social media platforms like
|
||||
Twitter, Reddit, and Hacker News for networking and keeping up with new
|
||||
developments (or so she claims; in reality, it's mostly for feuds over
|
||||
programming language superiority, Vim vs. Emacs wars, and tabs vs. spaces
|
||||
crusades).
|
||||
|
||||
- **A GPG backend vault.** Vaults are completely offline qubes that are
|
||||
isolated from the network. This particular vault holds Alice's private keys
|
||||
(e.g., for code signing and email) and is securely accessed by several other
|
||||
"frontend" qubes via the [Split GPG](/doc/split-gpg/) system. Split GPG
|
||||
allows only the frontend qubes that Alice explicitly authorizes to have the
|
||||
ability to request PGP operations (e.g., signing and encryption) in the
|
||||
backend vault. Even then, no qube ever has direct access to Alice's private
|
||||
keys except the backend vault itself.
|
||||
|
||||
- **A password manager vault.** This is another completely offline,
|
||||
network-isolated qube where Alice uses her offline password manager,
|
||||
KeePassXC, to store all of her usernames and passwords. She uses the [secure
|
||||
copy and paste](/doc/how-to-copy-and-paste-text/) system to quickly copy
|
||||
credentials into other qubes whenever she needs to log into anything.
|
||||
|
||||
- **Personal qubes.** One of the things Alice loves the most about Qubes is
|
||||
that she can use it for both work *and* personal stuff without having to
|
||||
worry about cross-contamination. Accordingly, she has several qubes that
|
||||
pertain to her personal life. For example, she has an offline vault that
|
||||
holds her medical documents, test results, and vaccination records. She has
|
||||
another offline vault for her government documents, birth certificate, scans
|
||||
of her passport, and so on. She also has some personal social media accounts
|
||||
in a separate qube for keeping up with family members and friends from
|
||||
school.
|
||||
|
||||
When she finishes her work for a given client, Alice sends off her
|
||||
deliverables, [backs up](/doc/how-to-back-up-restore-and-migrate/) the qubes
|
||||
containing the work for that client, and deletes them from her system. If she
|
||||
ever needs those qubes again or just wants to reference them, she can easily
|
||||
restore them from her backup, and the internal state of each one will be
|
||||
exactly as it was when she finished that project.
|
||||
|
||||
|
||||
## Bob, the investigative journalist
|
||||
|
||||
As part of his research and reporting, Bob is frequently forced to interact
|
||||
with suspicious files, often from anonymous sources. For example, he may
|
||||
receive an email with an attachment that claims to be a tip about a story he's
|
||||
working on. Of course, he knows that it could just as easily be malware
|
||||
intended to infect his computer. Qubes OS is essential for Bob, since it allows
|
||||
him to handle all this suspicious data securely, keeping it compartmentalized
|
||||
so that it doesn't risk infecting the rest of his machine.
|
||||
|
||||
Bob isn't a super technical guy. He prefers to keep his tools simple so he can
|
||||
focus on what's important to him: uncovering the truth, exposing the guilty,
|
||||
exonerating the innocent, and shining light on the dark corners of society. His
|
||||
mind doesn't naturally gravitate to the technical details of how his computer
|
||||
works, but he's aware that people are getting hacked all the time and that the
|
||||
nature of his work might make him a target. He wants to protect his sources,
|
||||
his colleagues, his family, and himself; and he understands that computer
|
||||
security is an important part of that. He has a Qubes laptop that he uses only
|
||||
for work, which contains:
|
||||
|
||||
[](/attachment/doc/howto_use_qubes_bob.png)
|
||||
|
||||
- **One offline qube for writing.** It runs only LibreOffice Writer. This is
|
||||
where Bob does all of his writing. This window is usually open side-by-side
|
||||
with another window containing research or material from a source.
|
||||
|
||||
- **Multiple email qubes.** One is for receiving emails from the general
|
||||
public. Another is for emailing his editor and colleagues. Both are based on
|
||||
a [minimal template](/doc/templates/minimal/) with Thunderbird installed.
|
||||
He's configured both to open all attachments in
|
||||
[disposables](/doc/how-to-use-disposables/) that are offline in case an
|
||||
attachment contains a beacon that tries to phone home.
|
||||
|
||||
- **Whonix qubes.** He has the standard `sys-whonix` service qube for providing
|
||||
Torified network access, and he uses disposable `anon-workstation` app qubes
|
||||
for using Tor Browser to do research on stories he's writing. Since the topic
|
||||
is often of a sensitive nature and might implicate powerful individuals, it's
|
||||
important that he be able to conduct this research with a degree of
|
||||
anonymity. He doesn't want the subjects of his investigation to know that
|
||||
he's looking into them. He also doesn't want his network requests being
|
||||
traced back to his work or home IP addresses. Whonix helps with both of these
|
||||
concerns. He also has another Whonix-based disposable template for receiving
|
||||
tips anonymously via Tor, since some high-risk whistleblowers he's interacted
|
||||
with have said that they can't take a chance with any other form of
|
||||
communication.
|
||||
|
||||
- **Two qubes for
|
||||
[Signal](https://forum.qubes-os.org/t/19073).**
|
||||
Bob has two Signal app qubes (both on the same template in which the Signal
|
||||
desktop app is installed). One is linked to his own mobile number for
|
||||
communicating with co-workers and other known, trusted contacts. The other is
|
||||
a public number that serves as an additional way for sources to reach him
|
||||
confidentially. This is especially useful for individuals who don't use Tor
|
||||
but for whom unencrypted communication could be dangerous.
|
||||
|
||||
- **Several data vaults.** When someone sends Bob material that turns out to be
|
||||
useful, or when he comes across useful material while doing his own research,
|
||||
he stores a copy in a completely offline, network-isolated vault qube. Most
|
||||
of these files are PDFs and images, though some are audio files, videos, and
|
||||
text files. Since most of them are from unknown or untrusted sources, Bob
|
||||
isn't sure if it would be safe to put them all in the same vault, so he makes
|
||||
different vaults (usually one for each story or topic) just in case. This has
|
||||
the side benefit of helping to keep things organized.
|
||||
|
||||
- **A [VPN
|
||||
qube](https://forum.qubes-os.org/t/19061)
|
||||
and associated qubes for accessing work resources.** The servers at work can
|
||||
only be accessed from the organization's network, so Bob has certain qubes
|
||||
that are connected to a VPN qube so that he can upload his work and access
|
||||
anything he needs on the local network when he's not physically there.
|
||||
|
||||
- **A password manager vault.** Bob stores all of his login credentials in the
|
||||
default password manager that came with his offline vault qube. He [securely
|
||||
copies and pastes](/doc/how-to-copy-and-paste-text/) them into other qubes as
|
||||
needed.
|
||||
|
||||
A colleague helped Bob set up his Qubes system initially and showed him how to
|
||||
use it. Since Bob's workflow is pretty consistent and straightforward, the way
|
||||
his qubes are organized doesn't change much, and this is just fine by him. His
|
||||
colleague told him to remember a few simple rules: Don't copy or move
|
||||
[text](/doc/how-to-copy-and-paste-text/) or
|
||||
[files](/doc/how-to-copy-and-move-files/) from less trusted to more trusted
|
||||
qubes; [update](/doc/how-to-update/) your system when prompted; and make
|
||||
regular [backups](/doc/how-to-back-up-restore-and-migrate/). Bob doesn't have
|
||||
the need to try out new software or tweak any settings, so he can do everything
|
||||
he needs to do on a daily basis without having to interact with the command
|
||||
line.
|
||||
|
||||
|
||||
## Carol, the investor
|
||||
|
||||
Carol works hard and lives below her means so that she can save money and
|
||||
invest it for her future. She hopes to become financially independent and maybe
|
||||
even retire early someday, and she's decided that her best bet for achieving
|
||||
this is by investing for the long term and allow compounding to do its work.
|
||||
However, after doing some research into her country's consumer financial
|
||||
protection laws, she learned that there's no legal guarantee that customers
|
||||
will be made whole in the event of theft or fraud. The various insurance and
|
||||
protection organizations only guarantee recovery in the case of a financial
|
||||
institution *failing*, which is quite different from an individual customer
|
||||
being hacked. Moreover, even though many financial institutions have their own
|
||||
cybercrime policies, rarely, if ever, do they explicitly guarantee
|
||||
reimbursement in the event that a *customer* gets hacked (rather than the
|
||||
institution itself).
|
||||
|
||||
<div class="alert alert-warning" role="alert">
|
||||
<i class="fa fa-exclamation-circle"></i>
|
||||
Carol looked into how thieves might actually try to steal her hard-earned
|
||||
wealth and was surprised to learn that they have all sorts of ploys that she
|
||||
had never even considered. For example, she had assumed that any theft would,
|
||||
at the bare minimum, have to involve transferring money out of her account.
|
||||
That seems like a safe assumption. But then she read about "pump and dump"
|
||||
attacks, where thieves buy up some penny stock, hack into innocent people's
|
||||
brokerage accounts, then use the victims' funds to buy that same penny stock,
|
||||
"pumping" up its price so that the thieves can "dump" their shares on the
|
||||
market, leaving the victims with worthless shares. No money is ever
|
||||
transferred into or out of the victims' account; it's just used to buy and
|
||||
sell securities. So, all the safeguards preventing new bank accounts from
|
||||
being added or requiring extra approval for outbound transfers do nothing to
|
||||
protect victims' funds in cases like these. And this is just one example!
|
||||
Carol realized that she couldn't assume that existing safeguards against
|
||||
specific, known attacks were enough. She had to think about security at a
|
||||
more fundamental level and design it into her digital life from the ground
|
||||
up.
|
||||
</div>
|
||||
|
||||
After learning about all this, Carol decided that it was ultimately up to her
|
||||
to take care of her own cybersecurity. She couldn't rely on anyone else to do
|
||||
it for her. Sure, most people just use regular consumer tech and will probably
|
||||
end up fine, but, she reminded herself, most people also don't have as much to
|
||||
lose. It's not a risk that she was willing to take with her future, especially
|
||||
knowing that there's probably no government bailout waiting for her and that
|
||||
all the brokerage firms' vaguely reassuring marketing language about
|
||||
cybersecurity isn't legally binding. So, Carol started reading more about
|
||||
computer security and eventually stumbled upon Qubes OS after searching the web
|
||||
for "most secure operating system." She read about how it's designed and why.
|
||||
Although she didn't immediately understand all of the technical details, the
|
||||
fundamental principle of [security-by-compartmentalization](/doc/architecture/)
|
||||
made intuitive sense to her, and the more she learned about the technical
|
||||
aspects, the more she realized that this is what she'd been looking for. Today,
|
||||
her setup looks like this:
|
||||
|
||||
[](/attachment/doc/howto_use_qubes_carol.png)
|
||||
|
||||
- **One qube for each investment firm and bank.** Carol has a few different
|
||||
retirement accounts, brokerage accounts, and bank accounts. She treats each
|
||||
qube like a "secure terminal" for accessing only that one institution's
|
||||
website. She makes her transactions and saves any statements and
|
||||
confirmations she downloads in that qube. She uses the [Qubes
|
||||
firewall](/doc/firewall/) to enable access only to that institution's website
|
||||
in that qube so that she doesn't accidentally visit any others. Since most of
|
||||
what she does involves using websites and PDFs, most of Carol's app qubes are
|
||||
based on a [minimal template](/doc/templates/minimal/) with just a web
|
||||
browser (which doubles as a PDF viewer) and a file manager installed.
|
||||
|
||||
- **One qube for all her credit card accounts.** Carol started to make a
|
||||
separate qube for each credit card account but ultimately decided against it.
|
||||
For one thing, the consumer protections for credit card fraud in her country
|
||||
are much better than for losing assets to theft or fraud in a bank or
|
||||
brokerage account, so the security risk isn't as high. Second, there's
|
||||
actually not a whole lot that an attacker could do with access to her credit
|
||||
cards' online accounts or her old credit card statements, since online access
|
||||
to these generally doesn't allow spending or withdrawing any money. So, even
|
||||
the worst case scenario here wouldn't be catastrophic, unlike with her bank
|
||||
and brokerage accounts. Third, she's not too worried about any of her credit
|
||||
card company websites being used to attack each other or her qube. (As long as
|
||||
it's contained to a single qube, she's fine with that level of risk.) Last,
|
||||
but not least: She has way too many credit cards! While Carol is very frugal,
|
||||
she likes to collect the sign-up bonuses that are offered for opening new
|
||||
cards, so she's accumulated quite a few of them. (However, she's always
|
||||
careful to pay off her balance each month, so she never pays interest. She's
|
||||
also pretty disciplined about only spending what she would have spent
|
||||
*anyway* and not being tempted to spend more just to meet a spending
|
||||
requirement or because she can.) At any rate, Carol has decided that the tiny
|
||||
benefit she stands to gain from having a separate qube for every credit card
|
||||
website wouldn't be worth the hassle of having to manage so many extra qubes.
|
||||
|
||||
- **A qube for credit monitoring, credit reports, and credit history
|
||||
services.** Carol has worked hard to build up a good credit score, and she's
|
||||
concerned about identity theft, so she has one qube dedicated to managing her
|
||||
free credit monitoring services and downloading her free annual credit
|
||||
reports.
|
||||
|
||||
- **Two qubes for taxes.** Carol has a [Windows
|
||||
qube](/doc/templates/windows/)
|
||||
for running her Windows-only tax software. She also has an offline vault
|
||||
where she stores all of her tax-related forms and documents, organized by
|
||||
year.
|
||||
|
||||
- **A qube for financial planning and tracking.** Carol loves spreadsheets, so
|
||||
this offline qube is where she maintains a master spreadsheet to track all of
|
||||
her investments and her savings rate. She also keeps her budgeting
|
||||
spreadsheet, insurance spreadsheet, and written investment policy statement
|
||||
here. This qube is based on a template with some additional productivity
|
||||
software, like LibreOffice and Gnumeric (so that Carol can run her own Monte
|
||||
Carlo simulations).
|
||||
|
||||
- **Various email qubes.** Carol likes to have one email qube for her most
|
||||
important financial accounts; a separate one for her credit cards accounts,
|
||||
online shopping accounts, and insurance companies; and another one for
|
||||
personal email. They're all based on the same template with Thunderbird
|
||||
installed.
|
||||
|
||||
- **A password manager vault.** A network-isolated qube where Carol stores all
|
||||
of her account usernames and passwords in KeePassXC. She uses the [Qubes
|
||||
global clipboard](/doc/how-to-copy-and-paste-text/) to copy and paste them
|
||||
into her other qubes when she needs to log into her accounts.
|
||||
|
||||
|
||||
### Bonus: Carol explores new financial technology
|
||||
|
||||
The vast majority of Carol's assets are in broad-based, low-cost,
|
||||
passively-managed indexed funds. Lately, however, she's started getting
|
||||
interested in cryptocurrency. She's still committed to staying the course with
|
||||
her tried-and-true investments, and she's always been skeptical of new asset
|
||||
classes, especially those that don't generate cash flows or that often seem to
|
||||
be associated with scams or wild speculation. However, she finds the ability to
|
||||
self-custody a portion of her assets appealing from a long-term risk management
|
||||
perspective, particularly as a hedge against certain types of political risk.
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<i class="fa fa-exclamation-triangle"></i>
|
||||
Some of Carol's friends warned her that cryptocurrency is extremely volatile
|
||||
and that hacking and theft are common occurrences. Carol agreed and reassured
|
||||
them that she's educated herself about the risks and will make sure she never
|
||||
invests more than she can afford to lose.
|
||||
</div>
|
||||
|
||||
Carol has added the following to her Qubes setup:
|
||||
|
||||
- **A standalone qube for running Bitcoin Core and an offline wallet vault.**
|
||||
Carol finds the design and security properties of Bitcoin very interesting,
|
||||
so she's experimenting with running a full node. She also created a
|
||||
network-isolated vault in order to try running a copy of Bitcoin Core
|
||||
completely offline as a "cold storage" wallet. She's still trying to figure
|
||||
out how this compares to an actual hardware wallet, paper wallet, or
|
||||
physically air-gapped machine, but she's figures they all have different
|
||||
security properties. She also recently heard about using [Electrum as a
|
||||
"split" wallet in
|
||||
Qubes](https://forum.qubes-os.org/t/19017)
|
||||
and is interested in exploring that further.
|
||||
|
||||
- **Whonix qubes.** Carol read somewhere that Bitcoin nodes should be run over
|
||||
Tor for privacy and security. She found it very convenient that Whonix is
|
||||
already integrated into Qubes, so she simply set her Bitcoin Core "full node"
|
||||
qube to use `sys-whonix` as its networking qube.
|
||||
|
||||
- **Various qubes for DeFi and web3.** Carol has also started getting into DeFi
|
||||
(decentralized finance) and web3 on Ethereum and other smart contract
|
||||
blockchains, so a friend recommended that she get a Ledger hardware wallet.
|
||||
She downloaded the Ledger Live software in an app qube and [set up her system
|
||||
to recognize the
|
||||
Ledger](https://www.kicksecure.com/wiki/Ledger_Hardware_Wallet). She can now
|
||||
start her [USB qube](/doc/usb-qubes/), plug her Ledger into it into a USB
|
||||
port, [use the Qubes Devices widget to attach it](/doc/how-to-use-devices/)
|
||||
to her Ledger Live qube, and from there she can interact with the software.
|
||||
She has a separate qube with the Metamask extension installed in a web
|
||||
browser. She can also use the Qubes Devices widget to attach her Ledger to
|
||||
this qube so she can use Metamask in conjunction with her Ledger to interact
|
||||
with smart contracts and decentralized exchanges.
|
||||
|
||||
- **Various qubes for research and centralized exchanges.** Carol uses these
|
||||
when she wants to check block explorer websites, coin listing and market cap
|
||||
sites, aggregation tools, or just to see what the latest buzz is on Crypto
|
||||
Twitter.
|
||||
|
||||
Carol makes sure to back up all of her qubes that contain important account
|
||||
statements, confirmations, spreadsheets, cryptocurrency wallets, and her
|
||||
password manager vault. If she has extra storage space, she'll also back up her
|
||||
templates and even her Bitcoin full node qube, but she'll skip them if she
|
||||
doesn't have time or space, since she knows she can always recreate them again
|
||||
later and download what she needs from the Internet.
|
||||
|
||||
## John, the teacher
|
||||
|
||||
John is a teacher at a high school, teaching mathematics and history. He is used
|
||||
to setting up his workstation but has not the time or inclination to dive deeper
|
||||
into technical details. So he has installed Qubes in a rather simple way mainly
|
||||
using the installation defaults and just adding a few well-documented features
|
||||
like Split GPG.
|
||||
|
||||
[](/attachment/doc/Simple_Setup.png)
|
||||
|
||||
- **One qube for surfing.** `untrusted` is just the standard qube coming with the Qubes
|
||||
installation, based on the standard Fedora template, but with Thunderbird removed.
|
||||
It is intended for surfing arbitrary locations and may be at risk from some websites.
|
||||
Consequently, it does not keep any valuable data and has no facilities to view or
|
||||
edit office documents.
|
||||
|
||||
- **One offline qube for writing.** `work` is the qube used to edit documents – even
|
||||
MS office documents. It is based on an extended Fedora template containing additional
|
||||
software like LibreOffice, GIMP, Wine, and some Windows applications. It has no netVM
|
||||
and so the risk of an infected document contacting a hacker’s control server is minimized.
|
||||
|
||||
- **One qube for access to trusted servers.** `personal` is used to access only trusted
|
||||
websites like home banking, and the firewall rules for this qube restrict it to these
|
||||
locations. It is based on the same extended Fedora template. John uses this qube for
|
||||
access to his mail server, too, but does not process any documents received by mail
|
||||
in this qube. Any office documents from this qube are only opened in disposables in order
|
||||
to reduce the risk of infection.
|
||||
|
||||
- **One qube for preparing teaching material for his students.** `Windows` is the workhorse
|
||||
used to execute anything needed for teaching. It is based on a Windows 7 template with QWT
|
||||
installed as most of John’s students work with Windows PCs. In order to reduce the risks
|
||||
for such an AppVM, and possible risks caused by it, its internet access is limited, again
|
||||
by a firewall rule, to the servers providing material for teaching.
|
||||
|
||||
- **One qube for protected access to sensible websites.** `whonix` is just the standard
|
||||
AppVM `anon-whonix` based on the `whonix-ws` coming with the Qubes installation. It is
|
||||
used for all accesses over Tor and could as well be replaced by a disposable. John, who is
|
||||
engaged in a project for helping mentally disabled people, uses this qube to avoid tracking
|
||||
his access to the project’s server.
|
||||
|
||||
- **One offline qube for keeping the private PGP key.** `vault` is the key part of Split GPG,
|
||||
just as described in the Qubes documentation, keeping the private PGP key.
|
||||
|
||||
- **One offline qube for permanent data storage.** `storage` finally is a qube based on the
|
||||
standard Debian template and, having no applications and no network access, it is used
|
||||
explicitly and only for permanent data storage, and it is the only qube whose data is regarded
|
||||
as valuable and worth keeping. The Fedora-based qubes might even be configured as disposables, and,
|
||||
if you are willing to accept the rather slow start of Windows, even the qube `Windows` might be
|
||||
created as a disposable.
|
||||
|
||||
This is a rather simplistic design, intended to show that with a minimum effort a decent level
|
||||
of security can be reached, and it is a first implementation showing how John can compartmentalize
|
||||
his digital life, as described in the Qubes documentation. Once the templates are set up with
|
||||
the necessary software like LibreOffice and
|
||||
Split GPG is installed, setting up this structure takes only a few minutes, but it is much more
|
||||
secure than, for instance, a Windows 10 installation based on the available hardening studies,
|
||||
which are quite useless for a practical environment, especially for a user like John.
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
The characters we've met today may be fictional, but they represent the needs
|
||||
of real users like you. You may find that your own needs overlap with more than
|
||||
one of them, in which case you may find it useful to model certain subsets of
|
||||
your overall Qubes system on different examples. You probably also noticed that
|
||||
there are commonalities among them. Most people need to use email, for example,
|
||||
so most people will need at least one email qube and a suitable template to
|
||||
base it on. But not everyone will need [Split GPG](/doc/split-gpg/), and not
|
||||
everyone will want to use the same email client. On the other hand, almost
|
||||
everyone will need a password manager, and it pretty much always makes sense to
|
||||
keep it in an offline, network-isolated vault.
|
||||
|
||||
<div class="alert alert-info" role="alert">
|
||||
<i class="fa fa-circle-info"></i>
|
||||
As you gain experience with Qubes, you may find yourself disagreeing with
|
||||
some of the decisions our fictional friends made. That's okay! There are many
|
||||
different ways to organize a Qubes system, and the most important criterion
|
||||
is that it serves the needs of its owner. Since everyone's needs are
|
||||
different, it's perfectly normal to find yourself doing things a bit
|
||||
differently. Nonetheless, there are some general principles that almost all
|
||||
users find helpful, especially when they're first starting out.
|
||||
</div>
|
||||
|
||||
As you're designing your own Qubes system, keep in mind some of the following
|
||||
lessons from our case studies:
|
||||
|
||||
- **You'll probably change your mind as you go.** You'll realize that one qube
|
||||
should really be split into two, or you'll realize that it doesn't really
|
||||
make sense for two qubes to be separate and that they should instead be
|
||||
merged into one. That's okay. Qubes OS supports your ability to adapt and
|
||||
make changes as you go. Try to maintain a flexible mindset. Things will
|
||||
eventually settle down, and you'll find your groove. Changes to the way you
|
||||
organize your qubes will become less drastic and less frequent over time.
|
||||
|
||||
- **[Make frequent backups.](/doc/how-to-back-up-restore-and-migrate/)** Losing
|
||||
data is never fun, whether it's from an accidental deletion, a system crash,
|
||||
buggy software, or a hardware failure. By getting into the habit of making
|
||||
frequent backups now, you'll save yourself from a lot of pain in the future.
|
||||
Many people never take backups seriously until they suffer catastrophic data
|
||||
loss. That's human nature. If you've experienced that before, then you know
|
||||
the pain. Resolve now never to let it happen again. If you've never
|
||||
experienced it, count yourself lucky and try to learn from the hard-won
|
||||
experience of others. Keeping good backups also allows you to be a bit more
|
||||
free with reorganizations. You can delete qubes that you think you won't need
|
||||
anymore without having to worry that you might need them again someday, since
|
||||
you know you can always restore them from a backup.
|
||||
|
||||
- **Think about which programs you want to run and where you want to store
|
||||
data.** In some cases, it makes sense to run programs and store data in the
|
||||
same qube, for example, if the data is generated by that program. In other
|
||||
cases, it makes sense to have qubes that are exclusively for storing data
|
||||
(e.g., offline data storage vaults) and other qubes that are exclusively for
|
||||
running programs (e.g., web browser-only qubes). Remember that when you make
|
||||
backups, it's only essential to back up data that can't be replaced. This can
|
||||
allow you to achieve minimal backups that are quite small compared to the
|
||||
total size of your installation. Templates, service qubes, and qubes that are
|
||||
used exclusively for running programs and that contain no data don't
|
||||
necessarily have to be backed up as long as you're confident that you can
|
||||
recreate them if needed. This is why it's a good practice to keep notes on
|
||||
which packages you installed in which templates and which customizations and
|
||||
configurations you made. Then you can refer to your notes the next time you
|
||||
need to recreate those qubes. Of course, backing up everything is not a bad
|
||||
idea either. It may require a bit more time and disk space upfront, but for
|
||||
some people, it can be just as important as backing up their irreplaceable
|
||||
data. If your system is mission-critical, and you can't afford more than a
|
||||
certain amount of downtime, then by all means, back everything up!
|
||||
|
||||
- **Introspect on your own behavior.** For example, if you find yourself
|
||||
wanting to find some way to get two qubes to share the same storage space,
|
||||
then this is probably a sign that those two qubes shouldn't be separate in
|
||||
the first place. Sharing storage with each other largely breaks down the
|
||||
secure wall between them, making the separation somewhat pointless. But you
|
||||
probably had a good reason for wanting to make them two separate qubes
|
||||
instead of one to begin with. What exactly was that reason? If it has to do
|
||||
with security, then why are you okay with them freely sharing data that could
|
||||
allow one to infect the other? If you're sure sharing the data wouldn't cause
|
||||
one to infect the other, then what's the security rationale for keeping them
|
||||
separate? By critically examining your own thought process in this way, you
|
||||
can uncover inconsistencies and contradictions that allow you to better
|
||||
refine your system, resulting in a more logical organization that serves your
|
||||
needs better and better over time.
|
||||
|
||||
- **Don't assume that just because *you* can't find a way to attack your
|
||||
system, an adversary wouldn't be able to.** When you're thinking about
|
||||
whether it's a good idea to combine different activities or data in a single
|
||||
qube, for example, you might think, "Well, I can't really see how these pose
|
||||
a risk to each other." The problem is that we often miss attack vectors that
|
||||
sophisticated adversaries spot and can use against us. After all, most people
|
||||
don't think that using a conventional monolithic operating system is risky,
|
||||
when in reality their entire digital life can be taken down in one fell
|
||||
swoop. That's why a good rule of thumb is: When in doubt, compartmentalize.
|
||||
|
||||
- **But remember that compartmentalization --- like everything else --- can be
|
||||
taken to an extreme.** The appropriate amount depends on your temperament,
|
||||
time, patience, experience, risk tolerance, and expertise. In short, there
|
||||
can be such a thing as *too much* compartmentalization! You also have to be
|
||||
able to actually *use* your computer efficiently to do the things you need to
|
||||
do. For example, if you immediately try to jump into doing everything in
|
||||
[disposables](/doc/how-to-use-disposables/) and find yourself constantly
|
||||
losing work (e.g., because you forget to transfer it out before the
|
||||
disposable self-destructs), then that's a big problem! Your extra
|
||||
self-imposed security measures are interfering with the very thing they're
|
||||
designed to protect. At times like these, take a deep breath and remember
|
||||
that you've already reaped the vast majority of the security benefit simply
|
||||
by using Qubes OS in the first place and performing basic
|
||||
compartmentalization (e.g., no random web browsing in templates). Each
|
||||
further step of hardening and compartmentalization beyond that represents an
|
||||
incremental gain with diminishing marginal utility. Try not to allow the
|
||||
perfect to be the enemy of the good!
|
||||
204
user/how-to-guides/how-to-organize-your-qubes.rst
Normal file
204
user/how-to-guides/how-to-organize-your-qubes.rst
Normal file
|
|
@ -0,0 +1,204 @@
|
|||
==========================
|
||||
How to organize your qubes
|
||||
==========================
|
||||
|
||||
|
||||
When people first learn about Qubes OS, their initial reaction is often, “Wow, this looks really cool! But… what can I actually *do* with it?” It’s not always obvious which qubes you should create, what you should do in each one, and whether your organizational ideas makes sense from a security or usage perspective.
|
||||
|
||||
Each qube is essentially a secure compartment, and you can create as many of them as you like and connect them to each other in various ways. They’re sort of like Lego blocks in the sense that you can build whatever you want. But if you’re not sure what to build, then this open-ended freedom can be daunting. It’s a bit like staring at a blank document when you first sit down to write something. The possibilities are endless, and you may not know where to begin!
|
||||
|
||||
The truth is that no one else can tell you *exactly* how you should organize your qubes, as there is no single correct answer to that question. It depends on your needs, desires, and preferences. Every user’s optimal setup will be different. However, what we *can* do is provide you with some illustrative examples based on questionnaires and interviews with Qubes users and developers, as well as our own personal experience and insight from using Qubes over the years. You may be able to adapt some of these examples to fit your own unique situation. More importantly, walking you through the rationale behind various decisions will teach you how to apply the same thought process to your own organizational decisions. Let’s begin!
|
||||
|
||||
Alice, the software developer
|
||||
-----------------------------
|
||||
|
||||
|
||||
Alice is a freelance dev who works on several projects for different clients simultaneously. The projects have varying requirements and often different build environments. She has a separate set of qubes for each project. She keeps them organized by coming up with a naming scheme, such as:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
clientA-code
|
||||
clientA-build
|
||||
clientA-test
|
||||
clientA-prod
|
||||
projectB-code
|
||||
projectB-build-test
|
||||
projectB-prod
|
||||
...
|
||||
|
||||
|
||||
|
||||
This helps her keep groups of qubes organized in a set. Some of her qubes are based on :doc:`Debian templates </user/templates/debian/debian>`, while others are based on :doc:`Fedora templates </user/templates/fedora/fedora>`. The reason for this is that some software packages are more readily available in one distribution as opposed to the other. Alice’s setup looks like this:
|
||||
|
||||
|Alice’s system: diagram 1|
|
||||
|
||||
- **Several qubes for writing code.** Here’s where she runs her IDE, commits code, and signs her commits. These qubes are based on different templates depending on which tools and which development environment she needs. In general, Alice likes to have a separate qube of this type for each client or each project. This allows her to keep everything organized and avoid accidentally mixing up any access credentials or client code, which could be disastrous. This also allows her to truthfully tell her clients that their code is always securely isolated from all her other clients. She likes to use the :doc:`Qubes firewall </user/security-in-qubes/firewall>` to restrict these qubes’ network access to only the code repositories she needs in that qube in order to avoid accidentally interacting with anything else on her local network or on the internet. Alice also has some qubes of this type for personal programming projects that she works on just for fun when she has “free time” (whatever that is).
|
||||
|
||||
- **Several qubes for building and testing.** Again, Alice usually likes to have one of these for each client or project in order to keep things organized. However, this can become rather cumbersome and memory-intensive when many such qubes are running at the same time, so Alice will sometimes use the same qube for building and testing, or for multiple projects that require the same environment, when she decides that the marginal benefits of extra compartmentalization aren’t worth the trouble. Here’s where she pulls any dependencies she needs, compiles her code, runs her build toolchain, and tests her deliverables. In some cases, she finds it useful to use :doc:`standalones </user/advanced-topics/standalones-and-hvms>` for these so that it’s easier to quickly :doc:`install different pieces of software </user/how-to-guides/how-to-install-software>` without having to juggle rebooting both the template and an app qube. She also sometimes finds it necessary (or just convenient) to make edits to config files in the root filesystem, and she’d rather not have to worry about losing those changes during an app qube reboot. She knows that she could use :doc:`bind-dirs </user/advanced-topics/bind-dirs>` to make those changes persistent, but sometimes she doesn’t want to get bogged down doing with all that and figures it wouldn’t be worth it just for this one qube. She’s secretly glad that Qubes OS doesn’t judge her for this and just gives her the freedom to do things however she likes while keeping everything securely compartmentalized. At times like these, she takes comfort in knowing that things can be messy and disorganized *within* a qube while her overall digital life remains well-organized.
|
||||
|
||||
|
||||
|
||||
|Alice’s system: diagram 2|
|
||||
|
||||
- **Several email qubes.** Since Alice is a command-line aficionado, she likes to use a terminal-based email client, so both her work and personal email qubes are based on a template with `Mutt <https://forum.qubes-os.org/t/18989>`__ installed. The email qubes where she sends and receives PGP-signed and encrypted email securely accesses the private keys in her PGP backend qube (more on that below). To guard against malicious attachments, she configured Mutt to open all attachment files in :doc:`disposable qubes </user/how-to-guides/how-to-use-disposables>`.
|
||||
|
||||
- **Several qubes for communication tools,** like Signal, Slack, Zoom, Telegram, IRC, and Discord. This is where she teleconferences and chats with clients. She uses :doc:`USB passthrough </user/how-to-guides/how-to-use-usb-devices>` to attach her webcam to each qube as needed and detaches it afterward. Likewise, she gives each qube access to her microphone while it’s needed, then removes access afterward. This way, she doesn’t have to trust any given video chat program’s mute button and doesn’t have to worry about being spied on when she’s not on a call. She also has a qube for social media platforms like Twitter, Reddit, and Hacker News for networking and keeping up with new developments (or so she claims; in reality, it’s mostly for feuds over programming language superiority, Vim vs. Emacs wars, and tabs vs. spaces crusades).
|
||||
|
||||
- **A GPG backend vault.** Vaults are completely offline qubes that are isolated from the network. This particular vault holds Alice’s private keys (e.g., for code signing and email) and is securely accessed by several other “frontend” qubes via the :doc:`Split GPG </user/security-in-qubes/split-gpg>` system. Split GPG allows only the frontend qubes that Alice explicitly authorizes to have the ability to request PGP operations (e.g., signing and encryption) in the backend vault. Even then, no qube ever has direct access to Alice’s private keys except the backend vault itself.
|
||||
|
||||
- **A password manager vault.** This is another completely offline, network-isolated qube where Alice uses her offline password manager, KeePassXC, to store all of her usernames and passwords. She uses the :doc:`secure copy and paste </user/how-to-guides/how-to-copy-and-paste-text>` system to quickly copy credentials into other qubes whenever she needs to log into anything.
|
||||
|
||||
- **Personal qubes.** One of the things Alice loves the most about Qubes is that she can use it for both work *and* personal stuff without having to worry about cross-contamination. Accordingly, she has several qubes that pertain to her personal life. For example, she has an offline vault that holds her medical documents, test results, and vaccination records. She has another offline vault for her government documents, birth certificate, scans of her passport, and so on. She also has some personal social media accounts in a separate qube for keeping up with family members and friends from school.
|
||||
|
||||
|
||||
|
||||
When she finishes her work for a given client, Alice sends off her deliverables, :doc:`backs up </user/how-to-guides/how-to-back-up-restore-and-migrate>` the qubes containing the work for that client, and deletes them from her system. If she ever needs those qubes again or just wants to reference them, she can easily restore them from her backup, and the internal state of each one will be exactly as it was when she finished that project.
|
||||
|
||||
Bob, the investigative journalist
|
||||
---------------------------------
|
||||
|
||||
|
||||
As part of his research and reporting, Bob is frequently forced to interact with suspicious files, often from anonymous sources. For example, he may receive an email with an attachment that claims to be a tip about a story he’s working on. Of course, he knows that it could just as easily be malware intended to infect his computer. Qubes OS is essential for Bob, since it allows him to handle all this suspicious data securely, keeping it compartmentalized so that it doesn’t risk infecting the rest of his machine.
|
||||
|
||||
Bob isn’t a super technical guy. He prefers to keep his tools simple so he can focus on what’s important to him: uncovering the truth, exposing the guilty, exonerating the innocent, and shining light on the dark corners of society. His mind doesn’t naturally gravitate to the technical details of how his computer works, but he’s aware that people are getting hacked all the time and that the nature of his work might make him a target. He wants to protect his sources, his colleagues, his family, and himself; and he understands that computer security is an important part of that. He has a Qubes laptop that he uses only for work, which contains:
|
||||
|
||||
|A diagram of Bob’s system|
|
||||
|
||||
- **One offline qube for writing.** It runs only LibreOffice Writer. This is where Bob does all of his writing. This window is usually open side-by-side with another window containing research or material from a source.
|
||||
|
||||
- **Multiple email qubes.** One is for receiving emails from the general public. Another is for emailing his editor and colleagues. Both are based on a :doc:`minimal template </user/templates/minimal-templates>` with Thunderbird installed. He’s configured both to open all attachments in :doc:`disposables </user/how-to-guides/how-to-use-disposables>` that are offline in case an attachment contains a beacon that tries to phone home.
|
||||
|
||||
- **Whonix qubes.** He has the standard ``sys-whonix`` service qube for providing Torified network access, and he uses disposable ``anon-workstation`` app qubes for using Tor Browser to do research on stories he’s writing. Since the topic is often of a sensitive nature and might implicate powerful individuals, it’s important that he be able to conduct this research with a degree of anonymity. He doesn’t want the subjects of his investigation to know that he’s looking into them. He also doesn’t want his network requests being traced back to his work or home IP addresses. Whonix helps with both of these concerns. He also has another Whonix-based disposable template for receiving tips anonymously via Tor, since some high-risk whistleblowers he’s interacted with have said that they can’t take a chance with any other form of communication.
|
||||
|
||||
- **Two qubes for** `Signal <https://forum.qubes-os.org/t/19073>`__ **.** Bob has two Signal app qubes (both on the same template in which the Signal desktop app is installed). One is linked to his own mobile number for communicating with co-workers and other known, trusted contacts. The other is a public number that serves as an additional way for sources to reach him confidentially. This is especially useful for individuals who don’t use Tor but for whom unencrypted communication could be dangerous.
|
||||
|
||||
- **Several data vaults.** When someone sends Bob material that turns out to be useful, or when he comes across useful material while doing his own research, he stores a copy in a completely offline, network-isolated vault qube. Most of these files are PDFs and images, though some are audio files, videos, and text files. Since most of them are from unknown or untrusted sources, Bob isn’t sure if it would be safe to put them all in the same vault, so he makes different vaults (usually one for each story or topic) just in case. This has the side benefit of helping to keep things organized.
|
||||
|
||||
- **A** `VPN qube <https://forum.qubes-os.org/t/19061>`__ **and associated qubes for accessing work resources.** The servers at work can only be accessed from the organization’s network, so Bob has certain qubes that are connected to a VPN qube so that he can upload his work and access anything he needs on the local network when he’s not physically there.
|
||||
|
||||
- **A password manager vault.** Bob stores all of his login credentials in the default password manager that came with his offline vault qube. He :doc:`securely copies and pastes </user/how-to-guides/how-to-copy-and-paste-text>` them into other qubes as needed.
|
||||
|
||||
|
||||
|
||||
A colleague helped Bob set up his Qubes system initially and showed him how to use it. Since Bob’s workflow is pretty consistent and straightforward, the way his qubes are organized doesn’t change much, and this is just fine by him. His colleague told him to remember a few simple rules: Don’t copy or move :doc:`text </user/how-to-guides/how-to-copy-and-paste-text>` or :doc:`files </user/how-to-guides/how-to-copy-and-move-files>` from less trusted to more trusted qubes; :doc:`update </user/how-to-guides/how-to-update>` your system when prompted; and make regular :doc:`backups </user/how-to-guides/how-to-back-up-restore-and-migrate>`. Bob doesn’t have the need to try out new software or tweak any settings, so he can do everything he needs to do on a daily basis without having to interact with the command line.
|
||||
|
||||
Carol, the investor
|
||||
-------------------
|
||||
|
||||
|
||||
Carol works hard and lives below her means so that she can save money and invest it for her future. She hopes to become financially independent and maybe even retire early someday, and she’s decided that her best bet for achieving this is by investing for the long term and allow compounding to do its work. However, after doing some research into her country’s consumer financial protection laws, she learned that there’s no legal guarantee that customers will be made whole in the event of theft or fraud. The various insurance and protection organizations only guarantee recovery in the case of a financial institution *failing*, which is quite different from an individual customer being hacked. Moreover, even though many financial institutions have their own cybercrime policies, rarely, if ever, do they explicitly guarantee reimbursement in the event that a *customer* gets hacked (rather than the institution itself).
|
||||
|
||||
.. warning::
|
||||
|
||||
Carol looked into how thieves might actually try to steal her hard-earned wealth and was surprised to learn that they have all sorts of ploys that she had never even considered. For example, she had assumed that any theft would, at the bare minimum, have to involve transferring money out of her account. That seems like a safe assumption. But then she read about “pump and dump” attacks, where thieves buy up some penny stock, hack into innocent people’s brokerage accounts, then use the victims’ funds to buy that same penny stock, “pumping” up its price so that the thieves can “dump” their shares on the market, leaving the victims with worthless shares. No money is ever transferred into or out of the victims’ account; it’s just used to buy and sell securities. So, all the safeguards preventing new bank accounts from being added or requiring extra approval for outbound transfers do nothing to protect victims’ funds in cases like these. And this is just one example! Carol realized that she couldn’t assume that existing safeguards against specific, known attacks were enough. She had to think about security at a more fundamental level and design it into her digital life from the ground up.
|
||||
|
||||
After learning about all this, Carol decided that it was ultimately up to her to take care of her own cybersecurity. She couldn’t rely on anyone else to do it for her. Sure, most people just use regular consumer tech and will probably end up fine, but, she reminded herself, most people also don’t have as much to lose. It’s not a risk that she was willing to take with her future, especially knowing that there’s probably no government bailout waiting for her and that all the brokerage firms’ vaguely reassuring marketing language about cybersecurity isn’t legally binding. So, Carol started reading more about computer security and eventually stumbled upon Qubes OS after searching the web for “most secure operating system.” She read about how it’s designed and why. Although she didn’t immediately understand all of the technical details, the fundamental principle of :doc:`security-by-compartmentalization </developer/system/architecture>` made intuitive sense to her, and the more she learned about the technical aspects, the more she realized that this is what she’d been looking for. Today, her setup looks like this:
|
||||
|
||||
|A diagram of Carol’s system|
|
||||
|
||||
- **One qube for each investment firm and bank.** Carol has a few different retirement accounts, brokerage accounts, and bank accounts. She treats each qube like a “secure terminal” for accessing only that one institution’s website. She makes her transactions and saves any statements and confirmations she downloads in that qube. She uses the :doc:`Qubes firewall </user/security-in-qubes/firewall>` to enable access only to that institution’s website in that qube so that she doesn’t accidentally visit any others. Since most of what she does involves using websites and PDFs, most of Carol’s app qubes are based on a :doc:`minimal template </user/templates/minimal-templates>` with just a web browser (which doubles as a PDF viewer) and a file manager installed.
|
||||
|
||||
- **One qube for all her credit card accounts.** Carol started to make a separate qube for each credit card account but ultimately decided against it. For one thing, the consumer protections for credit card fraud in her country are much better than for losing assets to theft or fraud in a bank or brokerage account, so the security risk isn’t as high. Second, there’s actually not a whole lot that an attacker could do with access to her credit cards’ online accounts or her old credit card statements, since online access to these generally doesn’t allow spending or withdrawing any money. So, even the worst case scenario here wouldn’t be catastrophic, unlike with her bank and brokerage accounts. Third, she’s not too worried about any of her credit card company websites being used to attack each other or her qube. (As long as it’s contained to a single qube, she’s fine with that level of risk.) Last, but not least: She has way too many credit cards! While Carol is very frugal, she likes to collect the sign-up bonuses that are offered for opening new cards, so she’s accumulated quite a few of them. (However, she’s always careful to pay off her balance each month, so she never pays interest. She’s also pretty disciplined about only spending what she would have spent *anyway* and not being tempted to spend more just to meet a spending requirement or because she can.) At any rate, Carol has decided that the tiny benefit she stands to gain from having a separate qube for every credit card website wouldn’t be worth the hassle of having to manage so many extra qubes.
|
||||
|
||||
- **A qube for credit monitoring, credit reports, and credit history services.** Carol has worked hard to build up a good credit score, and she’s concerned about identity theft, so she has one qube dedicated to managing her free credit monitoring services and downloading her free annual credit reports.
|
||||
|
||||
- **Two qubes for taxes.** Carol has a :doc:`Windows qube </user/templates/windows/windows>` for running her Windows-only tax software. She also has an offline vault where she stores all of her tax-related forms and documents, organized by year.
|
||||
|
||||
- **A qube for financial planning and tracking.** Carol loves spreadsheets, so this offline qube is where she maintains a master spreadsheet to track all of her investments and her savings rate. She also keeps her budgeting spreadsheet, insurance spreadsheet, and written investment policy statement here. This qube is based on a template with some additional productivity software, like LibreOffice and Gnumeric (so that Carol can run her own Monte Carlo simulations).
|
||||
|
||||
- **Various email qubes.** Carol likes to have one email qube for her most important financial accounts; a separate one for her credit cards accounts, online shopping accounts, and insurance companies; and another one for personal email. They’re all based on the same template with Thunderbird installed.
|
||||
|
||||
- **A password manager vault.** A network-isolated qube where Carol stores all of her account usernames and passwords in KeePassXC. She uses the :doc:`Qubes global clipboard </user/how-to-guides/how-to-copy-and-paste-text>` to copy and paste them into her other qubes when she needs to log into her accounts.
|
||||
|
||||
|
||||
|
||||
Bonus: Carol explores new financial technology
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
The vast majority of Carol’s assets are in broad-based, low-cost, passively-managed indexed funds. Lately, however, she’s started getting interested in cryptocurrency. She’s still committed to staying the course with her tried-and-true investments, and she’s always been skeptical of new asset classes, especially those that don’t generate cash flows or that often seem to be associated with scams or wild speculation. However, she finds the ability to self-custody a portion of her assets appealing from a long-term risk management perspective, particularly as a hedge against certain types of political risk.
|
||||
|
||||
.. DANGER::
|
||||
|
||||
Some of Carol’s friends warned her that cryptocurrency is extremely volatile and that hacking and theft are common occurrences. Carol agreed and reassured them that she’s educated herself about the risks and will make sure she never invests more than she can afford to lose.
|
||||
|
||||
Carol has added the following to her Qubes setup:
|
||||
|
||||
- **A standalone qube for running Bitcoin Core and an offline wallet vault.** Carol finds the design and security properties of Bitcoin very interesting, so she’s experimenting with running a full node. She also created a network-isolated vault in order to try running a copy of Bitcoin Core completely offline as a “cold storage” wallet. She’s still trying to figure out how this compares to an actual hardware wallet, paper wallet, or physically air-gapped machine, but she’s figures they all have different security properties. She also recently heard about using `Electrum as a “split” wallet in Qubes <https://forum.qubes-os.org/t/19017>`__ and is interested in exploring that further.
|
||||
|
||||
- **Whonix qubes.** Carol read somewhere that Bitcoin nodes should be run over Tor for privacy and security. She found it very convenient that Whonix is already integrated into Qubes, so she simply set her Bitcoin Core “full node” qube to use ``sys-whonix`` as its networking qube.
|
||||
|
||||
- **Various qubes for DeFi and web3.** Carol has also started getting into DeFi (decentralized finance) and web3 on Ethereum and other smart contract blockchains, so a friend recommended that she get a Ledger hardware wallet. She downloaded the Ledger Live software in an app qube and `set up her system to recognize the Ledger <https://www.kicksecure.com/wiki/Ledger_Hardware_Wallet>`__. She can now start her :doc:`USB qube </user/advanced-topics/usb-qubes>`, plug her Ledger into it into a USB port, :doc:`use the Qubes Devices widget to attach it </user/how-to-guides/how-to-use-devices>` to her Ledger Live qube, and from there she can interact with the software. She has a separate qube with the Metamask extension installed in a web browser. She can also use the Qubes Devices widget to attach her Ledger to this qube so she can use Metamask in conjunction with her Ledger to interact with smart contracts and decentralized exchanges.
|
||||
|
||||
- **Various qubes for research and centralized exchanges.** Carol uses these when she wants to check block explorer websites, coin listing and market cap sites, aggregation tools, or just to see what the latest buzz is on Crypto Twitter.
|
||||
|
||||
|
||||
|
||||
Carol makes sure to back up all of her qubes that contain important account statements, confirmations, spreadsheets, cryptocurrency wallets, and her password manager vault. If she has extra storage space, she’ll also back up her templates and even her Bitcoin full node qube, but she’ll skip them if she doesn’t have time or space, since she knows she can always recreate them again later and download what she needs from the Internet.
|
||||
|
||||
John, the teacher
|
||||
-----------------
|
||||
|
||||
|
||||
John is a teacher at a high school, teaching mathematics and history. He is used to setting up his workstation but has not the time or inclination to dive deeper into technical details. So he has installed Qubes in a rather simple way mainly using the installation defaults and just adding a few well-documented features like Split GPG.
|
||||
|
||||
|Simple VM setup|
|
||||
|
||||
- **One qube for surfing.** ``untrusted`` is just the standard qube coming with the Qubes installation, based on the standard Fedora template, but with Thunderbird removed. It is intended for surfing arbitrary locations and may be at risk from some websites. Consequently, it does not keep any valuable data and has no facilities to view or edit office documents.
|
||||
|
||||
- **One offline qube for writing.** ``work`` is the qube used to edit documents – even MS office documents. It is based on an extended Fedora template containing additional software like LibreOffice, GIMP, Wine, and some Windows applications. It has no netVM and so the risk of an infected document contacting a hacker’s control server is minimized.
|
||||
|
||||
- **One qube for access to trusted servers.** ``personal`` is used to access only trusted websites like home banking, and the firewall rules for this qube restrict it to these locations. It is based on the same extended Fedora template. John uses this qube for access to his mail server, too, but does not process any documents received by mail in this qube. Any office documents from this qube are only opened in disposables in order to reduce the risk of infection.
|
||||
|
||||
- **One qube for preparing teaching material for his students.** ``Windows`` is the workhorse used to execute anything needed for teaching. It is based on a Windows 7 template with QWT installed as most of John’s students work with Windows PCs. In order to reduce the risks for such an AppVM, and possible risks caused by it, its internet access is limited, again by a firewall rule, to the servers providing material for teaching.
|
||||
|
||||
- **One qube for protected access to sensible websites.** ``whonix`` is just the standard AppVM ``anon-whonix`` based on the ``whonix-ws`` coming with the Qubes installation. It is used for all accesses over Tor and could as well be replaced by a disposable. John, who is engaged in a project for helping mentally disabled people, uses this qube to avoid tracking his access to the project’s server.
|
||||
|
||||
- **One offline qube for keeping the private PGP key.** ``vault`` is the key part of Split GPG, just as described in the Qubes documentation, keeping the private PGP key.
|
||||
|
||||
- **One offline qube for permanent data storage.** ``storage`` finally is a qube based on the standard Debian template and, having no applications and no network access, it is used explicitly and only for permanent data storage, and it is the only qube whose data is regarded as valuable and worth keeping. The Fedora-based qubes might even be configured as disposables, and, if you are willing to accept the rather slow start of Windows, even the qube ``Windows`` might be created as a disposable.
|
||||
|
||||
|
||||
|
||||
This is a rather simplistic design, intended to show that with a minimum effort a decent level of security can be reached, and it is a first implementation showing how John can compartmentalize his digital life, as described in the Qubes documentation. Once the templates are set up with the necessary software like LibreOffice and Split GPG is installed, setting up this structure takes only a few minutes, but it is much more secure than, for instance, a Windows 10 installation based on the available hardening studies, which are quite useless for a practical environment, especially for a user like John.
|
||||
|
||||
Conclusion
|
||||
----------
|
||||
|
||||
|
||||
The characters we’ve met today may be fictional, but they represent the needs of real users like you. You may find that your own needs overlap with more than one of them, in which case you may find it useful to model certain subsets of your overall Qubes system on different examples. You probably also noticed that there are commonalities among them. Most people need to use email, for example, so most people will need at least one email qube and a suitable template to base it on. But not everyone will need :doc:`Split GPG </user/security-in-qubes/split-gpg>`, and not everyone will want to use the same email client. On the other hand, almost everyone will need a password manager, and it pretty much always makes sense to keep it in an offline, network-isolated vault.
|
||||
|
||||
.. note::
|
||||
|
||||
As you gain experience with Qubes, you may find yourself disagreeing with some of the decisions our fictional friends made. That’s okay! There are many different ways to organize a Qubes system, and the most important criterion is that it serves the needs of its owner. Since everyone’s needs are different, it’s perfectly normal to find yourself doing things a bit differently. Nonetheless, there are some general principles that almost all users find helpful, especially when they’re first starting out.
|
||||
|
||||
As you’re designing your own Qubes system, keep in mind some of the following lessons from our case studies:
|
||||
|
||||
- **You’ll probably change your mind as you go.** You’ll realize that one qube should really be split into two, or you’ll realize that it doesn’t really make sense for two qubes to be separate and that they should instead be merged into one. That’s okay. Qubes OS supports your ability to adapt and make changes as you go. Try to maintain a flexible mindset. Things will eventually settle down, and you’ll find your groove. Changes to the way you organize your qubes will become less drastic and less frequent over time.
|
||||
|
||||
- :doc:`Make frequent backups. </user/how-to-guides/how-to-back-up-restore-and-migrate>` Losing data is never fun, whether it’s from an accidental deletion, a system crash, buggy software, or a hardware failure. By getting into the habit of making frequent backups now, you’ll save yourself from a lot of pain in the future. Many people never take backups seriously until they suffer catastrophic data loss. That’s human nature. If you’ve experienced that before, then you know the pain. Resolve now never to let it happen again. If you’ve never experienced it, count yourself lucky and try to learn from the hard-won experience of others. Keeping good backups also allows you to be a bit more free with reorganizations. You can delete qubes that you think you won’t need anymore without having to worry that you might need them again someday, since you know you can always restore them from a backup.
|
||||
|
||||
- **Think about which programs you want to run and where you want to store data.** In some cases, it makes sense to run programs and store data in the same qube, for example, if the data is generated by that program. In other cases, it makes sense to have qubes that are exclusively for storing data (e.g., offline data storage vaults) and other qubes that are exclusively for running programs (e.g., web browser-only qubes). Remember that when you make backups, it’s only essential to back up data that can’t be replaced. This can allow you to achieve minimal backups that are quite small compared to the total size of your installation. Templates, service qubes, and qubes that are used exclusively for running programs and that contain no data don’t necessarily have to be backed up as long as you’re confident that you can recreate them if needed. This is why it’s a good practice to keep notes on which packages you installed in which templates and which customizations and configurations you made. Then you can refer to your notes the next time you need to recreate those qubes. Of course, backing up everything is not a bad idea either. It may require a bit more time and disk space upfront, but for some people, it can be just as important as backing up their irreplaceable data. If your system is mission-critical, and you can’t afford more than a certain amount of downtime, then by all means, back everything up!
|
||||
|
||||
- **Introspect on your own behavior.** For example, if you find yourself wanting to find some way to get two qubes to share the same storage space, then this is probably a sign that those two qubes shouldn’t be separate in the first place. Sharing storage with each other largely breaks down the secure wall between them, making the separation somewhat pointless. But you probably had a good reason for wanting to make them two separate qubes instead of one to begin with. What exactly was that reason? If it has to do with security, then why are you okay with them freely sharing data that could allow one to infect the other? If you’re sure sharing the data wouldn’t cause one to infect the other, then what’s the security rationale for keeping them separate? By critically examining your own thought process in this way, you can uncover inconsistencies and contradictions that allow you to better refine your system, resulting in a more logical organization that serves your needs better and better over time.
|
||||
|
||||
- **Don’t assume that just because you can’t find a way to attack your system, an adversary wouldn’t be able to.** When you’re thinking about whether it’s a good idea to combine different activities or data in a single qube, for example, you might think, “Well, I can’t really see how these pose a risk to each other.” The problem is that we often miss attack vectors that sophisticated adversaries spot and can use against us. After all, most people don’t think that using a conventional monolithic operating system is risky, when in reality their entire digital life can be taken down in one fell swoop. That’s why a good rule of thumb is: When in doubt, compartmentalize.
|
||||
|
||||
- **But remember that compartmentalization — like everything else — can be taken to an extreme.** The appropriate amount depends on your temperament, time, patience, experience, risk tolerance, and expertise. In short, there can be such a thing as *too much* compartmentalization! You also have to be able to actually *use* your computer efficiently to do the things you need to do. For example, if you immediately try to jump into doing everything in :doc:`disposables </user/how-to-guides/how-to-use-disposables>` and find yourself constantly losing work (e.g., because you forget to transfer it out before the disposable self-destructs), then that’s a big problem! Your extra self-imposed security measures are interfering with the very thing they’re designed to protect. At times like these, take a deep breath and remember that you’ve already reaped the vast majority of the security benefit simply by using Qubes OS in the first place and performing basic compartmentalization (e.g., no random web browsing in templates). Each further step of hardening and compartmentalization beyond that represents an incremental gain with diminishing marginal utility. Try not to allow the perfect to be the enemy of the good!
|
||||
|
||||
|
||||
|
||||
.. |Alice’s system: diagram 1| image:: /attachment/doc/howto_use_qubes_alice_1.png
|
||||
|
||||
|
||||
.. |Alice’s system: diagram 2| image:: /attachment/doc/howto_use_qubes_alice_2.png
|
||||
|
||||
|
||||
.. |A diagram of Bob’s system| image:: /attachment/doc/howto_use_qubes_bob.png
|
||||
|
||||
|
||||
.. |A diagram of Carol’s system| image:: /attachment/doc/howto_use_qubes_carol.png
|
||||
|
||||
|
||||
.. |Simple VM setup| image:: /attachment/doc/Simple_Setup.png
|
||||
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/how-to-reinstall-a-template/
|
||||
redirect_from:
|
||||
- /doc/reinstall-template/
|
||||
- /doc/whonix/reinstall/
|
||||
ref: 128
|
||||
title: How to reinstall a template
|
||||
---
|
||||
|
||||
If you suspect your [template](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any template that was installed from the Qubes repository.
|
||||
|
||||
Automatic Method
|
||||
----------------
|
||||
|
||||
First, copy any files that you wish to keep from the template's `/home` and `/rw` folders to a safe storage location.
|
||||
Then, in a dom0 terminal, run:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
|
||||
```
|
||||
|
||||
Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall.
|
||||
For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template.
|
||||
Only one template can be reinstalled at a time.
|
||||
|
||||
Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository.
|
||||
In this case, you can specify `upgrade` as the action instead and the newer version will be used.
|
||||
The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`.
|
||||
Note that the `upgrade`, `upgrade-to`, and `downgrade` commands are only supported under Fedora based UpdateVMs.
|
||||
If you receive a message about them being unsupported, review the manual reinstallation method below.
|
||||
|
||||
**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo.
|
||||
For example:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
|
||||
```
|
||||
|
||||
**Note:** VMs that are using the reinstalled template will not be affected until they are restarted.
|
||||
|
||||
Manual Method
|
||||
-------------
|
||||
|
||||
In what follows, the term "target template" refers to whichever template you want to reinstall.
|
||||
If you want to reinstall more than one template, repeat these instructions for each one.
|
||||
|
||||
1. Clone the existing target template.
|
||||
|
||||
|
||||
- This can be a good idea if you've customized the existing template and want to keep your customizations.
|
||||
On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
|
||||
|
||||
2. Temporarily change all VMs based on the target template to the new clone template, or remove them.
|
||||
|
||||
|
||||
- This can be a good idea if you have user data in these VMs that you want to keep.
|
||||
On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
|
||||
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
|
||||
|
||||
3. Uninstall the target template from dom0:
|
||||
|
||||
```
|
||||
$ sudo dnf remove <template-package-name>
|
||||
```
|
||||
|
||||
For example, to uninstall the `whonix-gw` template:
|
||||
|
||||
```
|
||||
$ sudo dnf remove qubes-template-whonix-gw
|
||||
```
|
||||
|
||||
4. Reinstall the target template in dom0:
|
||||
|
||||
```shell_session
|
||||
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
|
||||
<template-package-name>
|
||||
```
|
||||
|
||||
For example, to install the `whonix-gw` template:
|
||||
|
||||
```shell_session
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
|
||||
qubes-template-whonix-gw
|
||||
```
|
||||
|
||||
5. If you temporarily changed all VMs based on the target template to the clone template in step 3, change them back to the new target template now.
|
||||
If you instead removed all VMs based on the old target template, you can recreate your desired VMs from the newly reinstalled target template now.
|
||||
|
||||
6. Delete the cloned template.
|
||||
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the
|
||||
command `qvm-remove <vm-name>` in dom0.
|
||||
86
user/how-to-guides/how-to-reinstall-a-template.rst
Normal file
86
user/how-to-guides/how-to-reinstall-a-template.rst
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
===========================
|
||||
How to reinstall a template
|
||||
===========================
|
||||
|
||||
|
||||
If you suspect your :doc:`template </user/templates/templates>` is broken, misconfigured, or compromised, you can reinstall any template that was installed from the Qubes repository.
|
||||
|
||||
Automatic Method
|
||||
----------------
|
||||
|
||||
|
||||
First, copy any files that you wish to keep from the template’s ``/home`` and ``/rw`` folders to a safe storage location. Then, in a dom0 terminal, run:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
|
||||
|
||||
|
||||
|
||||
Replace ``qubes-template-package-name`` with the name of the *package* of the template you wish to reinstall. For example, use ``qubes-template-fedora-25`` if you wish to reinstall the ``fedora-25`` template. Only one template can be reinstalled at a time.
|
||||
|
||||
Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository. In this case, you can specify ``upgrade`` as the action instead and the newer version will be used. The other ``dnf`` package actions that are supported in addition to ``reinstall`` and ``upgrade`` are ``upgrade-to`` and ``downgrade``. Note that the ``upgrade``, ``upgrade-to``, and ``downgrade`` commands are only supported under Fedora based UpdateVMs. If you receive a message about them being unsupported, review the manual reinstallation method below.
|
||||
|
||||
**Reminder:** If you’re trying to reinstall a template that is not in an enabled repo, you must enable that repo. For example:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
|
||||
|
||||
|
||||
|
||||
**Note:** VMs that are using the reinstalled template will not be affected until they are restarted.
|
||||
|
||||
Manual Method
|
||||
-------------
|
||||
|
||||
|
||||
In what follows, the term “target template” refers to whichever template you want to reinstall. If you want to reinstall more than one template, repeat these instructions for each one.
|
||||
|
||||
1. Clone the existing target template.
|
||||
|
||||
- This can be a good idea if you’ve customized the existing template and want to keep your customizations. On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
|
||||
|
||||
|
||||
|
||||
2. Temporarily change all VMs based on the target template to the new clone template, or remove them.
|
||||
|
||||
- This can be a good idea if you have user data in these VMs that you want to keep. On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command ``qvm-remove <vm-name>`` in dom0.
|
||||
|
||||
|
||||
|
||||
3. Uninstall the target template from dom0:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo dnf remove <template-package-name>
|
||||
|
||||
|
||||
For example, to uninstall the ``whonix-gw`` template:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo dnf remove qubes-template-whonix-gw
|
||||
|
||||
|
||||
|
||||
4. Reinstall the target template in dom0:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
|
||||
<template-package-name>
|
||||
|
||||
For example, to install the ``whonix-gw`` template:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
|
||||
qubes-template-whonix-gw
|
||||
|
||||
|
||||
5. If you temporarily changed all VMs based on the target template to the clone template in step 3, change them back to the new target template now. If you instead removed all VMs based on the old target template, you can recreate your desired VMs from the newly reinstalled target template now.
|
||||
|
||||
6. Delete the cloned template. You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command ``qvm-remove <vm-name>`` in dom0.
|
||||
|
||||
|
||||
|
|
@ -1,205 +0,0 @@
|
|||
---
|
||||
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-releases/#qubes-os). If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see [Upgrade guides](/doc/upgrade/).*
|
||||
|
||||
It is important to keep your Qubes OS system up-to-date to ensure you have the latest security updates, as well as the latest non-security enhancements and bug fixes.
|
||||
|
||||
Fully updating your Qubes OS system means updating:
|
||||
|
||||
- [dom0](/doc/glossary/#dom0)
|
||||
- [templates](/doc/glossary/#template)
|
||||
- [standalones](/doc/glossary/#standalone) (if you have any)
|
||||
- [firmware](/doc/glossary/#firmware)
|
||||
|
||||
## Security updates
|
||||
|
||||
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a [Qubes Security Bulletin (QSB)](/security/qsb/) 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, as described below, 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.
|
||||
|
||||
## Checking for updates
|
||||
|
||||
By default, the **Qubes Update** tool will appear as an icon in the Notification Area when updates are available.
|
||||
|
||||
[](/attachment/doc/r4.2-qube-updates-available.png)
|
||||
|
||||
However, you can also start the tool manually by selecting it in the Applications Menu under "Qubes Tools." Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting all desired items from the list and clicking "Update".
|
||||
|
||||
<div class="alert alert-info" role="alert">
|
||||
<i class="fa fa-question-circle"></i>
|
||||
For information about how templates download updates, please see <a href="/doc/how-to-install-software/#why-dont-templates-have-normal-network-access">Why don't templates have normal network access?</a> and the <a href="/doc/how-to-install-software/#updates-proxy">Updates proxy</a>.
|
||||
</div>
|
||||
|
||||
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the "last checked" column. If updates are available for any qube, you will receive a notification as described above, and in the "Updates available" column you will see "YES" for that qube(s). If the update check did not find any new updates, "NO" will appear in the column. Respectively, for qubes that are no longer supported, "OBSOLETE" will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the "Updates available" column will be set to "MAYBE".
|
||||
|
||||
## Installing updates
|
||||
|
||||
The standard way to install updates is with the **Qubes Update** tool. (However, you can also perform the same action via the [command-line interface](#command-line-interface).)
|
||||
|
||||
[](/attachment/doc/r4.2-software-update.png)
|
||||
|
||||
You can easily decide which qubes to update by clicking on the checkbox in the column header. At startup, only the qubes for which updates are known are selected for updating, but clicking on the mentioned checkbox will also select all qubes with the "MAYBE" status. It is recommended to update all qubes with the statuses "YES" and "MAYBE".
|
||||
|
||||
Then simply follow the on-screen instructions, and the tool will download and install all available updates for you. Note that if you are downloading updates over Tor (`sys-whonix`), this can take a very long time, especially if there are a lot of updates available.
|
||||
|
||||
## Restarting after updating
|
||||
|
||||
Certain updates require certain components to be restarted in order for the updates to take effect:
|
||||
|
||||
- QSBs may instruct you to restart certain components after installing updates.
|
||||
- Dom0 should be restarted after all **Xen** and **kernel** updates.
|
||||
- On Intel systems, dom0 should be restarted after all `microcode_ctl` updates.
|
||||
- On AMD systems, dom0 should be restarted after all `linux-firmware` updates.
|
||||
- After updating a template, first shut down the template, then restart all running qubes based on that template. The updater will try to do this for you automatically in the last step of updating. Remember to save all your data before restarting!
|
||||
|
||||
## AEM resealing after updating
|
||||
|
||||
If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal" after certain updates. It's common for QSBs to contain instructions to this effect. See the relevant QSB and the [AEM `README`](https://github.com/QubesOS/qubes-antievilmaid/blob/main/README) for details.
|
||||
|
||||
## Command-line interface
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<i class="fa fa-exclamation-triangle"></i>
|
||||
<b>Warning:</b> Updating with direct commands such as <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/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
|
||||
</div>
|
||||
|
||||
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
|
||||
|
||||
- If you are using Salt, one can use the following two Salt states.
|
||||
|
||||
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
|
||||
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
|
||||
|
||||
- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
|
||||
|
||||
Using either of these methods has the same effect as updating via the Qubes Update tool.
|
||||
|
||||
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
|
||||
|
||||
## Upgrading to avoid EOL
|
||||
|
||||
The above covers updating *within* a given operating system (OS) release. Eventually, however, most OS releases will reach **end-of-life (EOL)**, after which point they will no longer be supported. This applies to Qubes OS itself as well as OSes used in [templates](/doc/templates/) (and [standalones](/doc/standalones-and-hvms/), if you have any).
|
||||
|
||||
**It's very important that you use only supported releases so that you continue to receive security updates.** This means that you *must* periodically upgrade Qubes OS and your templates before they reach EOL. You can always see which versions of Qubes OS and select templates are supported on [Supported releases](/doc/supported-releases/).
|
||||
|
||||
In the case of Qubes OS itself, we will make an [announcement](/news/categories/#releases) when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
|
||||
|
||||
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/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 OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
|
||||
|
||||
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-releases/#note-on-dom0-and-eol).
|
||||
|
||||
## Microcode Updates
|
||||
|
||||
x86\_64 CPUs contain special low-level software called **microcode**, which
|
||||
is used to implement certain instructions and runs on various processors that
|
||||
are outside of Qubes OS's control. Most microcode is in an on-CPU ROM, but
|
||||
CPU vendors provide patches that modify small parts of this microcode. These
|
||||
patches can be loaded from the BIOS or by the OS.
|
||||
|
||||
The fixes for some QSBs require a microcode update to work. Furthermore,
|
||||
microcode updates will sometimes fix vulnerabilities "silently". This means
|
||||
that the vulnerability impacts the security of Qubes OS, but the Qubes OS
|
||||
Security Team is not informed that a vulnerability exists, so no QSB is ever
|
||||
issued. Therefore, it is critical to update microcode.
|
||||
|
||||
Intel provides microcode updates for all of their CPUs in a public Git
|
||||
repository, and allows OS vendors (such as Qubes OS) to distribute the updates
|
||||
free of charge. AMD, however, only provides microcode for server CPUs.
|
||||
AMD client CPUs can only receive microcode updates via a system firmware
|
||||
update. Worse, there is often a significant delay between when a vulnerability
|
||||
becomes public and when firmware that includes updated microcode is available
|
||||
to Qubes OS users. This is why Qubes OS recommends Intel CPUs instead of
|
||||
AMD CPUs.
|
||||
|
||||
## Firmware updates
|
||||
|
||||
Modern computers have many processors other than those that run Qubes OS.
|
||||
Furthermore, the main processor cores also run firmware, which is used to
|
||||
boot the system and often provides some services at runtime. Both kinds
|
||||
of firmware can have bugs and vulnerabilities, so it is critical to keep
|
||||
them updated.
|
||||
|
||||
Some firmware is loaded by the OS at runtime.
|
||||
Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
|
||||
Other devices have persistent firmware that must be updated manually.
|
||||
|
||||
Qubes OS supports updating system firmware in three different ways.
|
||||
Which one to use depends on the device whose firmware is being updated.
|
||||
|
||||
- If a device is attached to a domU, it should be updated using **fwupd**.
|
||||
fwupd is included in both Debian and Fedora repositories.
|
||||
It requires Internet access to use, but you can use the updates proxy if you
|
||||
need to update firmware from an offline VM. You can use either the
|
||||
command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
|
||||
|
||||
- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
|
||||
This tool uses fwupd internally, but it fetches firmware and metadata over
|
||||
qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
|
||||
Unfortunately, their is no graphical interface for this tool yet.
|
||||
|
||||
- System76 systems use a special update tool which is simpler than fwupd.
|
||||
Support for this tool is currently in progress. Once it is finished,
|
||||
users will be able to use the **system76-firmware-cli** command-line
|
||||
tool to update the firmware.
|
||||
|
||||
Firmware updates are important on all systems, but they are especially
|
||||
important on AMD client systems. These do not support loading microcode from
|
||||
the OS, so firmware updates are the **only** way to obtain microcode updates.
|
||||
|
||||
## Firmware update methods
|
||||
|
||||
As of Qubes 4.2, firmware updates can be performed from within Qubes for [fwupd-supported computers](https://fwupd.org/).
|
||||
|
||||
### In dom0
|
||||
|
||||
First, ensure that your UpdateVM
|
||||
contains the `fwupd-qubes-vm` package. This package is installed
|
||||
by default for qubes with `qubes-vm-recommended` packages.
|
||||
|
||||
In a dom0 terminal, install the `fwupd-qubes-dom0` package:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update fwupd-qubes-dom0
|
||||
```
|
||||
|
||||
Once the package is installed:
|
||||
|
||||
```
|
||||
$ sudo qubes-fwupdmgr get-devices
|
||||
```
|
||||
|
||||
Examine the terminal output for warnings or errors.
|
||||
You may see the following warning:
|
||||
|
||||
```
|
||||
WARNING: UEFI capsule updates not available or enabled
|
||||
```
|
||||
If so, [adjust your BIOS settings](https://github.com/fwupd/fwupd/wiki/PluginFlag:capsules-unsupported) to enable UEFI updates. This setting is sometimes named "Windows UEFI Firmware Update."
|
||||
|
||||
Once resolved, in a dom0 terminal:
|
||||
|
||||
```
|
||||
$ sudo qubes-fwupdmgr get-devices
|
||||
$ sudo qubes-fwupdmgr refresh
|
||||
$ sudo qubes-fwupdmgr update
|
||||
```
|
||||
|
||||
A numbered list of devices with available updates will be presented. Ensure your computer is plugged in to a stable power source, then type the list number of the device you wish to update. If a reboot is required, you will be prompted at the console to confirm.
|
||||
|
||||
Repeat the update process for any additional devices on your computer.
|
||||
|
||||
### In other qubes
|
||||
|
||||
Devices that are attached to non-dom0 qubes can be updated via a graphical tool for `fwupd`, or via the `fwupdmgr` commandline tool.
|
||||
|
||||
To update the firmware of offline qubes, use the [Updates proxy](/doc/how-to-install-software/#updates-proxy).
|
||||
|
||||
### Computers without fwupd support
|
||||
|
||||
For computers that do not have firmware update support via `fwupd`, follow the firmware update instructions on the manufacturer's website. Verify the authenticity of any firmware updates you apply.
|
||||
218
user/how-to-guides/how-to-update.rst
Normal file
218
user/how-to-guides/how-to-update.rst
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
=============
|
||||
How to update
|
||||
=============
|
||||
|
||||
|
||||
*This page is about updating your system while staying on the same* :ref:`supported version of Qubes OS <user/downloading-installing-upgrading/supported-releases:qubes os>` *. If you’re instead looking to upgrade from your current version of Qubes OS to a newer version, see* :doc:`Upgrade guides </user/downloading-installing-upgrading/upgrade/upgrade>` *.*
|
||||
|
||||
It is important to keep your Qubes OS system up-to-date to ensure you have the latest security updates, as well as the latest non-security enhancements and bug fixes.
|
||||
|
||||
Fully updating your Qubes OS system means updating:
|
||||
|
||||
- :ref:`dom0 <user/reference/glossary:dom0>`
|
||||
|
||||
- :ref:`templates <user/reference/glossary:template>`
|
||||
|
||||
- :ref:`standalones <user/reference/glossary:standalone>` (if you have any)
|
||||
|
||||
- :ref:`firmware <user/reference/glossary:firmware>`
|
||||
|
||||
|
||||
|
||||
Security updates
|
||||
----------------
|
||||
|
||||
|
||||
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a `Qubes Security Bulletin (QSB) <https://www.qubes-os.org/security/qsb/>`__ via the `Qubes Security Pack (qubes-secpack) <https://www.qubes-os.org/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, as described below, 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.
|
||||
|
||||
Checking for updates
|
||||
--------------------
|
||||
|
||||
|
||||
By default, the **Qubes Update** tool will appear as an icon in the Notification Area when updates are available.
|
||||
|
||||
|Qube Updates Available|
|
||||
|
||||
However, you can also start the tool manually by selecting it in the Applications Menu under “Qubes Tools.” Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting all desired items from the list and clicking “Update”.
|
||||
|
||||
.. note::
|
||||
|
||||
For information about how templates download updates, please see :ref:`Why don’t templates have normal network access? <user/how-to-guides/how-to-install-software:why don't templates have normal network access?>` and the :ref:`Updates proxy <user/how-to-guides/how-to-install-software:updates proxy>` .
|
||||
|
||||
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the “last checked” column. If updates are available for any qube, you will receive a notification as described above, and in the “Updates available” column you will see “YES” for that qube(s). If the update check did not find any new updates, “NO” will appear in the column. Respectively, for qubes that are no longer supported, “OBSOLETE” will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the “Updates available” column will be set to “MAYBE”.
|
||||
|
||||
Installing updates
|
||||
------------------
|
||||
|
||||
|
||||
The standard way to install updates is with the **Qubes Update** tool. (However, you can also perform the same action via the `command-line interface <#command-line-interface>`__.)
|
||||
|
||||
|Qubes Update|
|
||||
|
||||
You can easily decide which qubes to update by clicking on the checkbox in the column header. At startup, only the qubes for which updates are known are selected for updating, but clicking on the mentioned checkbox will also select all qubes with the “MAYBE” status. It is recommended to update all qubes with the statuses “YES” and “MAYBE”.
|
||||
|
||||
Then simply follow the on-screen instructions, and the tool will download and install all available updates for you. Note that if you are downloading updates over Tor (``sys-whonix``), this can take a very long time, especially if there are a lot of updates available.
|
||||
|
||||
Restarting after updating
|
||||
-------------------------
|
||||
|
||||
|
||||
Certain updates require certain components to be restarted in order for the updates to take effect:
|
||||
|
||||
- QSBs may instruct you to restart certain components after installing updates.
|
||||
|
||||
- Dom0 should be restarted after all **Xen** and **kernel** updates.
|
||||
|
||||
- On Intel systems, dom0 should be restarted after all ``microcode_ctl`` updates.
|
||||
|
||||
- On AMD systems, dom0 should be restarted after all ``linux-firmware`` updates.
|
||||
|
||||
- After updating a template, first shut down the template, then restart all running qubes based on that template. The updater will try to do this for you automatically in the last step of updating. Remember to save all your data before restarting!
|
||||
|
||||
|
||||
|
||||
AEM resealing after updating
|
||||
----------------------------
|
||||
|
||||
|
||||
If you use :doc:`Anti Evil Maid (AEM) </user/security-in-qubes/anti-evil-maid>`, you’ll have to “reseal” after certain updates. It’s common for QSBs to contain instructions to this effect. See the relevant QSB and the `AEM README <https://github.com/QubesOS/qubes-antievilmaid/blob/main/README>`__ for details.
|
||||
|
||||
Command-line interface
|
||||
----------------------
|
||||
|
||||
|
||||
.. DANGER::
|
||||
|
||||
**Warning:** Updating with direct commands such as dnf update and apt update is not recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the **Qubes Update** tool or its command-line equivalents, as described below. (By contrast, :doc:`installing </user/how-to-guides/how-to-install-software>` packages using direct package manager commands is fine.)
|
||||
|
||||
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
|
||||
|
||||
- If you are using Salt, one can use the following two Salt states.
|
||||
|
||||
- :ref:`update.qubes-dom0 <user/advanced-topics/salt:\`\`update.qubes-dom0\`\`>`
|
||||
|
||||
- :ref:`update.qubes-vm <user/advanced-topics/salt:\`\`update.qubes-vm\`\`>`
|
||||
|
||||
- Alternatively, use ``qubes-dom0-update`` to update dom0, and use ``qubes-vm-update`` to update domUs.
|
||||
|
||||
|
||||
|
||||
Using either of these methods has the same effect as updating via the Qubes Update tool.
|
||||
|
||||
Advanced users may also be interested in learning :doc:`how to enable the testing repos </user/downloading-installing-upgrading/testing>`.
|
||||
|
||||
Upgrading to avoid EOL
|
||||
----------------------
|
||||
|
||||
|
||||
The above covers updating *within* a given operating system (OS) release. Eventually, however, most OS releases will reach **end-of-life (EOL)**, after which point they will no longer be supported. This applies to Qubes OS itself as well as OSes used in :doc:`templates </user/templates/templates>` (and :doc:`standalones </user/advanced-topics/standalones-and-hvms>`, if you have any).
|
||||
|
||||
**It’s very important that you use only supported releases so that you continue to receive security updates.** This means that you *must* periodically upgrade Qubes OS and your templates before they reach EOL. You can always see which versions of Qubes OS and select templates are supported on :doc:`Supported releases </user/downloading-installing-upgrading/supported-releases>`.
|
||||
|
||||
In the case of Qubes OS itself, we will make an `announcement <https://www.qubes-os.org/news/categories/>`__ when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide :doc:`instructions for upgrading to the next stable supported Qubes OS release </user/downloading-installing-upgrading/upgrade/upgrade>`.
|
||||
|
||||
Periodic upgrades are also important for templates. For example, you might be using a :doc:`Fedora template </user/templates/fedora/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 OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the :ref:`supported template releases <user/downloading-installing-upgrading/supported-releases:templates>`).
|
||||
|
||||
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which :ref:`doesn’t have to be upgraded <user/downloading-installing-upgrading/supported-releases:note on dom0 and eol>`.
|
||||
|
||||
Microcode Updates
|
||||
-----------------
|
||||
|
||||
|
||||
x86_64 CPUs contain special low-level software called **microcode**, which is used to implement certain instructions and runs on various processors that are outside of Qubes OS’s control. Most microcode is in an on-CPU ROM, but CPU vendors provide patches that modify small parts of this microcode. These patches can be loaded from the BIOS or by the OS.
|
||||
|
||||
The fixes for some QSBs require a microcode update to work. Furthermore, microcode updates will sometimes fix vulnerabilities “silently”. This means that the vulnerability impacts the security of Qubes OS, but the Qubes OS Security Team is not informed that a vulnerability exists, so no QSB is ever issued. Therefore, it is critical to update microcode.
|
||||
|
||||
Intel provides microcode updates for all of their CPUs in a public Git repository, and allows OS vendors (such as Qubes OS) to distribute the updates free of charge. AMD, however, only provides microcode for server CPUs. AMD client CPUs can only receive microcode updates via a system firmware update. Worse, there is often a significant delay between when a vulnerability becomes public and when firmware that includes updated microcode is available to Qubes OS users. This is why Qubes OS recommends Intel CPUs instead of AMD CPUs.
|
||||
|
||||
Firmware updates
|
||||
----------------
|
||||
|
||||
|
||||
Modern computers have many processors other than those that run Qubes OS. Furthermore, the main processor cores also run firmware, which is used to boot the system and often provides some services at runtime. Both kinds of firmware can have bugs and vulnerabilities, so it is critical to keep them updated.
|
||||
|
||||
Some firmware is loaded by the OS at runtime. Such firmware is provided by the ``linux-firmware`` package and can be updated the usual way. Other devices have persistent firmware that must be updated manually.
|
||||
|
||||
Qubes OS supports updating system firmware in three different ways. Which one to use depends on the device whose firmware is being updated.
|
||||
|
||||
- If a device is attached to a domU, it should be updated using **fwupd**. fwupd is included in both Debian and Fedora repositories. It requires Internet access to use, but you can use the updates proxy if you need to update firmware from an offline VM. You can use either the command-line ``fwupdmgr`` tool or any of the graphical interfaces to fwupd.
|
||||
|
||||
- If a device is attached to dom0, use the ``qubes-fwupdmgr`` command-line tool. This tool uses fwupd internally, but it fetches firmware and metadata over qrexec from the dom0 UpdateVM, rather than fetching them from the Internet. Unfortunately, their is no graphical interface for this tool yet.
|
||||
|
||||
- System76 systems use a special update tool which is simpler than fwupd. Support for this tool is currently in progress. Once it is finished, users will be able to use the **system76-firmware-cli** command-line tool to update the firmware.
|
||||
|
||||
|
||||
|
||||
Firmware updates are important on all systems, but they are especially important on AMD client systems. These do not support loading microcode from the OS, so firmware updates are the **only** way to obtain microcode updates.
|
||||
|
||||
Firmware update methods
|
||||
-----------------------
|
||||
|
||||
|
||||
As of Qubes 4.2, firmware updates can be performed from within Qubes for `fwupd-supported computers <https://fwupd.org/>`__.
|
||||
|
||||
In dom0
|
||||
^^^^^^^
|
||||
|
||||
|
||||
First, ensure that your UpdateVM contains the ``fwupd-qubes-vm`` package. This package is installed by default for qubes with ``qubes-vm-recommended`` packages.
|
||||
|
||||
In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-dom0-update fwupd-qubes-dom0
|
||||
|
||||
|
||||
|
||||
Once the package is installed:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-fwupdmgr get-devices
|
||||
|
||||
|
||||
|
||||
Examine the terminal output for warnings or errors. You may see the following warning:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
WARNING: UEFI capsule updates not available or enabled
|
||||
|
||||
|
||||
|
||||
If so, `adjust your BIOS settings <https://github.com/fwupd/fwupd/wiki/PluginFlag:capsules-unsupported>`__ to enable UEFI updates. This setting is sometimes named “Windows UEFI Firmware Update.”
|
||||
|
||||
Once resolved, in a dom0 terminal:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ sudo qubes-fwupdmgr get-devices
|
||||
$ sudo qubes-fwupdmgr refresh
|
||||
$ sudo qubes-fwupdmgr update
|
||||
|
||||
|
||||
|
||||
A numbered list of devices with available updates will be presented. Ensure your computer is plugged in to a stable power source, then type the list number of the device you wish to update. If a reboot is required, you will be prompted at the console to confirm.
|
||||
|
||||
Repeat the update process for any additional devices on your computer.
|
||||
|
||||
In other qubes
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Devices that are attached to non-dom0 qubes can be updated via a graphical tool for ``fwupd``, or via the ``fwupdmgr`` commandline tool.
|
||||
|
||||
To update the firmware of offline qubes, use the :ref:`Updates proxy <user/how-to-guides/how-to-install-software:updates proxy>`.
|
||||
|
||||
Computers without fwupd support
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
For computers that do not have firmware update support via ``fwupd``, follow the firmware update instructions on the manufacturer’s website. Verify the authenticity of any firmware updates you apply.
|
||||
|
||||
.. |Qube Updates Available| image:: /attachment/doc/r4.2-qube-updates-available.png
|
||||
|
||||
|
||||
.. |Qubes Update| image:: /attachment/doc/r4.2-software-update.png
|
||||
|
||||
|
|
@ -1,256 +0,0 @@
|
|||
---
|
||||
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/how-to-use-devices/).*
|
||||
|
||||
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 Devices Widget 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: 
|
||||
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/how-to-use-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 app qube to parse the partition table.
|
||||
However, it often means the app qube won't detect the new partition and you will need to manually mount it inside the app qube.
|
||||
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 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  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`.
|
||||
282
user/how-to-guides/how-to-use-block-storage-devices.rst
Normal file
282
user/how-to-guides/how-to-use-block-storage-devices.rst
Normal file
|
|
@ -0,0 +1,282 @@
|
|||
================================
|
||||
How to use block storage devices
|
||||
================================
|
||||
|
||||
|
||||
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
|
||||
|
||||
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 Devices Widget 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| 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 :doc:`whole usb-device </user/how-to-guides/how-to-use-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 app qube to parse the partition table. However, it often means the app qube won’t detect the new partition and you will need to manually mount it inside the app qube. 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo umount mnt
|
||||
|
||||
|
||||
|
||||
5. In a dom0 console, detach the device
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 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
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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| 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:
|
||||
|
||||
|
||||
|
||||
.. code:: bash
|
||||
|
||||
~]$ qvm-block
|
||||
BACKEND:DEVID DESCRIPTION USED BY
|
||||
sourceVM:loop0 /path/to/file
|
||||
|
||||
|
||||
3. Attach the ``loop0``-device using qvm-block as usual:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-block a targetVM sourceVM:loop0
|
||||
|
||||
|
||||
|
||||
4. After detaching, destroy the loop-device inside the sourceVM as follows:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-block a work sys-usb:sda1 -o read-only=true
|
||||
|
||||
|
||||
|
||||
There exists a shortcut to set read-only ``true``, ``--ro``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-block a work sys-usb:sda1 -o devtype=cdrom
|
||||
|
||||
|
||||
|
||||
This option accepts ``cdrom`` and ``disk``, default is ``disk``.
|
||||
|
||||
.. |device manager icon| image:: /attachment/doc/media-removable.png
|
||||
|
|
@ -1,159 +0,0 @@
|
|||
---
|
||||
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/how-to-use-block-storage-devices/), [USB](/doc/how-to-use-usb-devices/) and [PCI](/doc/how-to-use-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):  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: 
|
||||
|
||||
|
||||
### 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](https://github.com/QubesOS/qubes-issues/issues/4692) `qvm-device block` or `qvm-block` 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]`
|
||||
169
user/how-to-guides/how-to-use-devices.rst
Normal file
169
user/how-to-guides/how-to-use-devices.rst
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
==================
|
||||
How to use devices
|
||||
==================
|
||||
|
||||
|
||||
This is an overview of device handling in Qubes OS. For specific devices (:doc:`block </user/how-to-guides/how-to-use-block-storage-devices>`, :doc:`USB </user/how-to-guides/how-to-use-usb-devices>` and :doc:`PCI </user/how-to-guides/how-to-use-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 :doc:`security considerations </user/security-in-qubes/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| 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|
|
||||
|
||||
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 <https://github.com/QubesOS/qubes-issues/issues/4692>`__ ``qvm-device block`` or ``qvm-block`` 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-1:
|
||||
|
||||
|
||||
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]``
|
||||
|
||||
.. |SD card and thumbdrive| image:: /attachment/doc/media-removable.png
|
||||
|
||||
.. |eject icon| image:: /attachment/doc/media-eject.png
|
||||
|
|
@ -1,185 +0,0 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/how-to-use-disposables/
|
||||
redirect_from:
|
||||
- /doc/how-to-use-disposablevms/
|
||||
- /doc/disposable/
|
||||
- /doc/disposablevm/
|
||||
- /doc/dispvm/
|
||||
- /en/doc/dispvm/
|
||||
- /doc/DisposableVms/
|
||||
- /wiki/DisposableVMs/
|
||||
ref: 203
|
||||
title: How to use disposables
|
||||
---
|
||||
|
||||
A [disposable](/doc/glossary/#disposable) is a lightweight [qube](/doc/glossary/#qube) that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
|
||||
|
||||
From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file. Changes made to a file opened in a disposable are passed back to the originating qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0's app menu or terminal window, or from within app qubes. Disposables are generated with names like `disp####`, where `####` is random number.
|
||||
|
||||
[](/attachment/doc/disposablevm-example.png)
|
||||
|
||||
This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a disposable.
|
||||
|
||||
## Named disposables and disposable templates
|
||||
|
||||
There is a difference between [named disposable qubes](/doc/glossary/#named-disposable) and [disposable templates](/doc/glossary/#disposable-template).
|
||||
|
||||
In a default QubesOS Installation, you would probably use the 'whonix-ws-16-dvm' disposable template to, for example, browse the Tor network with an disposable qube. Every time you start an application using this disposable template, a new disposable qube - named `dispX` (where X is a random number) starts. If you close the application window, the `dispX` qube shuts down and vanishes from your system. That is how disposable templates are used.
|
||||
|
||||
Named disposables are also built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube - every application you open will start in the same qube, and you need to manually shutdown the qube. But when you shutdown *any changes you made in the named disposable will be lost*. Except for this non-persistance, they feel like usual app qubes.
|
||||
|
||||
### How to create disposable templates
|
||||
|
||||
First, you need to create an app qube. You can run it normally, set up any necessary settings (like browser settings) you wish to be applied to every disposable qube ran from this template. Next, go to 'Qube Settings' of the app qube, set it as a _Disposable template_ in the _Advanced_ section and apply the change.
|
||||
|
||||
In Qubes 4.1, the entry in the Application menu is split into 'Disposable' and 'Template (disp)'. The settings for the disposable can be changed under **'Application Menu -> Template (disp) -> Template: Qubes Settings**
|
||||
|
||||
In Qubes 4.2, the qube will now appear in the menu as a disposable template (in the Apps section), from which you can launch new disposable qubes. To change the settings of the template itself or run programs in it, use the menu item for the disposable template located in the Templates section.
|
||||
|
||||
### How to create named disposables
|
||||
|
||||
In Qubes 4.1: named disposables can be created under **Application Menu -> Create Qubes VM**, set the qube type to be _DisposableVM_.
|
||||
|
||||
In Qubes 4.2: named disposables can be created by **Application Menu -> Settings -> Qubes Settings -> Create New Qube**. Set the qube type to **Named disposable**.
|
||||
|
||||
## Security
|
||||
|
||||
If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised. In particular, the *default* disposable template is important because it is used by the "Open in disposable" 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 disposable template on a trusted template.
|
||||
|
||||
### Disposables and Local Forensics
|
||||
|
||||
At this time, disposables 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/).
|
||||
|
||||
## Disposables and Networking
|
||||
|
||||
Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template). R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
|
||||
|
||||
On a fresh installation of Qubes, the default disposable template is called `fedora-X-dvm` or `debian-X-dvm` (where `X` is a release number). If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
|
||||
|
||||
You can set any app qube to have the ability to act as a disposable template with:
|
||||
|
||||
```
|
||||
qvm-prefs <APP_QUBE> template_for_dispvms True
|
||||
```
|
||||
|
||||
The default system wide disposable template can be changed with `qubes-prefs default_dispvm`. By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
|
||||
|
||||
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the "Advanced" tab. Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
|
||||
|
||||
```
|
||||
qvm-prefs <QUBE> default_dispvm <DISPOSABLE_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 app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
|
||||
|
||||
Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior from R3.2, where disposables would inherit the settings of the app qube from which they were launched. Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based. For example, if an app qube uses sys-net as its net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
|
||||
|
||||
**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 disposable uses sys-net, launching a disposable from inside `anon-whonix` will result in the disposable using `sys-net`.
|
||||
|
||||
A disposable launched from the app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
|
||||
|
||||
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
|
||||
|
||||
```
|
||||
qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
|
||||
```
|
||||
|
||||
To launch a disposable template from the command line, execute the following command in dom0:
|
||||
|
||||
```
|
||||
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
|
||||
```
|
||||
|
||||
## Opening a file in a disposable via GUI
|
||||
|
||||
In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable". 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 qube -- a disposable created for the purpose of viewing or editing this very file. Once you close the viewing application the whole disposable will be destroyed. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Opening a fresh web browser instance in a new disposable
|
||||
|
||||
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to **Application Menu -> Disposable -> Disposable: Firefox web browser**. Wait a few seconds until a web browser starts. Once you close the viewing application the whole disposable will be destroyed.
|
||||
|
||||
|
||||
|
||||
|
||||
## Opening a file in a disposable via command line (from app qube)
|
||||
|
||||
Use the `qvm-open-in-dvm` command from a terminal in your app qube:
|
||||
|
||||
~~~
|
||||
[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 disposable.
|
||||
|
||||
## Making a particular application open everything in a disposable
|
||||
|
||||
You can use the `qvm-service` command or the services GUI to cause an application in a qube to open files and URLs in a disposable. To do this, enable a service named `app-dispvm.X` in that qube, where `X` is the application ID. For instance, to have Thunderbird open all attachments in a disposable, enable the `app-dispvm.thunderbird` service.
|
||||
|
||||
This feature is currently somewhat experimental, and only works for Linux qubes. It is known to work with Thunderbird and Wire, but it may fail to work with some applications that do not honor all XDG environment variables. If the feature does not work for you, please file a bug report.
|
||||
|
||||
## Opening particular types of files in a disposable
|
||||
|
||||
You can set `qvm-open-in-dvm.desktop` as the handler for a given MIME type. This will cause all files of that type to open in a disposable. This works in disposable templates too, but be careful: if your disposable template is set to use `qvm-open-in-dvm.desktop` to open a certain kind of file, every disposable based on it will be as well. If the disposable template is its own default disposable template (as is often the case), this will result in a loop: `qvm-open-in-dvm` will execute `qubes.OpenURL` in a new disposable, but that will in turn execute `qvm-open-in-dvm`. The cycle will repeat until no new disposables can be created, most likely because your system has run out of memory.
|
||||
|
||||
This will _not_ override the internal handling of PDF documents in Web browsers. This is typically okay, though: in-browser PDF viewers have a fairly good security record, especially when compared to non-browser PDF viewers. In particular, the attack surface of PDF viewing in Firefox is usually less than that of viewing an ordinary Web page.
|
||||
|
||||
## Starting an arbitrary program in a disposable from an app qube
|
||||
|
||||
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable 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 app qube by running
|
||||
|
||||
~~~
|
||||
[user@vault ~]$ qvm-run '@dispvm' xterm
|
||||
~~~
|
||||
|
||||
The created disposable can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
|
||||
|
||||
## Starting an arbitrary application in a disposable via command line from dom0
|
||||
|
||||
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable 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 disposable directly from dom0 by running:
|
||||
|
||||
~~~
|
||||
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
|
||||
~~~
|
||||
|
||||
The label color will be inherited from `<DISPOSABLE_TEMPLATE>`. (The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
|
||||
|
||||
### Opening a link in a disposable based on a non-default disposable template from a qube
|
||||
|
||||
Suppose that the default disposable 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 disposables. Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable 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_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
|
||||
~~~
|
||||
|
||||
This will create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`, open the default web browser in that disposable, 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_DISPOSABLE_TEMPLATE> allow
|
||||
~~~
|
||||
|
||||
This line means:
|
||||
|
||||
- FROM: Any qube
|
||||
- TO: A disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`
|
||||
- WHAT: Allow sending an "Open URL" request
|
||||
|
||||
In other words, any qube will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
|
||||
|
||||
More information about RPC policies for disposables can be found [here](/doc/qrexec/#qubes-rpc-administration).
|
||||
|
||||
## Customizing disposables
|
||||
|
||||
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found [here](/doc/disposable-customization/).
|
||||
238
user/how-to-guides/how-to-use-disposables.rst
Normal file
238
user/how-to-guides/how-to-use-disposables.rst
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
======================
|
||||
How to use disposables
|
||||
======================
|
||||
|
||||
|
||||
A :ref:`disposable <user/reference/glossary:disposable>` is a lightweight :ref:`qube <user/reference/glossary:qube>` that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
|
||||
|
||||
From inside an app qube, choosing the ``Open in disposable`` option on a file will launch a disposable for just that file. Changes made to a file opened in a disposable are passed back to the originating qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0’s app menu or terminal window, or from within app qubes. Disposables are generated with names like ``disp####``, where ``####`` is random number.
|
||||
|
||||
|disposablevm-example.png|
|
||||
|
||||
This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. See `this article <https://blog.invisiblethings.org/2010/06/01/disposable-vms.html>`__ for more on why one would want to use a disposable.
|
||||
|
||||
Named disposables and disposable templates
|
||||
------------------------------------------
|
||||
|
||||
|
||||
There is a difference between :ref:`named disposable qubes <user/reference/glossary:named disposable>` and :ref:`disposable templates <user/reference/glossary:disposable template>`.
|
||||
|
||||
In a default QubesOS Installation, you would probably use the ‘whonix-ws-16-dvm’ disposable template to, for example, browse the Tor network with an disposable qube. Every time you start an application using this disposable template, a new disposable qube - named ``dispX`` (where X is a random number) starts. If you close the application window, the ``dispX`` qube shuts down and vanishes from your system. That is how disposable templates are used.
|
||||
|
||||
Named disposables are also built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube - every application you open will start in the same qube, and you need to manually shutdown the qube. But when you shutdown *any changes you made in the named disposable will be lost*. Except for this non-persistance, they feel like usual app qubes.
|
||||
|
||||
How to create disposable templates
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
First, you need to create an app qube. You can run it normally, set up any necessary settings (like browser settings) you wish to be applied to every disposable qube ran from this template. Next, go to ‘Qube Settings’ of the app qube, set it as a *Disposable template* in the *Advanced* section and apply the change.
|
||||
|
||||
In Qubes 4.1, the entry in the Application menu is split into ‘Disposable’ and ‘Template (disp)’. The settings for the disposable can be changed under **’Application Menu -> Template (disp) -> Template: Qubes Settings**
|
||||
|
||||
In Qubes 4.2, the qube will now appear in the menu as a disposable template (in the Apps section), from which you can launch new disposable qubes. To change the settings of the template itself or run programs in it, use the menu item for the disposable template located in the Templates section.
|
||||
|
||||
How to create named disposables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
In Qubes 4.1: named disposables can be created under **Application Menu -> Create Qubes VM**, set the qube type to be *DisposableVM*.
|
||||
|
||||
In Qubes 4.2: named disposables can be created by **Application Menu -> Settings -> Qubes Settings -> Create New Qube**. Set the qube type to **Named disposable**.
|
||||
|
||||
Security
|
||||
--------
|
||||
|
||||
|
||||
If a :ref:`disposable template <user/reference/glossary:disposable template>` becomes compromised, then any disposable based on that disposable template could be compromised. In particular, the *default* disposable template is important because it is used by the “Open in disposable” 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 disposable template on a trusted template.
|
||||
|
||||
Disposables and Local Forensics
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
At this time, disposables 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/>`__.
|
||||
|
||||
Disposables and Networking
|
||||
--------------------------
|
||||
|
||||
|
||||
Similarly to how app qubes are based on their underlying :ref:`template <user/reference/glossary:template>`, disposables are based on their underlying :ref:`disposable template <user/reference/glossary:disposable template>`. R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
|
||||
|
||||
On a fresh installation of Qubes, the default disposable template is called ``fedora-X-dvm`` or ``debian-X-dvm`` (where ``X`` is a release number). If you have included the Whonix option in your install, there will also be a ``whonix-ws-dvm`` disposable template available for your use.
|
||||
|
||||
You can set any app qube to have the ability to act as a disposable template with:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-prefs <APP_QUBE> template_for_dispvms True
|
||||
|
||||
|
||||
|
||||
The default system wide disposable template can be changed with ``qubes-prefs default_dispvm``. By combining the two, choosing ``Open in disposable`` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
|
||||
|
||||
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the “Advanced” tab. Here you can edit the “Default disposable” setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-prefs <QUBE> default_dispvm <DISPOSABLE_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 app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
|
||||
|
||||
Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior from R3.2, where disposables would inherit the settings of the app qube from which they were launched. Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based. For example, if an app qube uses sys-net as its net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
|
||||
|
||||
**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 disposable uses sys-net, launching a disposable from inside ``anon-whonix`` will result in the disposable using ``sys-net``.
|
||||
|
||||
A disposable launched from the app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
|
||||
|
||||
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
|
||||
|
||||
|
||||
|
||||
To launch a disposable template from the command line, execute the following command in dom0:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
|
||||
|
||||
|
||||
|
||||
Opening a file in a disposable via GUI
|
||||
--------------------------------------
|
||||
|
||||
|
||||
In an app qube’s file manager, right click on the file you wish to open in a disposable, then choose “View in disposable” or “Edit in disposable”. 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 qube – a disposable created for the purpose of viewing or editing this very file. Once you close the viewing application the whole disposable will be destroyed. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
|
||||
|
||||
.. figure:: /attachment/doc/r4.0-open-in-dispvm-1.png
|
||||
:alt: r4.0-open-in-dispvm-1.png
|
||||
|
||||
|
||||
|
||||
.. figure:: /attachment/doc/r4.0-open-in-dispvm-2.png
|
||||
:alt: r4.0-open-in-dispvm-2.png
|
||||
|
||||
|
||||
|
||||
Opening a fresh web browser instance in a new disposable
|
||||
--------------------------------------------------------
|
||||
|
||||
|
||||
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to **Application Menu -> Disposable -> Disposable: Firefox web browser**. Wait a few seconds until a web browser starts. Once you close the viewing application the whole disposable will be destroyed.
|
||||
|
||||
.. figure:: /attachment/doc/r4.0-open-in-dispvm-3.png
|
||||
:alt: r4.0-open-in-dispvm-3.png
|
||||
|
||||
|
||||
|
||||
Opening a file in a disposable via command line (from app qube)
|
||||
---------------------------------------------------------------
|
||||
|
||||
|
||||
Use the ``qvm-open-in-dvm`` command from a terminal in your app qube:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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 disposable.
|
||||
|
||||
Making a particular application open everything in a disposable
|
||||
---------------------------------------------------------------
|
||||
|
||||
|
||||
You can use the ``qvm-service`` command or the services GUI to cause an application in a qube to open files and URLs in a disposable. To do this, enable a service named ``app-dispvm.X`` in that qube, where ``X`` is the application ID. For instance, to have Thunderbird open all attachments in a disposable, enable the ``app-dispvm.thunderbird`` service.
|
||||
|
||||
This feature is currently somewhat experimental, and only works for Linux qubes. It is known to work with Thunderbird and Wire, but it may fail to work with some applications that do not honor all XDG environment variables. If the feature does not work for you, please file a bug report.
|
||||
|
||||
Opening particular types of files in a disposable
|
||||
-------------------------------------------------
|
||||
|
||||
|
||||
You can set ``qvm-open-in-dvm.desktop`` as the handler for a given MIME type. This will cause all files of that type to open in a disposable. This works in disposable templates too, but be careful: if your disposable template is set to use ``qvm-open-in-dvm.desktop`` to open a certain kind of file, every disposable based on it will be as well. If the disposable template is its own default disposable template (as is often the case), this will result in a loop: ``qvm-open-in-dvm`` will execute ``qubes.OpenURL`` in a new disposable, but that will in turn execute ``qvm-open-in-dvm``. The cycle will repeat until no new disposables can be created, most likely because your system has run out of memory.
|
||||
|
||||
This will *not* override the internal handling of PDF documents in Web browsers. This is typically okay, though: in-browser PDF viewers have a fairly good security record, especially when compared to non-browser PDF viewers. In particular, the attack surface of PDF viewing in Firefox is usually less than that of viewing an ordinary Web page.
|
||||
|
||||
Starting an arbitrary program in a disposable from an app qube
|
||||
--------------------------------------------------------------
|
||||
|
||||
|
||||
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable 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 app qube by running
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@vault ~]$ qvm-run '@dispvm' xterm
|
||||
|
||||
|
||||
|
||||
The created disposable can be accessed via other tools (such as ``qvm-copy-to-vm``) using its ``disp####`` name as shown in the Qubes Manager or ``qvm-ls``.
|
||||
|
||||
Starting an arbitrary application in a disposable via command line from dom0
|
||||
----------------------------------------------------------------------------
|
||||
|
||||
|
||||
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable 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 disposable directly from dom0 by running:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
|
||||
|
||||
|
||||
|
||||
The label color will be inherited from ``<DISPOSABLE_TEMPLATE>``. (The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
|
||||
|
||||
Opening a link in a disposable based on a non-default disposable template from a qube
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Suppose that the default disposable 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 disposables. Obviously, you can’t use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the ``email`` qube (as long as your RPC policies allow it):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
|
||||
|
||||
|
||||
|
||||
This will create a new disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>``, open the default web browser in that disposable, 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``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@anyvm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> allow
|
||||
|
||||
|
||||
|
||||
This line means:
|
||||
|
||||
- FROM: Any qube
|
||||
|
||||
- TO: A disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>``
|
||||
|
||||
- WHAT: Allow sending an “Open URL” request
|
||||
|
||||
|
||||
|
||||
In other words, any qube will be allowed to create a new disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>`` and open a URL inside of that disposable.
|
||||
|
||||
More information about RPC policies for disposables can be found :ref:`here <developer/services/qrexec:qubes rpc administration>`.
|
||||
|
||||
Customizing disposables
|
||||
-----------------------
|
||||
|
||||
|
||||
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found :doc:`here </user/advanced-topics/disposable-customization>`.
|
||||
|
||||
.. |disposablevm-example.png| image:: /attachment/doc/disposablevm-example.png
|
||||
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
---
|
||||
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 Qubes OS. This is not a limitation of Xen, which provides scsiback and scsifront drivers, but of Qubes OS. It will be fixed in the future.
|
||||
|
||||
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://forum.qubes-os.org/t/19075#dom0-precautions).)
|
||||
|
||||
To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/how-to-use-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`.
|
||||
18
user/how-to-guides/how-to-use-optical-discs.rst
Normal file
18
user/how-to-guides/how-to-use-optical-discs.rst
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
========================
|
||||
How to use optical discs
|
||||
========================
|
||||
|
||||
|
||||
Passthrough reading and recording (a.k.a., “burning”) are not supported by Qubes OS. This is not a limitation of Xen, which provides scsiback and scsifront drivers, but of Qubes OS. It will be fixed in the future.
|
||||
|
||||
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://forum.qubes-os.org/t/19075#dom0-precautions>`__.)
|
||||
|
||||
|
||||
|
||||
To access an optical disc via USB follow the :ref:`typical procedure for attaching a USB device <user/how-to-guides/how-to-use-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``.
|
||||
|
|
@ -1,144 +0,0 @@
|
|||
---
|
||||
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/how-to-use-devices/).*
|
||||
|
||||
**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/how-to-use-usb-devices/), [block](/doc/how-to-use-block-storage-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.
|
||||
Moreover, PCI devices can be attached only to VMs running in certain virtualization modes. See [FAQ: Which virtualization modes do VMs use?](/faq/#which-virtualization-modes-do-vms-use)
|
||||
|
||||
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  `[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/how-to-use-devices/#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!
|
||||
155
user/how-to-guides/how-to-use-pci-devices.rst
Normal file
155
user/how-to-guides/how-to-use-pci-devices.rst
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
======================
|
||||
How to use PCI devices
|
||||
======================
|
||||
|
||||
|
||||
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
|
||||
|
||||
**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 :ref:`security considerations <user/security-in-qubes/device-handling-security:pci security>` before deviating from default behavior.
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
|
||||
Unlike other devices (:doc:`USB </user/how-to-guides/how-to-use-usb-devices>`, :doc:`block </user/how-to-guides/how-to-use-block-storage-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. Moreover, PCI devices can be attached only to VMs running in certain virtualization modes. See :ref:`FAQ: Which virtualization modes do VMs use? <introduction/faq:which virtualization modes do vms use?>`
|
||||
|
||||
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 :ref:`security considerations <user/security-in-qubes/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| ``[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 :ref:`qvm-device pci <user/how-to-guides/how-to-use-devices: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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-pci attach work dom0:00_1a.0 --persistent
|
||||
|
||||
|
||||
|
||||
Possible Issues
|
||||
---------------
|
||||
|
||||
|
||||
Visit the :doc:`PCI Troubleshooting guide </user/troubleshooting/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 :ref:`heavy security implications <user/security-in-qubes/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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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!
|
||||
|
||||
.. |appmenu| image:: /attachment/doc/qubes-appmenu-select.png
|
||||
|
|
@ -1,183 +0,0 @@
|
|||
---
|
||||
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/how-to-use-devices/).*
|
||||
|
||||
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page.
|
||||
|
||||
**Note:** Attaching USB devices to qubes 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/how-to-use-block-storage-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/ctap-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: 
|
||||
A list of available devices appears.
|
||||
USB-devices have a USB-icon to their right: 
|
||||
|
||||
Hover on one device to display a list of qubes 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 qubes
|
||||
The one to which your device is connected will have an eject button  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 qube` 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 qube`, you can install the `qubes-usb-proxy` with the package manager in the qube 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/).
|
||||
|
||||
### 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 you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
|
||||
|
||||
You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`.
|
||||
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 attached to the target qube.
|
||||
|
||||
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: 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/how-to-use-pci-devices/) to attach the controller to the target qube, like this:
|
||||
```
|
||||
qvm-pci attach --persistent personal dom0:00_1a.0
|
||||
```
|
||||
|
||||
It is possible that on some system configurations the readlink method produces output which is different from the example above,
|
||||
For example, you might see output like this:
|
||||
```
|
||||
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
|
||||
```
|
||||
In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
|
||||
|
||||
If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
|
||||
|
||||
### Identifying controllers using the Qube Manager
|
||||
Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
|
||||
|
||||
Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices".
|
||||
Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller".
|
||||
They should look something like: `01:00.0 USB controller: Name of manufacturer`
|
||||
|
||||
The first part is the BDF address, in this example: `01:00.0`
|
||||
|
||||
If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name.
|
||||
|
||||
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.
|
||||
211
user/how-to-guides/how-to-use-usb-devices.rst
Normal file
211
user/how-to-guides/how-to-use-usb-devices.rst
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
======================
|
||||
How to use USB devices
|
||||
======================
|
||||
|
||||
|
||||
*This page is part of* :doc:`device handling in qubes </user/how-to-guides/how-to-use-devices>` *.*
|
||||
|
||||
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the :doc:`block device </user/how-to-guides/how-to-use-block-storage-devices>` page.
|
||||
|
||||
**Note:** Attaching USB devices to qubes requires a :doc:`USB qube </user/advanced-topics/usb-qubes>`.
|
||||
|
||||
**Important security warning:** USB passthrough comes with many security implications. Please make sure you carefully read and understand the :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>`. Whenever possible, attach a :doc:`block device </user/how-to-guides/how-to-use-block-storage-devices>` instead.
|
||||
|
||||
Examples of valid cases for USB-passthrough:
|
||||
|
||||
- `microcontroller programming <https://www.arduino.cc/en/Main/Howto>`__
|
||||
|
||||
- `external audio devices <https://forum.qubes-os.org/t/18984>`__
|
||||
|
||||
- :doc:`optical drives </user/how-to-guides/how-to-use-optical-discs>` for recording
|
||||
|
||||
|
||||
|
||||
(If you are thinking to use a two-factor-authentication device, :doc:`there is an app for that </user/security-in-qubes/ctap-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| A list of available devices appears. USB-devices have a USB-icon to their right: |usb icon|
|
||||
|
||||
Hover on one device to display a list of qubes 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 qubes The one to which your device is connected will have an eject button |eject icon| 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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 qube`` instead, please refer to the `Installation Section <#installation-of-qubes-usb-proxy>`__.
|
||||
|
||||
When you finish, detach the device.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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 :doc:`this guide </user/advanced-topics/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 qube``, you can install the ``qubes-usb-proxy`` with the package manager in the qube you want to attach the USB device to.
|
||||
|
||||
- Fedora:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo dnf install qubes-usb-proxy
|
||||
|
||||
|
||||
|
||||
- Debian/Ubuntu:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 :ref:`security considerations <user/security-in-qubes/device-handling-security:usb security>` before continuing!
|
||||
|
||||
Mouse and keyboard setup are part of :doc:`setting up a USB qube </user/advanced-topics/usb-qubes>`.
|
||||
|
||||
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 you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it.
|
||||
|
||||
You can find your controller and its BDF address using the method described below, using the command-line tools ``lsusb`` and ``readlink``. 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):
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
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 attached to the target qube.
|
||||
|
||||
To find the right controller, follow the usb bus:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
readlink /sys/bus/usb/devices/usb3
|
||||
|
||||
|
||||
|
||||
This should output something like:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
|
||||
|
||||
|
||||
|
||||
Now you see the path: 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 :doc:`qvm-pci tool </user/how-to-guides/how-to-use-pci-devices>` to attach the controller to the target qube, like this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
qvm-pci attach --persistent personal dom0:00_1a.0
|
||||
|
||||
|
||||
|
||||
It is possible that on some system configurations the readlink method produces output which is different from the example above, For example, you might see output like this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
|
||||
|
||||
|
||||
|
||||
In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0
|
||||
|
||||
If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead.
|
||||
|
||||
Identifying controllers using the Qube Manager
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to.
|
||||
|
||||
Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab “Devices”. Here you should see your available devices along with their BDF addresses. Look for the lines containing “USB controller”. They should look something like: ``01:00.0 USB controller: Name of manufacturer``
|
||||
|
||||
The first part is the BDF address, in this example: ``01:00.0``
|
||||
|
||||
If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as “Intel Corporation”, while the added controller shows another manufacturer’s name.
|
||||
|
||||
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.
|
||||
|
||||
.. |device manager icon| image:: /attachment/doc/media-removable.png
|
||||
|
||||
.. |usb icon| image:: /attachment/doc/generic-usb.png
|
||||
|
||||
.. |eject icon| image:: /attachment/doc/media-eject.png
|
||||
Loading…
Add table
Add a link
Reference in a new issue