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

Wrap text and miscellaneous cleanup

Browse source
This commit is contained in:
Andrew David Wong 2021-06-18 06:25:06 -07:00
parent e451f92cde
commit 07c130df00
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
21 changed files with 1845 additions and 1022 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -21,21 +21,22 @@ any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt](https://www.tarsnap.com/scrypt.html). You
will need a copy of this utility in order to access your data. Since `scrypt`
is not pre-installed on every GNU/Linux system, it is strongly recommended that
you store a copy of it with your backups. If your distribution has `scrypt`
packaged (e.g., Debian), you can install the package in the standard way using
your distribution's package manager. Otherwise, you'll need to obtain a
compiled binary (instructions below) or compile the program from source
yourself. (Don't forget to [verify signatures](/security/verifying-signatures) first!) Note that versions of
`scrypt` up to 1.2.0 (inclusive) do not support the `-P` option for easier
scripting, which means you'll need to enter the passphrase for each file
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.
uses an RPM-based system (Fedora), but the same general procedure should work
on any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key](/security/verifying-signatures/#2-get-the-release-signing-key).
2. If you're not on Qubes 4.X, import the Release 4 Signing Key.
@ -143,7 +144,8 @@ Emergency Recovery Instructions
[user@restore ~]$ backup_id=20161020T123455-1234
6. Verify the integrity of your data, decrypt, decompress, and extract `private.img`:
6. Verify the integrity of your data, decrypt, decompress, and extract
`private.img`:
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \

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

@ -11,23 +11,27 @@ 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.
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`.
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.
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:
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/
@ -36,106 +40,149 @@ $ mkdir ~/backup/etc/qubes-rpc/
$ cp -a /etc/qubes-rpc/* ~/systemfiles/etc/qubes-rpc/
```
To restore these files, move them from the restored directory in dom0's home back to their appropriate locations in `/etc/`.
Please note that any packages installed via the package manager in dom0 will not be backed up.
Such packages will have to be reinstalled through the package manager when restoring on a fresh installation.
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.
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.
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.
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.
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.
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.
**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.
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.**
**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.
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**.
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.
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.
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**.
- 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**.
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.
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.
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.
**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.
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**.
6. When you are ready, click **Next**. Qubes will proceed to restore from your
backup. Once the progress bar has completed, you may click **Finish**.
**Note:** When restoring from a dom0 backup, a new directory will be created in the current dom0 home directory, and the contents from the backup will be placed inside this new directory.
This is intentional, as it allows users to have explicit control over which files and settings get applied in dom0.
If the contents from the dom0 backup were instead to overwrite the existing files in dom0's home directory, unexpected and undesired configuration changes could occur.
However, if you do wish to move all files from the dom0 backup out of the subdirectory into your current dom0 home directory (overwriting any existing files in the process), you may do so by following the instructions [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
Just remember that this can cause unexpected and desired configuration changes in dom0, depending on exactly which files you're adding and replacing.
**Note:** When restoring from a dom0 backup, a new directory will be created in
the current dom0 home directory, and the contents from the backup will be
placed inside this new directory. This is intentional, as it allows users to
have explicit control over which files and settings get applied in dom0. If the
contents from the dom0 backup were instead to overwrite the existing files in
dom0's home directory, unexpected and undesired configuration changes could
occur. However, if you do wish to move all files from the dom0 backup out of
the subdirectory into your current dom0 home directory (overwriting any
existing files in the process), you may do so by following the instructions
[here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
Just remember that this can cause unexpected and desired configuration changes
in dom0, depending on exactly which files you're adding and replacing.
Emergency backup recovery without qubes
---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind.
No special Qubes-specific tools are required to access data backed up by Qubes.
In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
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:
@ -146,25 +193,37 @@ Refer to the following for emergency restore of a backup created on:
Migrating between two physical machines
---------------------------------------
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine.
All of your settings and data will be preserved!
In order to migrate your Qubes system from one physical machine to another,
simply follow the backup procedure on the old machine, [install
Qubes](/downloads/) on the new machine, and follow the restoration procedure on
the new machine. All of your settings and data will be preserved!
Choosing a backup passphrase
----------------------------
Here are some things to consider when selecting a passphrase for your backups:
- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
If your system drive decryption passphrase is already sufficiently strong, it may not.)
- An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
On the 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.
- 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
-----
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).
- 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).

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

@ -12,68 +12,140 @@ ref: 190
title: How to Get Started
---
After [downloading](/downloads/) and [installing](/doc/installation-guide/) Qubes OS, it's time to dive in and get to work!
After [downloading](/downloads/) and [installing](/doc/installation-guide/)
Qubes OS, it's time to dive in and get to work!
## The Basics
Qubes OS is an operating system built out of securely-isolated compartments called **qubes**. For example, you might have a work qube, a personal qube, a banking qube, a web browsing qube, and so on. You can have as many qubes as you want!
Most of the time, you'll be using an **app qube**, which is a qube intended for running software programs like web browsers, email clients, and word processors. Each app qube is based on a **template qube**. More than one qube can be based on the same template. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is successful, the damage is limited to a single qube.
Qubes OS is an operating system built out of securely-isolated compartments
called **qubes**. For example, you might have a work qube, a personal qube, a
banking qube, a web browsing qube, and so on. You can have as many qubes as you
want! Most of the time, you'll be using an **app qube**, which is a qube
intended for running software programs like web browsers, email clients, and
word processors. Each app qube is based on a **template qube**. More than one
qube can be based on the same template. Importantly, a qube cannot modify its
template in any way. This means that, if a qube is ever compromised, its
template and any other qubes based on that template will remain safe. This is
what makes Qubes OS so secure. Even if an attack is successful, the damage is
limited to a single qube.
Suppose you want to use your favorite web browser in several different qubes. You'd install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only have to install the web browser a single time, and updating the template serves to update all the qubes based on it. This elegant design saves time and space while enhancing security.
Suppose you want to use your favorite web browser in several different qubes.
You'd install the web browser in a template, then every qube based on that
template would be able to run the web browser software (while still being
forbidden from modifying the template and any other qubes). This way, you only
have to install the web browser a single time, and updating the template serves
to update all the qubes based on it. This elegant design saves time and space
while enhancing security.
There are also some "helper" qubes in your system. Each qube that connects to the Internet does so through a network-providing **service qube**. If you need to access USB devices, another service qube will do that. There's also a **management qube** that automatically handles a lot of background housekeeping. For the most part, you won't have to worry about it, but it's nice to know that it's there.
As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a [Linux distribution](https://en.wikipedia.org/wiki/Linux_distribution)) and corresponding version number. There are many ready-to-use [templates](/doc/templates) to choose from, and you can download and have as many as you like.
There are also some "helper" qubes in your system. Each qube that connects to
the Internet does so through a network-providing **service qube**. If you need
to access USB devices, another service qube will do that. There's also a
**management qube** that automatically handles a lot of background
housekeeping. For the most part, you won't have to worry about it, but it's
nice to know that it's there. As with app qubes, service qubes and management
qubes are also based on templates. Templates are usually named after their
operating system (often a [Linux
distribution](https://en.wikipedia.org/wiki/Linux_distribution)) and
corresponding version number. There are many ready-to-use
[templates](/doc/templates) to choose from, and you can download and have as
many as you like.
Last but not least, there's a very special **admin qube** which, as the name suggests, is used to administer your entire system. There's only one admin qube, and it's called **dom0**. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is more trusted than any other qube. If dom0 were ever compromised, it would be "game over." The entire system would effectively be compromised. That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't happen.
Due to its overarching importance, dom0 has no network connectivity and is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That's what your app qubes are for!)
Last but not least, there's a very special **admin qube** which, as the name
suggests, is used to administer your entire system. There's only one admin
qube, and it's called **dom0**. You can think of it as the master qube, holding
ultimate power over everything that happens in Qubes OS. Dom0 is more trusted
than any other qube. If dom0 were ever compromised, it would be "game over."
The entire system would effectively be compromised. That's why everything in
Qubes OS is specifically designed to protect dom0 and ensure that doesn't
happen. Due to its overarching importance, dom0 has no network connectivity and
is used only for running the [desktop
environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window
manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be
used for anything else. In particular, you should never run user applications
in dom0. (That's what your app qubes are for!)
### Color & Security
You'll choose a **color** for each of your qubes out of a predefined set of colors. Each window on your desktop will have its frame colored according to the color of that qube. These colored frames help you keep track of which qube each window belongs to and how trustworthy it is. This is especially helpful when you have the same app running in multiple qubes at the same time. For example, if you're logged in to your bank account in one qube while doing some random web surfing in a different qube, you wouldn't want to accidentally enter your banking password in the latter! The colored frames help to avoid such mistakes.
You'll choose a **color** for each of your qubes out of a predefined set of
colors. Each window on your desktop will have its frame colored according to
the color of that qube. These colored frames help you keep track of which qube
each window belongs to and how trustworthy it is. This is especially helpful
when you have the same app running in multiple qubes at the same time. For
example, if you're logged in to your bank account in one qube while doing some
random web surfing in a different qube, you wouldn't want to accidentally enter
your banking password in the latter! The colored frames help to avoid such
mistakes.
[![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png)
Most Qubes users associate red with what's untrusted and dangerous (like a red light: stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle. This color scheme also extends to include blue and black, which are usually interpreted as indicating progressively more trusted domains than green, with black being ultimately trusted.
Color and associated meanings are ultimately up to you, however. The system itself does not treat the colors differently. If you create two identical qubes --- black and red, say --- they'll be the same until you start using them differently. Feel free to use the colors in whatever way is most useful to you. For example, you might decide to use three or four qubes for work activities and give them all the same color --- or all different colors. It's entirely up to you.
Most Qubes users associate red with what's untrusted and dangerous (like a red
light: stop! danger!), green with what's safe and trusted, and yellow and
orange with things in the middle. This color scheme also extends to include
blue and black, which are usually interpreted as indicating progressively more
trusted domains than green, with black being ultimately trusted. Color and
associated meanings are ultimately up to you, however. The system itself does
not treat the colors differently. If you create two identical qubes --- black
and red, say --- they'll be the same until you start using them differently.
Feel free to use the colors in whatever way is most useful to you. For example,
you might decide to use three or four qubes for work activities and give them
all the same color --- or all different colors. It's entirely up to you.
### User Interface
On operating systems like Windows and macOS, the desktop environment is unchangeable and part of that operating system. With Linux, any of a number of desktop environments are an option. Qubes OS is installed with XFCE as its default desktop environment, but it also supports KDE, as well as the i3 and awesome window managers.
On operating systems like Windows and macOS, the desktop environment is
unchangeable and part of that operating system. With Linux, any of a number of
desktop environments are an option. Qubes OS is installed with XFCE as its
default desktop environment, but it also supports KDE, as well as the i3 and
awesome window managers.
[![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png)
The bar at the top of your screen in Qubes 4.0 includes the following XFCE component areas:
The bar at the top of your screen in Qubes 4.0 includes the following XFCE
component areas:
- The **Tray**, where many functional widgets live.
- **Spaces**, an interface for [virtual desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things.
- **Spaces**, an interface for [virtual
desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops
do not have any inherent security isolation properties, but some users find
them useful for organizing things.
- The **Task Bar** where buttons for open and hidden windows live.
- The **App Menu**, where you go to open an application within a qube, to open a dom0 terminal, to access administrative UI tools such as the Qube Manager, or to access settings panels for your desktop environment.
- The **App Menu**, where you go to open an application within a qube, to open
a dom0 terminal, to access administrative UI tools such as the Qube Manager,
or to access settings panels for your desktop environment.
To learn more about how to customize your desktop environment, we recommend you spend some time going through [XFCE's documentation](https://docs.xfce.org/).
To learn more about how to customize your desktop environment, we recommend you
spend some time going through [XFCE's documentation](https://docs.xfce.org/).
There are several Tray widgets that are custom to Qubes OS:
- The **Qubes Domains** widget allows you to manage running qubes, turn them on and off, and monitor memory usage.
- The **Qubes Devices** widget allows you to attach and detach devices --- such as USB drives and cameras --- to qubes.
- The **Qubes Disk Space Monitor** will notify you if you're ever running out of disk space.
- The **Qubes Domains** widget allows you to manage running qubes, turn them
on and off, and monitor memory usage.
- The **Qubes Devices** widget allows you to attach and detach devices ---
such as USB drives and cameras --- to qubes.
- The **Qubes Disk Space Monitor** will notify you if you're ever running out
of disk space.
- The **Qubes Update** tool will inform you when updates are available.
[![q40_widgets.png](/attachment/doc/r4.0-q40_widgets.png)](/attachment/doc/r4.0-q40_widgets.png)
To see all of your qubes at the same time, you can use the **Qube Manager** (go to the App Menu → System Tools → Qube Manager), which displays the states of all the qubes in your system, even the ones that aren't running.
To see all of your qubes at the same time, you can use the **Qube Manager** (go
to the App Menu → System Tools → Qube Manager), which displays the states of
all the qubes in your system, even the ones that aren't running.
[![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png)
#### Command-line interface
All aspects of Qubes OS can be controlled using command-line tools. Opening a terminal emulator in dom0 can be done in several ways:
All aspects of Qubes OS can be controlled using command-line tools. Opening a
terminal emulator in dom0 can be done in several ways:
- Go to the App Menu and select **Terminal Emulator** at the top.
- Press <kbd>Alt</kbd>+<kbd>F3</kbd> and search for `xfce terminal`.
- Right-click on the desktop and select **Open Terminal Here**.
Terminal emulators can also be run in other qubes as normal programs.
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Terminal emulators can also be run in other qubes as normal programs. Various
command-line tools are described as part of this guide, and the whole reference
can be found [here](/doc/tools/).
## First boot
@ -82,13 +154,23 @@ When you install Qubes OS, a number of qubes are pre-configured for you:
- **Templates:** `fedora-XX` (`XX` being the version number)
- **Admin qube:** `dom0`
- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`
- **App qubes** configured to prioritize security by compartmentalizing tasks and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is nothing special about these qubes. If you were to create a black qube and name it `vault`, it would be the same as the pre-configured `vault` qube. They're just suggestions to get you started. )
- **App qubes** configured to prioritize security by compartmentalizing tasks
and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is
nothing special about these qubes. If you were to create a black qube and
name it `vault`, it would be the same as the pre-configured `vault` qube.
They're just suggestions to get you started. )
A variety of open-source applications such as file managers, command-line terminals, printer managers, text editors, and "applets" used to configure different things like audio or parts of the user interface are also installed by default—most within the templates. Most are bundled with each template.
A variety of open-source applications such as file managers, command-line
terminals, printer managers, text editors, and "applets" used to configure
different things like audio or parts of the user interface are also installed
by default—most within the templates. Most are bundled with each template.
### Adding, removing, and listing qubes
You can easily create a new qube with the **Create Qubes VM** option in the App Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add** and **Remove** buttons. You can also add, remove, and list qubes from the command line using the following tools:
You can easily create a new qube with the **Create Qubes VM** option in the App
Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add**
and **Remove** buttons. You can also add, remove, and list qubes from the
command line using the following tools:
- `qvm-create`
- `qvm-remove`
@ -96,21 +178,39 @@ You can easily create a new qube with the **Create Qubes VM** option in the App
### How many qubes do I need?
That's a great question, but there's no one-size-fits-all answer. It depends on the structure of your digital life, and this is at least a little different for everyone. If you plan on using your system for work, then it also depends on what kind of job you do.
That's a great question, but there's no one-size-fits-all answer. It depends on
the structure of your digital life, and this is at least a little different for
everyone. If you plan on using your system for work, then it also depends on
what kind of job you do.
It's a good idea to start out with the qubes created automatically by the installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it. You'll also be able to easily [copy any files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
It's a good idea to start out with the qubes created automatically by the
installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start
to feel that some activity just doesn't fit into any of your existing qubes, or
you want to partition some part of your life, you can easily create a new qube
for it. You'll also be able to easily [copy any
files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
Still not sure? You might find it helpful to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes OS architects partitioned her digital life into security domains.
Still not sure? You might find it helpful to read [this
article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html),
which describes how one of the Qubes OS architects partitioned her digital life
into security domains.
## Secure Habits
It is *very important* to [keep Qubes updated](/doc/how-to-update/) to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats.
It is *very important* to [keep Qubes updated](/doc/how-to-update/) to ensure
you have the latest security updates. Frequently updating is one of the best
ways to remain secure against new threats.
It's also *very important* to make regular backups so that you don't lose your data unexpectedly. The [Qubes backup system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this securely and easily.
It's also *very important* to make regular backups so that you don't lose your
data unexpectedly. The [Qubes backup
system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this
securely and easily.
## How-to Guides
Here are some basic tasks you're likely to want to perform often that are unique to Qubes as a multi-environment system. A full list is available in the [How-to Guides](/doc/#how-to-guides) section in the docs.
Here are some basic tasks you're likely to want to perform often that are
unique to Qubes as a multi-environment system. A full list is available in the
[How-to Guides](/doc/#how-to-guides) section in the docs.
- [How to Update](/doc/how-to-update/)
- [How to Back Up, Restore, and Migrate](/doc/how-to-back-up-restore-and-migrate/)
@ -120,16 +220,26 @@ Here are some basic tasks you're likely to want to perform often that are unique
- [How to Install Software](/doc/how-to-install-software/)
- [How to Use Devices (block storage, USB, and PCI devices)](/doc/how-to-use-devices/)
If you encounter any problems, please visit the [Help, Support, Mailing Lists, and Forum](/support/) page.
If you encounter any problems, please visit the [Help, Support, Mailing Lists,
and Forum](/support/) page.
## Compatible Hardware
Make sure your hardware satisfies the [system requirements](/doc/system-requirements/), as Qubes OS cannot run on every type of computer. You may also want to check out [Qubes-certified Hardware](/doc/certified-hardware/) and take a look at the [Hardware Compatibility List (HCL)](/hcl/).
Make sure your hardware satisfies the [system
requirements](/doc/system-requirements/), as Qubes OS cannot run on every type
of computer. You may also want to check out [Qubes-certified
Hardware](/doc/certified-hardware/) and take a look at the [Hardware
Compatibility List (HCL)](/hcl/).
## Downloads
[Download an ISO](/downloads/), learn how to [verify its authenticity](/doc/verifying-signatures/), and follow our [guide to install Qubes OS](/doc/installation-guide/). Looking for the [source code](/doc/source-code/)? You'll find it [on GitHub](https://github.com/QubesOS).
[Download an ISO](/downloads/), learn how to [verify its
authenticity](/doc/verifying-signatures/), and follow our [guide to install
Qubes OS](/doc/installation-guide/). Looking for the [source
code](/doc/source-code/)? You'll find it [on
GitHub](https://github.com/QubesOS).
## Documentation
Peruse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)!
Peruse our extensive library of [documentation](/doc/) for users and developers
of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)!

94
user/how-to-guides/how-to-update.md
View file

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