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

Merge branch 'md-refactoring-links' of https://github.com/tokideveloper/qubes-doc into tokideveloper-md-refactoring-links

Browse source
This commit is contained in:
Andrew David Wong 2021-04-15 08:57:06 -07:00
commit d2fa42c1e9
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
72 changed files with 733 additions and 1481 deletions
Download patch file Download diff file Expand all files Collapse all files

6
user/advanced-configuration/bind-dirs.md
View file

@ -21,7 +21,7 @@ In a TemplateBasedVM all of the file system comes from the template except `/hom
This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix][whonix]
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## How to use bind-dirs.sh? ##
@ -85,7 +85,7 @@ Note that you must create the full folder structure under `/rw/bind-dirs` - e.g
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
* Some files are altered when a qube boots - e.g. `/etc/hosts`.
If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`][config-file]
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
## How to remove binds from bind-dirs.sh? ##
@ -105,5 +105,3 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)
[config-file]: /doc/config-files
[whonix]: https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5

10
user/advanced-configuration/installing-contributed-packages.md
View file

@ -9,14 +9,14 @@ title: Installing contributed packages
# Installing contributed packages
_This page is for users who wish to install contributed packages.
If you want to contribute a package, please see [package contributions]._
If you want to contribute a package, please see [package contributions](/doc/package-contributions/)._
Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
Qubes OS contributed packages are available under the [QubesOS-contrib](https://github.com/QubesOS-contrib/) GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations](/doc/package-contributions/).
## Installing the repositories
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages.
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib](https://github.com/QubesOS-contrib/) packages.
In dom0, use `qubes-dom0-update`:
@ -57,5 +57,3 @@ sudo qubes-dom0-update --clean qvm-screenshot-tool
Please see the package's README for specific installation and setup instructions.
[package contributions]: /doc/package-contributions/
[QubesOS-contrib]: https://github.com/QubesOS-contrib/

3
user/advanced-configuration/managing-vm-kernel.md
View file

@ -11,7 +11,7 @@ title: Managing VM kernel
# VM kernel managed by dom0
By default, VMs kernels are provided by dom0.
(See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
(See [here](/doc/software-update-dom0/#kernel-upgrade) for information about upgrading kernels in dom0.)
This means that:
1. You can select the kernel version (using GUI VM Settings tool or `qvm-prefs` commandline tool);
@ -363,4 +363,3 @@ update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation.
[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade

3
user/advanced-configuration/resize-disk-image.md
View file

@ -106,6 +106,5 @@ qvm-shutdown qube1
sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
```
If you have a SSD see [here][fstrim] for information on using fstrim.
If you have a SSD see [here](/doc/disk-trim) for information on using fstrim.
[fstrim]: /doc/disk-trim

5
user/advanced-configuration/rpc-policy.md
View file

@ -10,7 +10,7 @@ RPC Policies
============
This document explains the basics of RPC policies in Qubes.
For more information, see [Qrexec: command execution in VMs][qrexec3].
For more information, see [Qrexec: command execution in VMs](/doc/qrexec3/).
Here's an example of an RPC policy file in dom0:
@ -54,9 +54,8 @@ Therefore, parsing will always stop at this rule, and no rules below it will eve
All together, the three rules we added say that all VMs tagged with "work" are allowed to copy files to each other; however, they're denied from copying files to other VMs (without the "work" tag), and other VMs (without the "work" tag) are denied from copying files to them.
The fourth rule means that the user gets prompted for any situation not already covered.
Further details about how this system works can be found in [Qrexec: command execution in VMs][qrexec3].
Further details about how this system works can be found in [Qrexec: command execution in VMs](/doc/qrexec3/).
(***Note**: the `$` character is deprecated in qrexec keywords -- please use `@` instead (e.g. `@anyvm`).
For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)
[qrexec3]: /doc/qrexec3/

53
user/advanced-configuration/salt.md
View file

@ -22,7 +22,7 @@ In the current form the **API is provisional** and subject to change between
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site][salt-doc], though we
For more exhaustive documentation, visit [official site](https://docs.saltstack.com/en/latest/), though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
@ -86,17 +86,17 @@ It executes a command on behalf of the administrator.
`name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
The module used defines which parameters can be passed to it.
There is a list of [officially available states][salt-doc-states].
There is a list of [officially available states](https://docs.saltstack.com/en/latest/ref/states/all/).
There are many very useful states:
- For [managing files][salt-doc-states-file]: Use this to create files or
- For [managing files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html): Use this to create files or
directories and change them (append lines, replace text, set their content etc.)
- For [installing and uninstalling][salt-doc-states-pkg] packages.
- For [executing shell commands][salt-doc-states-cmd].
- For [installing and uninstalling](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html) packages.
- For [executing shell commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html).
With these three states you can define most of the configuration of a VM.
You can also [order the execution][salt-doc-states-order] of your states:
You can also [order the execution](https://docs.saltstack.com/en/latest/ref/states/ordering.html) of your states:
```
D:
@ -121,7 +121,7 @@ A:
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
[require](https://docs.saltstack.com/en/latest/ref/states/requisites.html) and [order](https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option) arguments.
#### State Files
@ -133,7 +133,7 @@ configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
This is done by `*.top` files ([official documentation][salt-doc-top]).
This is done by `*.top` files ([official documentation](https://docs.saltstack.com/en/latest/ref/states/top.html)).
Their structure looks like this:
```
@ -195,15 +195,15 @@ $ qubesctl --all state.highstate
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja][jinja].
This is most commonly done with [Jinja](http://jinja.pocoo.org/).
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation][jinja-tmp].
So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation][jinja-call-salt-functions].
[Salt documentation](https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt).
## Salt Configuration, QubesOS layout
@ -259,7 +259,7 @@ This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the DVM
Template that should be used for management, such as Salt
@ -599,26 +599,11 @@ install template and shutdown updateVM:
## Further Reading
- [Salt documentation][salt-doc]
- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
[packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
- [Top files][salt-doc-top]
- [Jinja templates][jinja]
- [Qubes specific modules][salt-qvm-doc]
- [Formulas for default Qubes VMs][salt-virtual-machines-states]
- [Salt documentation](https://docs.saltstack.com/en/latest/)
- [Salt states](https://docs.saltstack.com/en/latest/ref/states/all/) ([files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html),
[packages](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltstack.com/en/latest/ref/states/ordering.html))
- [Top files](https://docs.saltstack.com/en/latest/ref/states/top.html)
- [Jinja templates](http://jinja.pocoo.org/)
- [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
- [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-pkg]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html
[salt-doc-states-cmd]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-order]: https://docs.saltstack.com/en/latest/ref/states/ordering.html
[salt-doc-states-req]: https://docs.saltstack.com/en/latest/ref/states/requisites.html
[salt-doc-states-ord]: https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option
[salt-doc-top]:https://docs.saltstack.com/en/latest/ref/states/top.html
[jinja]: http://jinja.pocoo.org/
[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt
[QSB #45]: /news/2018/12/03/qsb-45/

2
user/advanced-configuration/secondary-storage.md
View file

@ -114,5 +114,3 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```
[Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/

44
user/advanced-configuration/usb-qubes.md
View file

@ -14,20 +14,20 @@ title: USB Qubes
# USB Qubes #
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube].) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]!
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login](#enable-a-usb-keyboard-for-login)!
## Creating and Using a USB qube ##
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue][2270-comm23].
If you find yourself in this situation, see this [issue](https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312).
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications] of using USB devices.
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications](/doc/device-handling-security/#usb-security) of using USB devices.
With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][PCI Devices] command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci](/doc/pci-devices/) command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices](/doc/usb-devices/#finding-the-right-usb-controller).
You can create a USB qube using the management stack by performing the following steps as root in dom0:
```
@ -36,7 +36,7 @@ sudo qubesctl state.sls qvm.sys-usb
Alternatively, you can create a USB qube manually as follows:
1. Read the [PCI Devices] page to learn how to list and identify your USB controllers.
1. Read the [PCI Devices](/doc/pci-devices/) page to learn how to list and identify your USB controllers.
Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
If you find a free controller, note its name and proceed to step 2.
@ -54,19 +54,19 @@ Alternatively, you can create a USB qube manually as follows:
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
(This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
If the USB qube will not start, please have a look at the [faq].
If the USB qube will not start, please have a look at the [faq](/faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot).
## Enable a USB keyboard for login ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding!
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices).
### Automatic setup ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0:
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates](/doc/software-update-dom0/#how-to-update-dom0)) and execute in dom0:
```
sudo qubesctl state.sls qvm.usb-keyboard
@ -76,7 +76,7 @@ The above command will take care of all required configuration, including creati
Note that it will expose dom0 to USB devices while entering LUKS passphrase.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
To undo these changes, please follow the section on [**Removing a USB qube**][remove your USB-qube]!
To undo these changes, please follow the section on [**Removing a USB qube**](#removing-a-usb-qube)!
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
@ -107,12 +107,12 @@ sys-usb dom0 ask,default_target=dom0
*Don't do that if you want to unlock your device with a USB keyboard!*
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0].
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0](#how-to-hide-all-usb-controllers-from-dom0).
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
## Auto Enabling A USB Mouse ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding.
Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone.
@ -141,7 +141,7 @@ sys-usb dom0 allow
## How to hide all USB controllers from dom0 ##
(Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
This also occurs automatically if you choose to [create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
@ -155,7 +155,7 @@ There are two approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM] device, do not use the second option.
**Warning:** If you use a USB [AEM](/doc/anti-evil-maid/) device, do not use the second option.
Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
If dom0 cannot read your USB AEM device, AEM will hang.
@ -203,15 +203,3 @@ The procedure to hide all USB controllers from dom0 is as follows:
6. Save and close the file.
7. Reboot.
[remove your USB-qube]: #removing-a-usb-qube
[security implications]: /doc/device-handling-security/#usb-security
[enable your keyboard for login]: #enable-a-usb-keyboard-for-login
[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
[PCI Devices]: /doc/pci-devices/
[usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
[faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
[install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
[hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
[AEM]: /doc/anti-evil-maid/
[create a USB qube]: #creating-and-using-a-usb-qube

15
user/common-tasks/backup-emergency-restore-v4.md
View file

@ -23,14 +23,14 @@ any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt]. You
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] first!) Note that versions of
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`.
@ -39,7 +39,7 @@ Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key].
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key](/security/verifying-signatures/#2-get-the-release-signing-key).
2. If you're not on Qubes 4.X, import the Release 4 Signing Key.
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
@ -129,8 +129,8 @@ Emergency Recovery Instructions
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)]
- [Emergency Backup Recovery without Qubes (v3)]
- [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`:
@ -180,8 +180,3 @@ Emergency Recovery Instructions
https://github.com/QubesOS/qubes-doc.git
[scrypt]: https://www.tarsnap.com/scrypt.html
[verify signatures]: /security/verifying-signatures
[get and verify the Release 4 Signing Key]: /security/verifying-signatures/#2-get-the-release-signing-key
[Emergency Backup Recovery without Qubes (v2)]: /doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/

29
user/common-tasks/block-devices.md
View file

@ -13,21 +13,21 @@ title: Block (Storage) Devices
# Block (Storage) Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data".
## Using The GUI to Attach a Drive
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
(**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]
Attaching USB drives is integrated into the Devices Widget: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
Simply insert your USB drive and click on the widget.
You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB].
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device](/doc/usb-devices/).
Entries without a number (e.g. here `sda`) are the whole block-device.
Other entries are partitions of that block-device (e.r. here `sda1`).
@ -58,7 +58,7 @@ Beware that when you attach a whole block device, partitions can be identified b
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].
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
@ -123,7 +123,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
## Recovering From Premature Device Destruction
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
To recover from this error state, in dom0 run
@ -131,13 +131,13 @@ 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].)
(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] 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.
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:
@ -174,11 +174,11 @@ To attach a file as block device to another qube, first turn it into a loopback
sudo losetup -f --show /path/to/file
```
[This command][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.
[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.
Click the Device Manager ![device manager icon](/attachment/wiki/Devices/media-removable.png) and select the `loop0`-device to attach it to another qube.
If you rather use the command line, continue:
@ -256,12 +256,3 @@ qvm-block a work sys-usb:sda1 -o devtype=cdrom
This option accepts `cdrom` and `disk`, default is `disk`.
[device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:/attachment/wiki/Devices/media-removable.png
[frontend-dev]: #frontend-dev
[premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082
[detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm
[losetup]: https://linux.die.net/man/8/losetup
[USB]:/doc/usb-devices/
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082

17
user/common-tasks/device-handling.md
View file

@ -14,10 +14,10 @@ title: Device Handling
# Device Handling
This is an overview of device handling in Qubes OS.
For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages.
For specific devices ([block](/doc/block-devices/), [USB](/doc/usb-devices/) and [PCI](/doc/pci-devices/) devices), please visit their respective pages.
**Important security warning:** Device handling comes with many security implications.
Please make sure you carefully read and understand the **[security considerations]**.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/)**.
## Introduction ##
@ -38,7 +38,7 @@ 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][device manager icon] several device-classes separated by lines are displayed as tooltip.
When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive](/attachment/wiki/Devices/media-removable.png) several device-classes separated by lines are displayed as tooltip.
Block devices are displayed on top, microphones one below and USB-devices at the bottom.
On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
@ -57,7 +57,7 @@ Click on one and your device will be attached!
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]
A list of VMs appears, one showing the eject symbol: ![eject icon](/attachment/wiki/Devices/media-eject.png)
### Attaching a Device to Several VMs ###
@ -65,7 +65,7 @@ A list of VMs appears, one showing the eject symbol: ![eject icon]
Only `mic` should be attached to more than one running VM.
You may *assign* a device to more than one VM (using the `--persistent` option), however, only one of them can be started at the same time.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`](https://github.com/QubesOS/qubes-issues/issues/4692) which will allow you to *attach* a block device to two running VMs.
Don't do that!
@ -158,10 +158,3 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
**SYNOPSIS**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/block-devices/
[USB]:/doc/usb-devices/
[PCI]:/doc/pci-devices/
[security considerations]: /doc/device-handling-security/
[device manager icon]: /attachment/wiki/Devices/media-removable.png
[eject icon]: /attachment/wiki/Devices/media-eject.png
[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692

6
user/common-tasks/disposablevm.md
View file

@ -28,7 +28,7 @@ This diagram provides a general example of how DisposableVMs can be used to safe
## Security
If a [DisposableVM Template] becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
If a [DisposableVM Template](/doc/glossary/#disposablevm-template) becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM.
@ -180,7 +180,7 @@ This line means:
In other words, any VM will be allowed to create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` and open a URL inside of that DisposableVM.
More information about RPC policies for DisposableVMs can be found [here][qrexec].
More information about RPC policies for DisposableVMs can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing DisposableVMs
@ -188,5 +188,3 @@ You can change the template used to generate the DisposableVMs, and change setti
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[qrexec]: /doc/qrexec/#qubes-rpc-administration

61
user/common-tasks/getting-started.md
View file

@ -11,16 +11,16 @@ ref: 190
title: Get Started
---
After [downloading] and [installing] Qubes OS, let's cover some basic concepts.
After [downloading](/downloads/) and [installing](/doc/installation-guide/) Qubes OS, let's cover some basic concepts.
Introduction
------------
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)] called [qubes].
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)](/doc/glossary/#vm) called [qubes](/doc/glossary/#qube).
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a [security domain] (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template], although you can create more templates if you wish.
Instead, each qube represents a [security domain](/doc/glossary/#domain) (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template](/doc/glossary/#templatevm), although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
@ -49,14 +49,14 @@ It's entirely up to you.
![snapshot_40.png](/attachment/wiki/GettingStarted/r4.0-snapshot_40.png)
In addition to qubes and templates, there's one special domain called [dom0], where many system tools and the desktop manager run.
In addition to qubes and templates, there's one special domain called [dom0](/doc/glossary/#dom0), where many system tools and the desktop manager run.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including templates and black-labeled qubes).
If dom0 were ever compromised, it would be "game over."
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the window and desktop managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0][dom0-precautions].
In particular, [you should never run user applications in dom0](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).
(That's what your qubes are for!)
GUI and command-line tools
@ -69,7 +69,7 @@ Opening a terminal in dom0 can be done in several ways:
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools].
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
@ -133,54 +133,31 @@ If you plan on using your system for work, then it also depends on what kind of
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily [copy][copy-files] any files you need to the newly created qube.
You'll also be able to easily [copy](/doc/copying-files/) any files you need to the newly created qube.
Still not sure?
You might find it helpful to read [this article][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains.
You might find it helpful to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes OS architects partitions her digital life into security domains.
Important tasks
---------------
It's very important to [keep Qubes updated][update] to ensure you have the latest security updates.
It's very important to [keep Qubes updated](/doc/updating-qubes-os/) to ensure you have the latest security updates.
Frequently updating is one of the best ways to remain secure against new threats.
It's also very important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
The [Qubes backup system](/doc/backup-restore/) allows you to do this securely and easily.
Here are some other tasks you're likely to want to perform.
(A full list is available in the [Common Tasks] section of the documentation.)
(A full list is available in the [Common Tasks](/doc/#common-tasks) section of the documentation.)
- [Copying and Pasting Text Between Domains][copy-paste]
- [Copying and Moving Files Between Domains][copy-files]
- [Copying from (and to) dom0]
- [Fullscreen Mode]
- [DisposableVMs]
- [Device Handling] (block, USB, and PCI devices)
- [Copying and Pasting Text Between Domains](/doc/copy-paste/)
- [Copying and Moving Files Between Domains](/doc/copying-files/)
- [Copying from (and to) dom0](/doc/copy-from-dom0/)
- [Fullscreen Mode](/doc/full-screen-mode/)
- [DisposableVMs](/doc/disposablevm/)
- [Device Handling](/doc/device-handling/) (block, USB, and PCI devices)
If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.
[getting-started-32]: /getting-started-32/
[downloading]: /downloads/
[installing]: /doc/installation-guide/
[virtual machines (VMs)]: /doc/glossary/#vm
[qubes]: /doc/glossary/#qube
[security domain]: /doc/glossary/#domain
[template]: /doc/glossary/#templatevm
[dom0]: /doc/glossary/#dom0
[dom0-precautions]: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions
[tools]: /doc/tools/
[partitioning]: https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[copy-files]: /doc/copying-files/
[copy-paste]: /doc/copy-paste/
[Copying from (and to) dom0]: /doc/copy-from-dom0/
[Fullscreen Mode]: /doc/full-screen-mode/
[DisposableVMs]: /doc/disposablevm/
[Device Handling]: /doc/device-handling/
[Help, Support, and Mailing Lists]: /support/
If you encounter any problems, please visit the [Help, Support, and Mailing Lists](/support/) page.
<hr class="more-top more-bottom">

24
user/common-tasks/pci-devices.md
View file

@ -13,17 +13,17 @@ title: PCI Devices
# PCI Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
**Warning:** Only dom0 exposes PCI devices.
Some of them are strictly required in dom0 (e.g., the host bridge).
You may end up with an unusable system by attaching the wrong PCI device to a VM.
PCI passthrough should be safe by default, but non-default options may be required.
Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior.
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], [block], mic), PCI devices need to be attached on VM-bootup.
Unlike other devices ([USB](/doc/usb-devices/), [block](/doc/block-devices/), mic), PCI devices need to be attached on VM-bootup.
Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported.
The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install.
@ -31,7 +31,7 @@ While this covers most use cases, there are some occasions when you may want to
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].
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.
@ -45,7 +45,7 @@ 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"!
- Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu](/attachment/wiki/Devices/qubes-appmenu-select.png)\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
- Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
- Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
@ -59,7 +59,7 @@ There you can attach PCI-devices to a qube.
## `qvm-pci` Usage
The `qvm-pci` tool allows PCI attachment and detachment.
It's a shortcut for [`qvm-device pci`][qvm-device].
It's a shortcut for [`qvm-device pci`](/doc/device-handling/#general-qubes-device-widget-behavior-and-handling).
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
@ -93,7 +93,7 @@ Attaching a PCI device through the commandline offers additional options, specif
(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][security considerations]! **Make sure you understand them before continuing!**
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
@ -109,7 +109,7 @@ 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].
This increases attack surface and possibility of [side channel attacks](https://en.wikipedia.org/wiki/Side-channel_attack).
usage example:
@ -143,11 +143,3 @@ or
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
[device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-handling-security/#pci-security
[block]:/doc/block-devices/
[USB]:/doc/usb-devices/
[appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png
[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
[qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack

23
user/common-tasks/software-update-dom0.md
View file

@ -12,10 +12,10 @@ title: Installing and updating software in dom0
# Installing and updating software in dom0
Updating [dom0] is one of the main steps in [Updating Qubes OS].
It is very important to keep dom0 up-to-date with the latest [security] updates.
Updating [dom0](/doc/glossary/#dom0) is one of the main steps in [Updating Qubes OS](/doc/updating-qubes-os/).
It is very important to keep dom0 up-to-date with the latest [security](/security/) updates.
We also publish dom0 updates for various non-security bug fixes and enhancements to Qubes components.
In addition, you may wish to update the kernel, drivers, or libraries in dom0 when [troubleshooting newer hardware].
In addition, you may wish to update the kernel, drivers, or libraries in dom0 when [troubleshooting newer hardware](/doc/newer-hardware-troubleshooting/).
## Security
@ -109,7 +109,7 @@ sudo dnf remove anti-evil-maid
## Testing repositories
There are three Qubes dom0 [testing] repositories:
There are three Qubes dom0 [testing](/doc/testing/) repositories:
- `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository
@ -132,7 +132,7 @@ To enable or disable any of these repos permanently, change the corresponding `e
## Contributed package repository
Please see [installing contributed packages].
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## Kernel upgrade
@ -144,8 +144,8 @@ The packages `kernel` and `kernel-latest` are for dom0.
In the `current` repository:
- `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware])
- `kernel`: an older LTS kernel that has passed Qubes [testing](/doc/testing/) (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing](/doc/testing/) (useful for [troubleshooting newer hardware](/doc/newer-hardware-troubleshooting/))
In the `current-testing` repository:
@ -155,7 +155,7 @@ In the `current-testing` repository:
### domU
The packages `kernel-qubes-vm` and `kernel-latest-qubes-vm` are for domUs.
See [Managing VM kernel] for more information.
See [Managing VM kernel](/doc/managing-vm-kernel/) for more information.
### Example
@ -236,10 +236,3 @@ For example: sys-whonix.
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
`
[dom0]: /doc/glossary/#dom0
[Updating Qubes OS]: /doc/updating-qubes-os/
[security]: /security/
[testing]: /doc/testing/
[troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
[Managing VM kernel]: /doc/managing-vm-kernel/
[installing contributed packages]: /doc/installing-contributed-packages/

34
user/common-tasks/software-update-domu.md
View file

@ -13,8 +13,8 @@ title: Installing and updating software in domUs
# Installing and updating software in domUs
Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are important steps in [Updating Qubes OS].
It is very import to keep domUs up-to-date with the latest [security] updates.
Updating [domUs](/doc/glossary/#domu), especially [TemplateVMs](/doc/templates/) and [StandaloneVMs](/doc/standalone-and-hvm/) are important steps in [Updating Qubes OS](/doc/updating-qubes-os/).
It is very import to keep domUs up-to-date with the latest [security](/security/) updates.
Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer.
## Installing software in TemplateVMs
@ -25,10 +25,10 @@ To permanently install new software in a TemplateVM:
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
5. Restart all [TemplateBasedVMs](/doc/glossary/#templatebasedvm) based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs](/doc/glossary/#templatebasedvm)' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
These new shortcuts will appear in the Applications Menu.
(If you encounter problems, see [here][shortcuts] for troubleshooting.)
(If you encounter problems, see [here](/doc/managing-appvm-shortcuts/) for troubleshooting.)
![[The Applications tab in Qube Settings](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)
@ -45,7 +45,7 @@ Advanced users can execute the standard update command for that operating system
## Testing repositories
If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories.
If you wish to install updates that are still in [testing](/doc/testing), you must enable the appropriate testing repositories.
### Fedora
@ -78,11 +78,11 @@ To enable or disable any of these repos permanently, uncomment the corresponding
## Contributed package repository
Please see [installing contributed packages].
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## StandaloneVMs
When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
When you create a [StandaloneVM](/doc/standalone-and-hvm/) from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
After the moment of creation, the StandaloneVM is completely independent from the TemplateVM.
Therefore, it will not be updated when the TemplateVM is updated.
Rather, it must be updated individually.
@ -94,7 +94,7 @@ The following sections cover advanced topics pertaining to installing and updati
### RPMFusion for Fedora TemplateVMs
If you would like to enable the [RPM Fusion] repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion] for details):
If you would like to enable the [RPM Fusion](https://rpmfusion.org/) repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion](https://rpmfusion.org/) for details):
~~~
sudo dnf config-manager --set-enabled rpmfusion-free
@ -143,7 +143,7 @@ Just make sure to **back up** all of your data and changes first!
#### Reinstall the template
Please see [How to Reinstall a TemplateVM].
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
#### Full revert
@ -176,7 +176,7 @@ Thanks to such configuration all the VMs can use the same proxy address, and if
If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3).
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
There are two services (`qvm-service`, [service framework]):
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
@ -304,15 +304,3 @@ yelp.desktop
Note that the app will autostart only when the AppVM starts. If you would like the AppVM to autostart, select the "Start qube automatically on boot" checkbox in the AppVM's Qube Settings.
[domUs]: /doc/glossary/#domu
[TemplateVMs]: /doc/templates/
[StandaloneVM]: /doc/standalone-and-hvm/
[Updating Qubes OS]: /doc/updating-qubes-os/
[security]: /security/
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[testing]: /doc/testing
[RPM Fusion]: https://rpmfusion.org/
[service framework]: /doc/qubes-service/
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[installing contributed packages]: /doc/installing-contributed-packages/
[shortcuts]: /doc/managing-appvm-shortcuts/

38
user/common-tasks/updating-qubes-os.md
View file

@ -9,16 +9,16 @@ title: Updating Qubes OS
Updating Qubes OS
=================
*This page is about updating your system while staying on the same [supported version of Qubes OS].
If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see the [Upgrade Guides].*
*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/).*
It is very 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.
It is very important to keep your Qubes OS system up-to-date to ensure you have the latest [security](/security/) updates, as well as the latest non-security enhancements and bug fixes.
Fully updating your Qubes OS system means updating:
- [Dom0]
- [TemplateVMs]
- [StandaloneVMs] (if you have any)
- [Dom0](/doc/software-update-dom0/)
- [TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms)
- [StandaloneVMs](/doc/software-update-domu/#standalonevms) (if you have any)
You can accomplish this using the **Qubes Update** tool.
@ -35,24 +35,10 @@ As an alterntaive to the Qubes Update tool, advanced users can update each of th
Visit the pages linked above for details about updating each type.
The final step is to make sure that all of your VMs are running a supported operating system so that they're all receiving upstream security updates.
For example, you might be using a [Fedora TemplateVM].
The [Fedora Project] is independent of the Qubes OS Project.
They set their own [schedule] for when each Fedora release reaches [end-of-life] (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] and publish guides for official TemplateVM operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides] and the [Debian upgrade guides]).
The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
For example, you might be using a [Fedora TemplateVM](/doc/templates/fedora/).
The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project.
They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches [end-of-life](https://fedoraproject.org/wiki/End_of_life) (EOL).
You can always find out when an operating system reaches EOL from the upstream project that maintains it, but we also make EOL [announcements](/news/categories/#announcements) and publish guides for official TemplateVM operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides](/doc/templates/fedora/#upgrading) and the [Debian upgrade guides](/doc/templates/debian/#upgrading)).
The one exception is dom0, which [doesn't have to be upgraded](/doc/supported-versions/#note-on-dom0-and-eol).
[supported version of Qubes OS]: /doc/supported-versions/#qubes-os
[Upgrade Guides]: /doc/upgrade/
[security]: /security/
[Dom0]: /doc/software-update-dom0/
[TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[StandaloneVMs]: /doc/software-update-domu/#standalonevms
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora Project]: https://getfedora.org/
[schedule]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[end-of-life]: https://fedoraproject.org/wiki/End_of_life
[announcements]: /news/categories/#announcements
[Fedora upgrade guides]: /doc/templates/fedora/#upgrading
[Debian upgrade guides]: /doc/templates/debian/#upgrading
[dom0-eol]: /doc/supported-versions/#note-on-dom0-and-eol

52
user/common-tasks/usb-devices.md
View file

@ -10,32 +10,32 @@ title: USB Devices
# USB Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device] page.
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/block-devices/) page.
**Note:** Attaching USB devices to VMs requires a [USB qube][USB-qube howto].
**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
**Important security warning:** USB passthrough comes with many security implications.
Please make sure you carefully read and understand the **[security considerations]**.
Whenever possible, attach a [block device] instead.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
Whenever possible, attach a [block device](/doc/block-devices/) instead.
Examples of valid cases for USB-passthrough:
- [microcontroller programming]
- [external audio devices]
- [optical drives] for recording
- [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][qubes u2f proxy].
But it has some [issues][4661].)
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/).
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
## Attaching And Detaching a USB Device
### With Qubes Device Manager
Click the device-manager-icon: ![device manager icon]
Click the device-manager-icon: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
A list of available devices appears.
USB-devices have a USB-icon to their right: ![usb icon]
USB-devices have a USB-icon to their right: ![usb icon](/attachment/wiki/Devices/generic-usb.png)
Hover on one device to display a list of VMs you may attach it to.
@ -46,7 +46,7 @@ You're done.
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover on the attached device to display a list of running VMs.
The one to which your device is connected will have an eject button ![eject icon] next to it.
The one to which your device is connected will have an eject button ![eject icon](/attachment/wiki/Devices/media-eject.png) next to it.
Click that and your device will be detached.
### With The Command Line Tool
@ -75,7 +75,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
Now, you can use your USB device (camera in this case) in the `work` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section].
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
When you finish, detach the device.
@ -93,7 +93,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
### 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][USB-qube howto].
If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
### Installation Of `qubes-usb-proxy`
@ -108,9 +108,9 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
### 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]** before continuing!
**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][keyboard setup].
Mouse and keyboard setup are part of [setting up a USB-qube](/doc/usb-qubes/#enable-a-usb-keyboard-for-login).
### Finding The Right USB Controller
@ -150,25 +150,9 @@ This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM.
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/pci-devices/) to attach the controller to the targetVM.
For example, On R 4.0 the command would look something like
`qvm-pci attach --persistent personal dom0:00_1a.0`
[device handling in qubes]: /doc/device-handling/
[block device]: /doc/block-devices/
[security considerations]: /doc/device-handling-security/#usb-security
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[usb icon]: /attachment/wiki/Devices/generic-usb.png
[microcontroller programming]: https://www.arduino.cc/en/Main/Howto
[external audio devices]: /doc/external-audio/
[optical drives]: /doc/recording-optical-discs/
[qubes u2f proxy]: /doc/u2f-proxy/
[4661]: https://github.com/QubesOS/qubes-issues/issues/4661
[device manager icon]:/attachment/wiki/Devices/media-removable.png
[eject icon]:/attachment/wiki/Devices/media-eject.png
[Installation Section]:#installation-of-qubes-usb-proxy
[USB-qube howto]: /doc/usb-qubes/
[keyboard setup]: /doc/usb-qubes/#enable-a-usb-keyboard-for-login
[qvm-pci]: /doc/pci-devices/

5
user/downloading-installing-upgrading/custom-install.md
View file

@ -97,7 +97,7 @@ Default compiled-in device cipher parameters:
This means that, by default, Qubes inherits these upstream defaults:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- AES-128 [[1]](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions)[[2]](https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption)[[3]](https://github.com/dyne/Tomb/issues/238)
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
@ -162,6 +162,3 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con
The default file systems are ext4 for `/boot` and `/`, and swap for `swap`.
When you are finished, the Unknown list should go away, and all three mount points should be assigned. Proceed normally with the installation from there.
[cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238

10
user/downloading-installing-upgrading/download-mirrors.md
View file

@ -12,7 +12,7 @@ Qubes Download Mirrors
List of Download Mirrors
------------------------
The full list of known Qubes download mirrors is available [here][mirror-list].
The full list of known Qubes download mirrors is available [here](/downloads/#mirrors).
Instructions for Mirror Operators
---------------------------------
@ -24,10 +24,6 @@ helpful in streamlining the process.
* We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew].
* For technical accommodations, please contact [Wojtek](/team/#wojtek-porczyk) or [Marek](/team/#marek-marczykowski-górecki).
* For website updates and fixes, please contact [Andrew](/team/#andrew-david-wong).
[mirror-list]: /downloads/#mirrors
[Wojtek]: /team/#wojtek-porczyk
[Marek]: /team/#marek-marczykowski-górecki
[Andrew]: /team/#andrew-david-wong

23
user/downloading-installing-upgrading/install-security.md
View file

@ -19,18 +19,18 @@ There are several security matters to consider before and during the Qubes insta
No operating system, not even Qubes, can help you if you're installing it on hardware that is already compromised.
This includes CPUs, GPUs, SSDs, HDDs, the motherboard, BIOS/EFI/UEFI, and all relevant firmware.
Unfortunately, in today's world of undetectable supply chain attacks, there are no easy solutions.
(Tools like [Anti Evil Maid (AEM)][AEM] can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot], [Heads], and [Skulls].
(Tools like [Anti Evil Maid (AEM)](/doc/anti-evil-maid/) can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](http://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
## Verifying the Qubes ISO
You should [verify] the PGP signature on your Qubes ISO before you install from it.
You should [verify](/security/verifying-signatures/) the PGP signature on your Qubes ISO before you install from it.
However, if the machine on which you attempt the verification process is already compromised, it could falsely claim that a malicious ISO has a good signature.
Therefore, in order to be certain that your Qubes ISO is trustworthy, you require a trustworthy machine.
But how can you be certain *that* machine is trustworthy?
Only by using another trusted machine, and so forth.
This is a [classic problem].
While various [solutions] have been proposed, the point is that each user must ultimately make a choice about whether to trust that a file is non-malicious.
This is a [classic problem](https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf).
While various [solutions](https://www.dwheeler.com/trusting-trust/) have been proposed, the point is that each user must ultimately make a choice about whether to trust that a file is non-malicious.
## Choosing an installation medium
@ -43,7 +43,7 @@ From a Qubes-specific security perspective, each has certain pros and cons.
Pros:
* Works via USB, including with a [USB qube].
* Works via USB, including with a [USB qube](/doc/usb-qubes/#creating-and-using-a-usb-qube).
* Non-fixed capacity.
(Easy to find one on which the ISO can fit.)
@ -53,7 +53,7 @@ Cons:
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware.
(Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://srlabs.de/badusb/).
Installing from a compromised drive could compromise even a brand new Qubes installation.)
### Optical discs
@ -79,12 +79,3 @@ Cons:
Considering the pros and cons of each, perhaps a USB drive with non-rewritable (or at least cryptographically-signed) firmware and a physical write-protect switch might be the best option.
[AEM]: /doc/anti-evil-maid/
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
[solutions]: https://www.dwheeler.com/trusting-trust/
[USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube
[BadUSB]: https://srlabs.de/badusb/
[Coreboot]: https://www.coreboot.org/
[Heads]: http://osresearch.net/
[Skulls]: https://github.com/merge/skulls

78
user/downloading-installing-upgrading/installation-guide.md
View file

@ -37,16 +37,16 @@ Please read it carefully and thoroughly, as it contains important information fo
See <a href="/doc/install-security/">installation security</a> for more information.
</div>
Qubes OS has very specific [system requirements].
To ensure compatibility, we strongly recommend using [Qubes-certified hardware].
Qubes OS has very specific [system requirements](/doc/system-requirements/).
To ensure compatibility, we strongly recommend using [Qubes-certified hardware](/doc/certified-hardware/).
Other hardware may require you to perform significant troubleshooting.
You may also find it helpful to consult the [Hardware Compatibility List].
You may also find it helpful to consult the [Hardware Compatibility List](/hcl/).
Even on supported hardware, you must ensure that [IOMMU-based virtualization] is activated in the BIOS.
Even on supported hardware, you must ensure that [IOMMU-based virtualization](https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization) is activated in the BIOS.
Without it, Qubes OS won't be able to enforce isolation.
For Intel-based boards, this setting is called Intel Virtualization for Directed I/O (**Intel VT-d**) and for AMD-based boards, it is called AMD I/O Virtualization Technology (or simply **AMD-Vi**).
This parameter should be activated in your computer's BIOS, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions.
This [external guide][intel-guide] made for Intel-based boards can help you figure out how to enter your BIOS to locate and activate those settings.
This [external guide](https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html) made for Intel-based boards can help you figure out how to enter your BIOS to locate and activate those settings.
If those settings are not nested under the Advanced tab, you might find them under the Security tab.
<div class="alert alert-warning" role="alert">
@ -58,7 +58,7 @@ If those settings are not nested under the Advanced tab, you might find them und
### Copying the ISO onto the installation medium
Start by [downloading][downloads] a Qubes ISO.
Start by [downloading](/downloads/) a Qubes ISO.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
@ -68,7 +68,7 @@ Start by [downloading][downloads] a Qubes ISO.
</div>
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a dual-layer DVD, a Blu-ray disc, or a USB drive.
The size of each Qubes ISO is available on the [downloads] page by hovering over the download button.
The size of each Qubes ISO is available on the [downloads](/downloads/) page by hovering over the download button.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
@ -90,7 +90,7 @@ $ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`).
Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
On Windows, you can use the [Rufus] tool to write the ISO to a USB key.
On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the ISO to a USB key.
MediaTest is not recommended.
Be sure to select "DD image" mode (*after* selecting the Qubes ISO):
@ -103,7 +103,7 @@ Be sure to select "DD image" mode (*after* selecting the Qubes ISO):
![Rufus DD image mode](/attachment/wiki/InstallationGuide/rufus-dd-image-mode.png)
If you are an advanced user, and you would like to customize your installation, please see [custom installation].
If you are an advanced user, and you would like to customize your installation, please see [custom installation](/doc/custom-install/).
Otherwise, follow the instructions below.
## Installation
@ -139,7 +139,7 @@ First, try rebooting your computer.
If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order.
This may require an [advanced reboot].
This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
After the POST, you may have a chance to choose a boot device.
You may wish to select the USB drive or DVD drive as a temporary boot option so that the next time you boot, your internal storage device will be selected first.
@ -160,7 +160,7 @@ If the test fails, a window will pop up.
Do not panic.
It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS.
Return to the [hardware requirements] section to learn how to activate it.
Return to the [hardware requirements](#hardware-requirements) section to learn how to activate it.
If the setting is not configured correctly, it means that your hardware won't be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
If the test passes, you will reach the installation summary screen.
@ -211,18 +211,18 @@ Don't forget to select your time and date by clicking on the Time & Date entry.
On the software selection tab, you can choose which software to install in Qubes OS.
Two options are available:
* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix] qubes.
Whonix allows you to use [Tor] securely within Qubes.
* **Debian:** Select this option if you would like to use [Debian](/doc/templates/debian/) qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix](/doc/whonix/) qubes.
Whonix allows you to use [Tor](https://www.torproject.org/) securely within Qubes.
Whonix lets you route some or all of your network traffic through Tor for greater privacy.
Depending on your threat model, you may need to install Whonix templates right away.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs] later.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs](/doc/templates/) later.
If you're short on disk space, you may wish to deselect these options.
By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment.
Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced configuration]).
Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced configuration](/doc/#advanced-configuration)).
Press **Done** to go back to the installation summary screen.
@ -352,7 +352,7 @@ Congratulations, you are now ready to use Qubes OS!
### Updating
Next, [update] your installation to ensure you have the latest security updates.
Next, [update](/doc/updating-qubes-os/) your installation to ensure you have the latest security updates.
Frequently updating is one of the best ways to remain secure against new threats.
### Security
@ -372,56 +372,26 @@ For more information about Qubes OS Project security, please see the [security c
### Backups
It is extremely important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
The [Qubes backup system](/doc/backup-restore/) allows you to do this securely and easily.
### Submit your HCL report
Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report][hcl-howto].
Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/hcl/#generating-and-submitting-new-reports).
### Get Started
[Get Started] with Qubes, and read more about [Common Tasks] and [Managing Operating Systems within Qubes].
[Get Started](/getting-started/) with Qubes, and read more about [Common Tasks](/doc/#common-tasks) and [Managing Operating Systems within Qubes](/doc/#managing-operating-systems-within-qubes).
## Getting help
* We work very hard to make the [documentation] accurate, comprehensive useful and user friendly.
* We work very hard to make the [documentation](/doc/) accurate, comprehensive useful and user friendly.
We urge you to read it! It may very well contain the answers to your questions.
(Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
(Since the documentation is a community effort, we'd also greatly appreciate your help in [improving](/doc/doc-guidelines/) it!)
* If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide.
* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask.
* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum](/support/) for places to ask.
* Please do **not** email individual members of the Qubes team with questions about installation or other problems.
Instead, please see [Help, Support, Mailing Lists, and Forum] for appropriate places to ask questions.
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions.
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[Qubes-certified hardware]: /doc/certified-hardware/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/
[downloads]: /downloads/
[verifying signatures]: /security/verifying-signatures/
[security considerations]: /doc/install-security/
[Custom Installation]: /doc/custom-install/
[Upgrade Guides]: /doc/upgrade/
[Rufus]: https://rufus.akeo.ie/
[documentation]: /doc/
[improving]: /doc/doc-guidelines/
[Help, Support, Mailing Lists, and Forum]: /support/
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[Managing Operating Systems within Qubes]: /doc/#managing-operating-systems-within-qubes
[installation security]: /doc/install-security/
[IOMMU-based virtualization]: https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization
[intel-guide]: https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html
[advanced reboot]: https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings
[hardware requirements]: #hardware-requirements
[Debian]: /doc/templates/debian/
[Whonix]: /doc/whonix/
[Tor]: https://www.torproject.org/
[TemplateVMs]: /doc/templates/
[advanced configuration]: /doc/#advanced-configuration
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
[Get Started]: /getting-started/

36
user/downloading-installing-upgrading/supported-versions.md
View file

@ -13,9 +13,9 @@ This page details the level and period of support for versions of operating syst
## Qubes OS
Qubes OS releases are supported for **six months** after each subsequent major
or minor release (see [Version Scheme]). The current release and past major
releases are always available on the [Downloads] page, while all ISOs, including
past minor releases, are available from our [download mirrors].
or minor release (see [Version Scheme](/doc/version-scheme/)). The current release and past major
releases are always available on the [Downloads](/downloads/) page, while all ISOs, including
past minor releases, are available from our [download mirrors](/downloads/#mirrors).
| Qubes OS | Start Date | End Date | Status |
| ----------- | ---------- | ---------- | --------------------- |
@ -25,7 +25,7 @@ past minor releases, are available from our [download mirrors].
| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported |
| Release 4.0 | 2018-03-28 | TBA | Supported |
| Release 4.1 | TBA | TBA | [In development][4.1] |
| Release 4.1 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.1%22+) |
### Note on point releases
@ -51,18 +51,18 @@ The table below shows the OS used for dom0 in each Qubes OS release.
### Note on dom0 and EOL
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.).
These components are [security-critical], and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
These components are [security-critical](/doc/security-critical-code/), and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
## TemplateVMs
The following table shows select [TemplateVM] versions that are currently supported.
Currently, only [Fedora] and [Debian] TemplateVMs are officially supported by the Qubes OS Project.
[Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
The following table shows select [TemplateVM](/doc/templates/) versions that are currently supported.
Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) TemplateVMs are officially supported by the Qubes OS Project.
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
Qubes support for each TemplateVM ends when that upstream release reaches end-of-life (EOL), unless otherwise noted.
In the case of Debian, support ends at regular EOL, not [LTS][Debian-LTS] EOL, unless otherwise noted.
In the case of Debian, support ends at regular EOL, not [LTS](https://wiki.debian.org/LTS) EOL, unless otherwise noted.
See [below](#note-on-whonix-support) for Whonix support details.
For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debian-eol].
For upstream EOL information, see [Fedora EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian EOL](https://wiki.debian.org/DebianReleases).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ---------------------------- | ------ |
@ -73,7 +73,7 @@ For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debi
### Note on Whonix support
[Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
The Whonix Project has set its own support policy for Whonix TemplateVMs in Qubes.
This policy requires Whonix TemplateVM users to stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix TemplateVMs within a month of their respective releases.
@ -87,17 +87,3 @@ To be precise:
We aim to announce both types of events one month in advance in order to remind users to upgrade.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors
[security-critical]: /doc/security-critical-code/
[TemplateVM]: /doc/templates/
[extended support]: /news/2018/03/28/qubes-40/#the-past-and-the-future
[4.1]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.1%22+
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[fedora-eol]: https://fedoraproject.org/wiki/End_of_life
[debian-eol]: https://wiki.debian.org/DebianReleases
[Whonix]: /doc/whonix/
[Whonix Project]: https://www.whonix.org/
[Debian-LTS]: https://wiki.debian.org/LTS

30
user/downloading-installing-upgrading/testing.md
View file

@ -9,7 +9,7 @@ title: Testing New Releases and Updates
Testing New Releases and Updates
================================
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute] to the Qubes OS Project.
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute](/doc/contributing/) to the Qubes OS Project.
However, you should only attempt to do this if you know what you're doing.
Never rely on code that is in testing for critical work!
@ -18,26 +18,26 @@ Releases
How to test upcoming Qubes OS releases:
* Use [qubes-builder] to build the latest release.
* Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
* Test the latest release candidate (RC), if any is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
See [Version Scheme] for details about release versions and schedules.
See [Release Checklist] for details about the RC process.
See [Version Scheme](/doc/version-scheme/) for details about release versions and schedules.
See [Release Checklist](/doc/releases/todo/) for details about the RC process.
Updates
-------
How to test updates:
* Enable [dom0 testing repositories].
* Enable [TemplateVM testing repositories].
* Enable [dom0 testing repositories](/doc/software-update-dom0/#testing-repositories).
* Enable [TemplateVM testing repositories](/doc/software-update-domu/#testing-repositories).
Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update.
The update remains in `security-testing` or `current-testing` for a minimum of one week.
On occasion, an exception is made for a particularly critical security update, which is immediately pushed to the `current` stable repository.
In general, however, security updates remain in `security-testing` for two weeks before migrating to `current`.
Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can weeks or even months, depending on the amount of feedback received (see [Providing Feedback]).
Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can weeks or even months, depending on the amount of feedback received (see [Providing Feedback](#providing-feedback)).
"Sufficient testing" is, in practice, a fluid term that is up the developers' judgment. In general, it means either that no negative feedback and at least one piece of positive feedback has been received or that the package has been in `current-testing` for long enough, depending on the component and the complexity of the changes.
A limitation of the current testing setup is that it is only possible to migrate the *most recent version* of a package from `current-testing` to `current`.
@ -49,19 +49,9 @@ Providing Feedback
If you're testing new releases or updates, we would be grateful for your feedback.
We use an [automated build process].
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status] repository for tracking purposes.
We use an [automated build process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md).
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository for tracking purposes.
We welcome any kind of feedback on any package in any testing repository.
Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository.
If you [report a bug] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
If you [report a bug](/doc/reporting-bugs/) in a package that is in a testing repository, please reference the appropriate issue in [updates-status](https://github.com/QubesOS/updates-status/issues).
[contribute]: /doc/contributing/
[qubes-builder]: /doc/qubes-builder/
[Version Scheme]: /doc/version-scheme/
[Release Checklist]: /doc/releases/todo/
[dom0 testing repositories]: /doc/software-update-dom0/#testing-repositories
[TemplateVM testing repositories]: /doc/software-update-domu/#testing-repositories
[automated build process]: https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md
[updates-status]: https://github.com/QubesOS/updates-status/issues
[report a bug]: /doc/reporting-bugs/
[Providing Feedback]: #providing-feedback

5
user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md
View file

@ -44,7 +44,7 @@ Backup R3.2
7. If your backup verifies successfully, proceed to the next section.
If it does not, **stop**.
Go back and repeat the backup steps, review the documentation, and ask for [help].
Go back and repeat the backup steps, review the documentation, and ask for [help](/support/).
Install R4.0
------------
@ -61,7 +61,7 @@ For further details, please see the [installation guide](/doc/installation-guide
If you did not successfully verify your backup in the previous section, cancel the installation, and go back to do that now.
3. Complete the R4.0 installation.
Ask for [help] if you run into trouble.
Ask for [help](/support/) if you run into trouble.
4. If you are unable to successfully install R4.0 on your system, all is not lost.
Use the R3.2 installer to reinstall R3.2, then restore from your backup.
@ -119,4 +119,3 @@ Please see [Supported Versions](/doc/supported-versions/) for information on sup
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)
[help]: /support/

3
user/downloading-installing-upgrading/upgrade/upgrade.md
View file

@ -10,7 +10,7 @@ Qubes OS Upgrade Guides
=======================
These guides are for upgrading from one version of Qubes to another.
If you're just looking to update your system while staying on the same version, see [Updating Qubes OS].
If you're just looking to update your system while staying on the same version, see [Updating Qubes OS](/doc/updating-qubes-os/).
* [Upgrading from R1 to R2 Beta 1](/doc/upgrade-to-r2b1/)
* [Upgrading from R1 to R2 Beta 2](/doc/upgrade-to-r2b2/)
@ -21,4 +21,3 @@ If you're just looking to update your system while staying on the same version,
* [Upgrading from R3.1 to R3.2](/doc/upgrade-to-r3.2/)
* [Upgrading from R3.2 to R4.0](/doc/upgrade-to-r4.0/)
[Updating Qubes OS]: /doc/updating-qubes-os/

3
user/downloading-installing-upgrading/version-scheme.md
View file

@ -42,7 +42,7 @@ When enough development has been made, we announce the first stable version,
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
we support it for some period. Core components are branched at this moment and
bugfixes are backported from master branch. Please see [Help, Support, Mailing
Lists, and Forum] for places to ask questions about stable releases. No major
Lists, and Forum](/support/) for places to ask questions about stable releases. No major
features and interface incompatibilities are to be included in this release. We
release bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the
next release e.g. `3.1-rcX`.
@ -158,4 +158,3 @@ Check installed version
If you want to know which version you are running, for example to report
an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal.
[Help, Support, Mailing Lists, and Forum]: /support/

53
user/hardware/certified-hardware.md
View file

@ -18,25 +18,25 @@ Note, however, that we certify only that a particular hardware *configuration* i
We take no responsibility for our partners' manufacturing or shipping processes, nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user.
There are also other hardware models on which we have tested Qubes OS.
See [Hardware Testing] for details.
See [Hardware Testing](/doc/hardware-testing/) for details.
## Qubes-certified Laptops
Qubes-certified laptops are certified for a [major version][version-scheme] and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major version.
Qubes-certified laptops are certified for a [major version](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major version.
The developers test all new updates within that major version to ensure that no regressions are introduced.
### Insurgo PrivacyBeast X230
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)][Insurgo PrivacyBeast X230]
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast X230] meets and exceeds our hardware certification requirements for Qubes 4.
Read our [announcement][privacybeast announcement] of the certification for further details!
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) meets and exceeds our hardware certification requirements for Qubes 4.
Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) of the certification for further details!
### NitroPad X230
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)][NitroPad X230]
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230] satisfies all hardware certification requirements for Qubes 4, offering users extensive hardware security options.
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) satisfies all hardware certification requirements for Qubes 4, offering users extensive hardware security options.
## Become Hardware Certified
@ -52,18 +52,18 @@ The benefits of hardware certification include:
## Hardware Certification Requirements
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes.
For the latter, please see the [system requirements].)
For the latter, please see the [system requirements](/doc/system-requirements/).)
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT]), also known as [EPT][EPT-enabled CPUs] in Intel parlance.
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance.
SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach.
We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148], which --- unlike many other major Xen bugs --- regrettably did [affect][QSB 22] Qubes OS.
We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS.
Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot].
The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP]) as well as other internal operations (see [Intel ME]).
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot](https://www.coreboot.org/).
The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other internal operations (see [Intel ME](https://www.apress.com/9781430265719)).
However, we specifically require all code used for and dealing with the System Management Mode (SMM) to be open-source.
While we [recognize][x86_harmful] the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop].
While we [recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf).
A switch to open source boot firmware is one such important step.
To be compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and SLAT functionality that the underlying hardware offers (and which we require).
Among other things, this implies **proper DMAR ACPI table** construction.
@ -76,7 +76,7 @@ The rest of the time, they should be outside the reach of malware.
While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).
Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth devices to be mandatory.
Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers][audio_modem]!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
We hope these hardware requirements will encourage the development of more secure and trustworthy devices.
@ -89,29 +89,8 @@ To have hardware certified, the vendor must:
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team.
It is the vendor's responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version.
This could be done by consulting the [Hardware Compatibility List] or trying to install it themselves before shipping any units to us.
This could be done by consulting the [Hardware Compatibility List](/hcl/) or trying to install it themselves before shipping any units to us.
While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
If you are interested in having your hardware certified, please [contact us].
If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org).
[version-scheme]: /doc/version-scheme/
[Hardware Testing]: /doc/hardware-testing/
[stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: #hardware-certification
[system requirements]: /doc/system-requirements/
[contact us]: mailto:business@qubes-os.org
[SLAT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation
[EPT-enabled CPUs]: https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile
[XSA-148]: https://xenbits.xen.org/xsa/advisory-148.html
[QSB 22]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt
[pvh_ticket]: https://github.com/QubesOS/qubes-issues/issues/2185
[coreboot]: https://www.coreboot.org/
[Intel FSP]: https://firmware.intel.com/learn/fsp/about-intel-fsp
[Intel ME]: https://www.apress.com/9781430265719
[x86_harmful]: https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf
[stateless laptop]: https://blog.invisiblethings.org/papers/2015/state_harmful.pdf
[audio_modem]: https://github.com/romanz/amodem/
[Insurgo PrivacyBeast X230]: https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/
[privacybeast announcement]: /news/2019/07/18/insurgo-privacybeast-qubes-certification/
[NitroPad X230]: https://shop.nitrokey.com/shop/product/nitropad-x230-67

8
user/hardware/hardware-testing.md
View file

@ -9,7 +9,7 @@ title: Hardware Testing
# Hardware Testing
The Qubes developers test Qubes OS on certain hardware models.
The tested hardware described on this page differs from [Qubes Certified Hardware] in a few key ways:
The tested hardware described on this page differs from [Qubes Certified Hardware](/doc/certified-hardware/) in a few key ways:
- Qubes Certified Hardware has to meet more demanding standards than hardware that is merely tested.
- All Qubes Certified Hardware is tested, but not all tested hardware is certified.
@ -17,9 +17,9 @@ The tested hardware described on this page differs from [Qubes Certified Hardwar
In general, you can think of tested hardware as "unofficial recommended" hardware:
- [Qubes Certified Hardware] --- Qubes developer certified, officially recommended
- [Qubes Certified Hardware](/doc/certified-hardware/) --- Qubes developer certified, officially recommended
- Hardware Testing (this page) --- Qubes developer tested, unofficially recommended
- [Hardware Compatibility List (HCL)] --- community test results, neither recommended nor disrecommended
- [Hardware Compatibility List (HCL)](/hcl/) --- community test results, neither recommended nor disrecommended
## Tested Models
@ -40,5 +40,3 @@ If anyone is willing to lend or donate these models to us, we would be happy to
Note: The Lenovo X and T series are similar enough to assume similar compatibility of the matching model from the other series.
[Qubes Certified Hardware]: /doc/certified-hardware/
[Hardware Compatibility List (HCL)]: /hcl/

5
user/hardware/hcl.md
View file

@ -31,7 +31,7 @@ If using the list to make a purchasing decision, we recommend that you choose ha
- the best achievable Qubes security level (green columns in HVM, IOMMU, TPM)
- and general machine compatibility (green columns in Qubes version, dom0 kernel, remarks).
Also see [Certified Hardware] and [Hardware Testing].
Also see [Certified Hardware](/doc/certified-hardware/) and [Hardware Testing](/doc/hardware-testing/).
Generating and Submitting New Reports
-------------------------------------
@ -49,6 +49,3 @@ Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To ge
**Please note:**
The **HCL Support Files** may contain numerous hardware details, including serial numbers. If, for privacy or security reasons, you do not wish to make this information public, please **do not** send the `.cpio.gz` file to the public mailing list.
[Certified Hardware]: /doc/certified-hardware/
[Hardware Testing]: /doc/hardware-testing/

41
user/hardware/system-requirements.md
View file

@ -24,32 +24,32 @@ title: System Requirements
## Minimum
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 4 GB RAM
- **Storage:** 32 GB free space
## Recommended
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 16 GB RAM
- **Storage:** 128 GB free space
- High-speed solid-state drive strongly recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant [troubleshooting][nvidia]
- Nvidia GPUs may require significant [troubleshooting](/doc/install-nvidia-driver/)
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and earlier) generally work well
- **Peripherals:** A non-USB keyboard or multiple USB controllers
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for [Anti Evil Maid])
- **Other:** Satisfaction of all [hardware certification requirements for Qubes 4.x]
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for [Anti Evil Maid](/doc/anti-evil-maid/))
- **Other:** Satisfaction of all [hardware certification requirements for Qubes 4.x](/news/2016/07/21/new-hw-certification-for-q4/)
## Choosing Hardware
- Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here][hcl-doc].)
- See the [Certified Hardware] page.
- See the [Hardware Testing] page.
- Please see the [Hardware Compatibility List](/hcl/) for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here](/doc/hcl/).)
- See the [Certified Hardware](/doc/certified-hardware/) page.
- See the [Hardware Testing](/doc/hardware-testing/) page.
## Important Notes
@ -62,23 +62,8 @@ title: System Requirements
After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes.
In addition to the convenience of having a portable copy of Qubes, this allows users to test for hardware compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase.
(See [hcl-report] for advice on hardware compatibility testing.)
(See [hcl-report](/doc/hcl/#generating-and-submitting-new-reports) for advice on hardware compatibility testing.)
Remember to change the devices assigned to your NetVM and USBVM if you move between different machines.
- [Advice on finding a VT-d capable notebook][vt-d-notebook].
- [Advice on finding a VT-d capable notebook](https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J).
- You can check whether an Intel processor has VT-x and VT-d on [ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
[nvidia]: /doc/install-nvidia-driver/
[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/
[Certified Hardware]: /doc/certified-hardware/
[Hardware Testing]: /doc/hardware-testing/
[Hardware Compatibility List]: /hcl/
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J
[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29
[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29
[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d
[AMD-Vi (also known as AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables
[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing

35
user/managing-os/debian/debian-upgrade.md
View file

@ -14,10 +14,10 @@ title: In-place upgrade of Debian TemplateVMs
# Upgrading Debian TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM].
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead. ([Learn more about the two options.][Debian TemplateVM Upgrade])
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM](/doc/templates/debian/).
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system][upgrade].
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
## Summary instructions for Debian TemplateVMs
@ -34,7 +34,7 @@ In general, upgrading a Debian TemplateVM follows the same process as [upgrading
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for Debian TemplateVMs
@ -87,8 +87,8 @@ The same general procedure may be used to upgrade any template based on the stan
```
7. (Optional) Trim the new template.
(This should [no longer be necessary][template-notes], but it does not hurt.
Some users have [reported][5055] that it makes a difference.)
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
```
[user@debian-<new> ~]$ sudo fstrim -av
@ -103,7 +103,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
9. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
9. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
10. (Optional) Make the new template the global default.
@ -120,7 +120,7 @@ The same general procedure may be used to upgrade any template based on the stan
## StandaloneVMs
The procedure for upgrading a Debian [StandaloneVM] is the same as for a TemplateVM.
The procedure for upgrading a Debian [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
## Release-specific notes
@ -128,7 +128,7 @@ This section contains notes about upgrading to specific releases.
### Debian 10 ("Buster")
Please see [Debian's Buster upgrade instructions][buster].
Please see [Debian's Buster upgrade instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
### Debian 9 ("Stretch")
@ -148,15 +148,15 @@ Relevant discussions:
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)
Also see [Debian's Stretch upgrade instructions][stretch].
Also see [Debian's Stretch upgrade instructions](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
### Debian 8 ("Jessie")
Please see [Debian's Jessie upgrade instructions][jessie].
Please see [Debian's Jessie upgrade instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
### End-of-life (EOL) releases
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)].
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)](https://wiki.debian.org/DebianReleases#Production_Releases).
## Additional information
@ -166,14 +166,3 @@ We strongly recommend against using any Debian release that has reached [end-of-
* By default, Qubes uses code names in the `apt` sources files, although the templates are referred to by release number.
Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.
[Debian TemplateVM]: /doc/templates/debian/
[Debian TemplateVM Upgrade]: /doc/templates/debian/#upgrading
[upgrade]: https://wiki.debian.org/DebianUpgrade
[switch]: /doc/templates/#switching
[jessie]: https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html
[stretch]: https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html
[buster]: https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html
[end-of-life (EOL)]: https://wiki.debian.org/DebianReleases#Production_Releases
[StandaloneVM]: /doc/standalone-and-hvm/
[template-notes]: /doc/templates/#important-notes
[5055]: https://github.com/QubesOS/qubes-issues/issues/5055

35
user/managing-os/debian/debian.md
View file

@ -13,14 +13,14 @@ title: The Debian TemplateVM
# The Debian TemplateVM
The Debian [TemplateVM] is an officially [supported] TemplateVM in Qubes OS.
The Debian [TemplateVM](/doc/templates/) is an officially [supported](/doc/supported-versions/#templatevms) TemplateVM in Qubes OS.
This page is about the standard (or "full") Debian TemplateVM.
For the minimal version, please see the [Minimal TemplateVMs] page.
There is also a [Qubes page on the Debian Wiki].
For the minimal version, please see the [Minimal TemplateVMs](/doc/templates/minimal/) page.
There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
## Installing
To [install] a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-debian-XX
@ -28,29 +28,29 @@ $ sudo qubes-dom0-update qubes-template-debian-XX
(Replace `XX` with the Debian version number of the template you wish to install.)
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## After Installing
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
## Updating
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs].
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Debian release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- [Perform an in-place upgrade of an existing Debian template.][Upgrading Debian TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
- [Perform an in-place upgrade of an existing Debian template.](/doc/template/debian/upgrade/) This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
## Release-specific notes
@ -108,16 +108,3 @@ The lesson is that you should carefully look at what is being installed to your
If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors)
[TemplateVM]: /doc/templates/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Qubes page on the Debian Wiki]: https://wiki.debian.org/Qubes
[end-of-life]: https://wiki.debian.org/DebianReleases#Production_Releases
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[Upgrading Debian TemplateVMs]: /doc/template/debian/upgrade/
[5149]: https://github.com/QubesOS/qubes-issues/issues/5149
[install]: /doc/templates/#installing

40
user/managing-os/fedora/fedora-upgrade.md
View file

@ -25,8 +25,8 @@ title: In-place upgrade of Fedora TemplateVMs
# Upgrading Fedora TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM].
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead. ([Learn more about the two options.][Fedora TemplateVM Upgrade])
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM](/doc/templates/fedora/).
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM](/doc/templates/fedora/) page instead. ([Learn more about the two options.](/doc/templates/fedora/#upgrading))
## Summary instructions for standard Fedora TemplateVMs
@ -47,7 +47,7 @@ If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
```
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for standard Fedora TemplateVMs
@ -120,8 +120,8 @@ The same general procedure may be used to upgrade any template based on the stan
At least X MB more space needed on the / filesystem.
`
In this case, one option is to [resize the TemplateVM's disk image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
In this case, one option is to [resize the TemplateVM's disk image](/doc/resize-disk-image/) before reattempting the upgrade process.
(See [Additional Information](#additional-information) below for other options.)
4. Check that you are on the correct (new) Fedora release.
@ -130,8 +130,8 @@ The same general procedure may be used to upgrade any template based on the stan
```
5. (Optional) Trim the new template.
(This should [no longer be necessary][template-notes], but it does not hurt.
Some users have [reported][5055] that it makes a difference.)
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
```
[user@fedora-<new> ~]$ sudo fstrim -av
@ -153,7 +153,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
```
8. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
8. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
9. (Optional) Make the new template the global default.
@ -186,18 +186,18 @@ The same general procedure may be used to upgrade any template based on the stan
## StandaloneVMs
The procedure for upgrading a Fedora [StandaloneVM] is the same as for a TemplateVM.
The procedure for upgrading a Fedora [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
## Release-specific notes
See the [news] announcement for each specific TemplateVM release for any important notices about that particular release.
See the [news](/news/) announcement for each specific TemplateVM release for any important notices about that particular release.
### End-of-life (EOL) releases
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)].
Also see [supported versions].
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life).
Also see [supported versions](/doc/supported-versions/).
## Additional information
@ -210,24 +210,12 @@ At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/).
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by uninstalling packages.
You may then reinstall them again after you finish the upgrade process, if desired).
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs].
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading).
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora TemplateVM Upgrade]: /doc/templates/fedora/#upgrading
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[switch]: /doc/templates/#switching
[DispVM]: /doc/dispvm/
[end-of-life (EOL)]: https://fedoraproject.org/wiki/End_of_life
[StandaloneVM]: /doc/standalone-and-hvm/
[template-notes]: /doc/templates/#important-notes
[5055]: https://github.com/QubesOS/qubes-issues/issues/5055
[supported versions]: /doc/supported-versions/
[news]: /news/

30
user/managing-os/fedora/fedora.md
View file

@ -8,11 +8,11 @@ title: The Fedora TemplateVM
# The Fedora TemplateVM
The Fedora [TemplateVM] is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages.
The Fedora [TemplateVM](/doc/templates/) is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs](/doc/templates/minimal/) and [Xfce TemplateVMs](/doc/templates/xfce/) pages.
## Installing
To [install] a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-fedora-XX
@ -20,39 +20,27 @@ $ sudo qubes-dom0-update qubes-template-fedora-XX
(Replace `XX` with the Fedora version number of the template you wish to install.)
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## After Installing
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
## Updating
For routine daily updates within a given release, see [Updating software in TemplateVMs].
For routine daily updates within a given release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Fedora release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
- [Perform an in-place upgrade of an existing Fedora template.][Upgrading Fedora TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
- [Perform an in-place upgrade of an existing Fedora template.](/doc/template/fedora/upgrade/) This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
[TemplateVM]: /doc/templates/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Xfce TemplateVMs]: /doc/templates/xfce/
[end-of-life]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/
[install]: /doc/templates/#installing

27
user/managing-os/minimal-templates.md
View file

@ -15,10 +15,10 @@ title: Minimal TemplateVMs
# Minimal TemplateVMs
The Minimal [TemplateVMs] are lightweight versions of their standard TemplateVM counterparts.
The Minimal [TemplateVMs](/doc/templates/) are lightweight versions of their standard TemplateVM counterparts.
They have only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora], [Debian], [CentOS] and [Gentoo] TemplateVMs.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/) and [Gentoo](/doc/templates/gentoo/) TemplateVMs.
## Important
@ -27,11 +27,11 @@ There are currently three Minimal TemplateVMs corresponding to the standard [Fed
2. If something works with a standard TemplateVM but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, please do *not* file a bug report.
Instead, please see [Help, Support, Mailing Lists, and Forum] for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation][doc-guidelines].
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation](/doc/doc-guidelines/).
3. The Minimal TemplateVMs are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
[Do not ask for your favorite package to be added to the minimal template by default.](/faq/#could-you-please-make-my-preference-the-default)
4. In order to reduce unnecessary risk, unused repositories have been disabled by default.
If you wish to install or update any packages from those repositories, you must enable them.
@ -44,7 +44,7 @@ The Minimal TemplateVMs can be installed with the following command (where `X` i
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-minimal
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -61,7 +61,7 @@ The download may take a while depending on your connection speed.
## Passwordless root
It is an intentional design choice for [Passwordless Root Access in VMs] to be optional in Minimal TemplateVMs.
It is an intentional design choice for [Passwordless Root Access in VMs](/doc/vm-sudo/) to be optional in Minimal TemplateVMs.
Since the Minimal TemplateVMs are *minimal*, they are not configured for passwordless root by default.
To update or install packages, execute the following command in dom0 (where `X` is your distro and version number):
@ -131,7 +131,7 @@ Also, there are packages to provide additional services:
You may also wish to consider additional packages from the `qubes-core-agent` suite:
See [here][customization] for further information on customizing `fedora-minimal`.
See [here](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md) for further information on customizing `fedora-minimal`.
#### Logging
@ -221,14 +221,3 @@ Documentation on all of these can be found in the [docs](/doc)
You could, of course, use `qubes-vm-recommended` to automatically install many of these, but in that case you are well on the way to a standard Debian template.
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[Gentoo]: /doc/templates/gentoo/
[Help, Support, Mailing Lists, and Forum]: /support/
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[testing]: /doc/testing/
[customization]: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md
[Passwordless Root Access in VMs]: /doc/vm-sudo/

3
user/managing-os/reinstall-template.md
View file

@ -11,7 +11,7 @@ title: How to Reinstall a TemplateVM
How to Reinstall a TemplateVM
=============================
If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
If you suspect your [TemplateVM](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
Automatic Method
----------------
@ -92,4 +92,3 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for
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.
[TemplateVM]: /doc/templates/

96
user/managing-os/templates.md
View file

@ -13,9 +13,9 @@ title: TemplateVMs
# TemplateVMs
In [Getting Started], we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software.
Your software is installed in [TemplateVMs] (or "templates" for short).
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs].
In [Getting Started](/getting-started/), we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software.
Your software is installed in [TemplateVMs](/doc/glossary/#templatevm) (or "templates" for short).
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs](/doc/glossary/#templatebasedvm).
TemplateBasedVMs are where you run your software and store your data.
The TemplateVM system has significant benefits:
@ -25,7 +25,7 @@ The TemplateVM system has significant benefits:
* **Speed:** It is extremely fast to create new TemplateBasedVMs, since the root filesystem already exists in the TemplateVM.
* **Updates:** Updates are naturally centralized, since updating a TemplateVM means that all qubes based on it will automatically use those updates after they're restarted.
An important side effect of this system is that any software installed in a TemplateBasedVM (rather than in the TemplateVM on which it is based) will disappear after the TemplateBasedVM reboots (see [Inheritance and Persistence]).
An important side effect of this system is that any software installed in a TemplateBasedVM (rather than in the TemplateVM on which it is based) will disappear after the TemplateBasedVM reboots (see [Inheritance and Persistence](#inheritance-and-persistence)).
For this reason, we recommend installing most of your software in TemplateVMs, not TemplateBasedVMs.
The default TemplateVM in Qubes is based on Fedora, but there are additional templates based on other Linux distributions.
@ -42,11 +42,11 @@ These are the official Qubes OS Project templates.
We build and release updates for these templates.
We guarantee that the binary updates are compiled from exactly the same source code as we publish.
* [Fedora] (default)
* [Fedora Minimal]
* [Fedora Xfce]
* [Debian]
* [Debian Minimal]
* [Fedora](/doc/templates/fedora/) (default)
* [Fedora Minimal](/doc/templates/minimal/)
* [Fedora Xfce](/doc/templates/xfce)
* [Debian](/doc/templates/debian/)
* [Debian Minimal](/doc/templates/minimal/)
## Community
@ -58,21 +58,21 @@ However, such updates may be provided by the template maintainer.
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer.
In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
* [Whonix]
* [Ubuntu]
* [Arch Linux]
* [CentOS]
* [CentOS Minimal]
* [Gentoo]
* [Gentoo Minimal]
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Arch Linux](/doc/building-archlinux-template/)
* [CentOS](/doc/templates/centos/)
* [CentOS Minimal](/doc/templates/minimal/)
* [Gentoo](/doc/templates/gentoo/)
* [Gentoo Minimal](/doc/templates/minimal/)
## Installing
Certain TemplateVMs come preinstalled with Qubes OS.
However, there may be times when you wish to install a fresh TemplateVM from the Qubes repositories, e.g.:
* When a TemplateVM version you're using reaches [end-of-life][supported].
* When a new version of a TemplateVM that you wish to use becomes [supported].
* When a TemplateVM version you're using reaches [end-of-life](/doc/supported-versions/).
* When a new version of a TemplateVM that you wish to use becomes [supported](/doc/supported-versions/).
* When you suspect your TemplateVM has been compromised.
* When you have made modifications to your TemplateVM that you no longer want.
@ -91,22 +91,22 @@ If you wish to install a community template, you must enable the community templ
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<name>
```
If you receive the message that no match is found for `qubes-template-<name>`, see [here][no-match].
If you receive the message that no match is found for `qubes-template-<name>`, see [here](/faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found).
## After Installing
After installing a fresh TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](#updating).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](#uninstalling).
## Updating
Updating TemplateVMs is an important part of [Updating Qubes OS].
Please see [Updating software in TemplateVMs].
Updating TemplateVMs is an important part of [Updating Qubes OS](/doc/updating-qubes-os/).
Please see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Uninstalling
@ -137,7 +137,7 @@ warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file
These are normal and expected. Nothing is wrong, and no action is required to address these warnings.
If this uninstallation command doesn't work, please see [How to Remove VMs Manually].
If this uninstallation command doesn't work, please see [How to Remove VMs Manually](/doc/remove-vm-manually/).
If the Applications Menu entry doesn't go away after you uninstall a TemplateVM, execute the following type of command in dom0:
@ -153,7 +153,7 @@ $ rm /usr/local/share/applications/<template_vm_name>
## Reinstalling
Please see [How to Reinstall a TemplateVM].
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## Switching
@ -179,7 +179,7 @@ When you install a new template or upgrade a clone of a template, it is recommen
Applications Menu --> System Tools --> Qubes Template Manager
`
4. Base the [DisposableVM Template] on the new template.
4. Base the [DisposableVM Template](/doc/glossary/#disposablevm-template) on the new template.
```
[user@dom0 ~]$ qvm-create -l red -t <new_template> <new_template_dvm>
@ -208,7 +208,7 @@ No changes in any other directories in TemplateBasedVMs persist in this manner.
(1) Upon creation
(2) Following shutdown
(3) Including any [DisposableVM Templates]
(3) Including any [DisposableVM Templates](/doc/glossary/#disposablevm-template)
### Trusting your TemplateVMs
@ -274,45 +274,13 @@ Note the word "clean" means in this context: the same as their template filesyst
* `qvm-trim-template` is no longer necessary or available in Qubes 4.0 and higher.
All VMs are created in a thin pool and trimming is handled automatically.
No user action is required.
See [Disk Trim] for more information.
See [Disk Trim](/doc/disk-trim) for more information.
* RPM-installed templates are "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
* Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder].
* Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/).
In particular, some template "flavors" are available in source code form only.
For the technical details of the template system, please see [TemplateVM Implementation].
Take a look at the [Qubes Builder] documentation for instructions on how to compile them.
For the technical details of the template system, please see [TemplateVM Implementation](/doc/template-implementation/).
Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for instructions on how to compile them.
[Getting Started]: /getting-started/
[TemplateVMs]: /doc/glossary/#templatevm
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[Fedora]: /doc/templates/fedora/
[Fedora Minimal]: /doc/templates/minimal/
[Fedora Xfce]: /doc/templates/xfce
[Debian]: /doc/templates/debian/
[Debian Minimal]: /doc/templates/minimal/
[Whonix]: /doc/templates/whonix/
[Ubuntu]: /doc/templates/ubuntu/
[Arch Linux]: /doc/building-archlinux-template/
[CentOS]: /doc/templates/centos/
[CentOS Minimal]: /doc/templates/minimal/
[CentOS Xfce]: /doc/templates/xfce
[Gentoo]: /doc/templates/gentoo/
[Gentoo Minimal]: /doc/templates/minimal/
[Gentoo Xfce]: /doc/templates/xfce
[Qubes Builder]: /doc/qubes-builder/
[TemplateVM Implementation]: /doc/template-implementation/
[How to Remove VMs Manually]: /doc/remove-vm-manually/
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[DisposableVM Templates]: /doc/glossary/#disposablevm-template
[Updating Qubes OS]: /doc/updating-qubes-os/
[Disk Trim]: /doc/disk-trim
[Inheritance and Persistence]: #inheritance-and-persistence
[supported]: /doc/supported-versions/
[Update the TemplateVM]: #updating
[switch]: #switching
[uninstall the old TemplateVM]: #uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[no-match]: /faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found

15
user/managing-os/xfce-templates.md
View file

@ -14,7 +14,7 @@ title: Xfce TemplateVMs
# Xfce TemplateVMs
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
you can install one of the available Xfce templates for [Fedora], [CentOS] or [Gentoo].
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
## Installation
@ -24,7 +24,7 @@ The Fedora Xfce TemplateVMs can be installed with the following command (where `
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -37,7 +37,7 @@ If you would like to install a community distribution, like CentOS or Gentoo, tr
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -46,12 +46,5 @@ You may wish to try again with the testing repository enabled:
The download may take a while depending on your connection speed.
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[Gentoo]: /doc/templates/gentoo/
[testing]: /doc/testing/

7
user/reference/glossary.md
View file

@ -107,7 +107,7 @@ NetVM
-----
*This is an old definition from before Qubes 4.0.
NetVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
NetVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Network Virtual Machine.
A type of [VM](#vm) that connects directly to a network.
@ -121,7 +121,7 @@ ProxyVM
-------
*This is an old definition from before Qubes 4.0.
ProxyVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
ProxyVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Proxy Virtual Machine.
A type of [VM](#vm) that proxies network access for other VMs.
@ -131,7 +131,7 @@ FirewallVM
----------
*This is an old definition from before Qubes 4.0.
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Firewall Virtual Machine.
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
@ -228,4 +228,3 @@ QWT
An abbreviation of Qubes [Windows Tools](#windows-tools).
[pr-748]: https://github.com/QubesOS/qubes-doc/pull/748

27
user/security-in-qubes/device-handling-security.md
View file

@ -11,7 +11,7 @@ title: Device Handling Security
Any additional ability a VM gains is additional attack surface.
It's a good idea to always attach the minimum entity required in a VM.
For example, attaching a full USB-device offers [more attack surface than attaching a single block device][USB security], while
For example, attaching a full USB-device offers [more attack surface than attaching a single block device](https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"), while
attaching a full block device (e.g. `sda`) again offers more attack surface than attaching a single partition (e.g. `sda1`), since the targetVM doesn't have to parse the partition-table.
(Attaching a full block device offers the advantage that most file-managers will mount and display them correctly, whereas they don't expect single partitions to be added and therefore don't handle them correctly.)
@ -41,25 +41,25 @@ Only whitelisted registers are accessible.
However, some devices or applications require full PCI access.
In these cases, the whole config-space may be allowed.
You're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit.
This increases the VM's ability to run a [side channel attack] and vulnerability to the same.
See [Xen PCI Passthrough: PV guests and PCI quirks] and [Software Attacks on Intel VT-d] \(page 7) for more details.
This increases the VM's ability to run a [side channel attack](https://en.wikipedia.org/wiki/Side-channel_attack) and vulnerability to the same.
See [Xen PCI Passthrough: PV guests and PCI quirks](https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks) and [Software Attacks on Intel VT-d](https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) \(page 7) for more details.
## USB Security
The connection of an untrusted USB device to dom0 is a security risk since the device can attack an arbitrary USB driver (which are included in the linux kernel), exploit bugs during partition-table-parsing or simply pretend to be a keyboard.
There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky][rubber duck].
There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky](https://shop.hak5.org/products/usb-rubber-ducky-deluxe).
The whole USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, use a [USB qube].
To avoid this risk, use a [USB qube](/doc/usb-qubes/).
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues][USB security] associated with the USB-stack.
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues](https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security") associated with the USB-stack.
If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
## Security Warning On USB Input Devices
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a [USB qube] entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
Because of this, the benefits of using a [USB qube](/doc/usb-qubes/) entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
@ -71,16 +71,7 @@ This is because you are guarding the system not only against anyone with local a
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
One way to achieve this is to use a [YubiKey](/doc/YubiKey/), or some other hardware token, or even to manually enter a one-time password.
Support for [two factor authentication][qubes u2f proxy] was recently added, though there are [issues][4661].
Support for [two factor authentication](/news/2018/09/11/qubes-u2f-proxy/) was recently added, though there are [issues](https://github.com/QubesOS/qubes-issues/issues/4661).
[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"
[rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe
[USB qube]: /doc/usb-qubes/
[YubiKey]: /doc/YubiKey/
[qubes u2f proxy]: /news/2018/09/11/qubes-u2f-proxy/
[4661]: https://github.com/QubesOS/qubes-issues/issues/4661
[side channel attack]: https://en.wikipedia.org/wiki/Side-channel_attack
[Xen PCI Passthrough: PV guests and PCI quirks]: https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks
[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf

51
user/security-in-qubes/split-gpg.md
View file

@ -97,7 +97,7 @@ Please note that previously, this parameter was set in ~/.bash_profile.
This will no longer work.
If you have the parameter set in ~/.bash_profile you *must* update your configuration.
Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations][current-limitations] section.
Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
### Configuring the client apps to use Split GPG backend
@ -199,7 +199,7 @@ Once this is done, you should be able to send an encrypted and signed email by s
[![tb78-10.png](/attachment/wiki/SplitGpg/tb78-10.png)](/attachment/wiki/SplitGpg/tb78-10.png)
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards] from which the above documentation is inspired.
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards) from which the above documentation is inspired.
### Older Thunderbird versions
@ -284,11 +284,11 @@ A safe, unspoofable user consent dialog box is displayed.
[![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)
Selecting "Yes to All" will add a line in the corresponding [RPC Policy] file.
Selecting "Yes to All" will add a line in the corresponding [RPC Policy](/doc/rpc-policy/) file.
## Advanced: Using Split GPG with Subkeys
Users with particularly high security requirements may wish to use Split GPG with [​subkeys].
Users with particularly high security requirements may wish to use Split GPG with [subkeys](https://wiki.debian.org/Subkeys).
However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model.
Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
@ -343,14 +343,14 @@ In this example, the following keys are stored in the following locations (see b
This is a network-isolated VM.
The initial master keypair and subkeys are generated in this VM.
The master secret key *never* leaves this VM under *any* circumstances.
No files or text is *ever* [copied] or [pasted] into this VM under *any* circumstances.
No files or text is *ever* [copied](/doc/copying-files#security) or [pasted](/doc/copy-paste#security) into this VM under *any* circumstances.
* `work-gpg`
This is a network-isolated VM.
This VM is used *only* as the GPG backend for `work-email`.
The secret subkeys (but *not* the master secret key) are [copied] from the `vault` VM to this VM.
Files from less trusted VMs are *never* [copied] into this VM under *any* circumstances.
The secret subkeys (but *not* the master secret key) are [copied](/doc/copying-files#security) from the `vault` VM to this VM.
Files from less trusted VMs are *never* [copied](/doc/copying-files#security) into this VM under *any* circumstances.
* `work-email`
@ -361,9 +361,9 @@ In this example, the following keys are stored in the following locations (see b
### Security Benefits
In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised.
First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [​MUA] could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM.
In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels].
In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/data-leaks).
Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there.
@ -371,23 +371,23 @@ Rather, the master secret key remains in the `vault` VM, which is extremely unli
<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
(This is significantly less devastating than having to create a new *master* keypair.)
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM][trusting-templates] upon which the `vault` VM is based.
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/doc/templates/#trusting-your-templatevms) upon which the `vault` VM is based.
### Subkey Tutorials and Discussions
(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments.
As always, exercise caution and use your good judgment.)
* [​"OpenPGP in Qubes OS" on the qubes-users mailing list][openpgp-in-qubes-os]
* [​"Creating the Perfect GPG Keypair" by Alex Cabal][cabal]
* [​"GPG Offline Master Key w/ smartcard" maintained by Abel Luck][luck]
* [​"Using GnuPG with QubesOS" by Alex][apapadop]
* ["OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
* ["Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
* ["GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
* ["Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)
## Current limitations
* Current implementation requires importing of public keys to the vault domain.
This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
See ticket [#474] for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys].
See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
Perhaps the GPG backend domain could start a DisposableVM and have the to-be-signed document displayed there? To Be Determined.
@ -395,26 +395,9 @@ As always, exercise caution and use your good judgment.)
* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
It will give an `Inappropriate ioctl for device` error.
Do not set passphrases for the private keys in the GPG backend domain.
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys].
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
(See [this StackExchange answer][se-pinentry] for more information.)
(See [this StackExchange answer](https://unix.stackexchange.com/a/379373) for more information.)
Note: The error shows only if you **do not** have graphical pinentry installed.
[#474]: https://github.com/QubesOS/qubes-issues/issues/474
[using Split GPG with subkeys]: #advanced-using-split-gpg-with-subkeys
[intro]: #what-is-split-gpg-and-why-should-i-use-it-instead-of-the-standard-gpg
[se-pinentry]: https://unix.stackexchange.com/a/379373
[​subkeys]: https://wiki.debian.org/Subkeys
[copied]: /doc/copying-files#security
[pasted]: /doc/copy-paste#security
[​MUA]: https://en.wikipedia.org/wiki/Mail_user_agent
[covert channels]: /doc/data-leaks
[trusting-templates]: /doc/templates/#trusting-your-templatevms
[openpgp-in-qubes-os]: https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion
[cabal]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[luck]: https://gist.github.com/abeluck/3383449
[apapadop]: https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/
[current-limitations]: #current-limitations
[RPC Policy]: /doc/rpc-policy/
[Thunderbird:OpenPGP:Smartcards]: https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards

41
user/security-in-qubes/u2f-proxy.md
View file

@ -8,12 +8,12 @@ title: The Qubes U2F Proxy
# The Qubes U2F Proxy
The [Qubes U2F Proxy] is a secure proxy intended to make use of U2F two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies][USB] implemented in Qubes.
The [Qubes U2F Proxy](https://github.com/QubesOS/qubes-app-u2f) is a secure proxy intended to make use of U2F two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies](/doc/usb/) implemented in Qubes.
## What is U2F?
[U2F], which stands for "Universal 2nd Factor", is a framework for authentication using hardware devices (U2F tokens) as "second factors", i.e. *what you have* as opposed to *what you know*, like a passphrase.
This additional control provides [good protection][krebs] in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
[U2F](https://en.wikipedia.org/wiki/U2F), which stands for "Universal 2nd Factor", is a framework for authentication using hardware devices (U2F tokens) as "second factors", i.e. *what you have* as opposed to *what you know*, like a passphrase.
This additional control provides [good protection](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/) in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
While passphrase compromise may not be obvious to the user, a physical device that cannot be duplicated must be stolen to be used outside of the owner's control.
Nonetheless, it is important to note at the outset that U2F cannot guarantee security when the host system is compromised (e.g. a malware-infected operating system under an adversary's control).
@ -25,8 +25,8 @@ The user interface is usually limited to a single LED and a button that is press
Currently, the most common form of two-step authentication consists of a numeric code that the user manually types into a web application.
These codes are typically generated by an app on the user's smartphone or sent via SMS.
By now, it is well-known that this form of two-step authentication is vulnerable to phishing and man-in-the-middle attacks due to the fact that the application requesting the two-step authentication code is typically not itself authenticated by the user.
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the U2F model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here][u2f-details]).
Nonetheless, [some attacks are still possible][wired] even with U2F (more on this below).
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the U2F model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here](https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs)).
Nonetheless, [some attacks are still possible](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) even with U2F (more on this below).
## The Qubes approach to U2F
@ -34,7 +34,7 @@ In a conventional setup, web browsers and the USB stack (to which the U2F token
Since the U2F model assumes that the browser is trustworthy, any browser in the OS is able to access any key stored on the U2F token.
The user has no way to know which keys have been accessed by which browsers for which services.
If any of the browsers are compromised, it should be assumed that all of the token's keys have been compromised.
(This problem can be mitigated, however, if the U2F device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB].
(This problem can be mitigated, however, if the U2F device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil).
In Qubes OS, by contrast, it is possible to securely compartmentalise the browser in one qube and the USB stack in another so that they are always kept separate from each other.
The Qubes U2F Proxy then allows the token connected to the USB stack in one qube to communicate with the browser in a separate qube.
@ -50,21 +50,21 @@ The frontend runs in the same qube as the browser and presents a fake USB-like H
The backend runs in `sys-usb` and behaves like a browser.
This is done using the `u2flib_host` reference library.
All of our code was written in Python.
The standard [qrexec] policy is responsible for directing calls to the appropriate domains.
The standard [qrexec](/doc/qrexec3/) policy is responsible for directing calls to the appropriate domains.
The `vault` qube with a dashed line in the bottom portion of the diagram depicts future work in which we plan to implement the Qubes U2F Proxy with a software token in an isolated qube rather than a physical hardware token.
This is similar to the manner in which [Split GPG] allows us to emulate the smart card model without physical smart cards.
This is similar to the manner in which [Split GPG](/doc/split-gpg/) allows us to emulate the smart card model without physical smart cards.
One very important assumption of U2F is that the browser verifies every request sent to the U2F token --- in particular, that the web application sending an authentication request matches the application that would be authenticated by answering that request (in order to prevent, e.g., a phishing site from sending an authentication request for your bank's site).
With the WebUSB feature in Chrome, however, a malicious website can [bypass][wired] this safeguard by connecting directly to the token instead of using the browser's U2F API.
With the WebUSB feature in Chrome, however, a malicious website can [bypass](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) this safeguard by connecting directly to the token instead of using the browser's U2F API.
The Qubes U2F Proxy also prevents this class of attacks by implementing an additional verification layer.
This verification layer allows you to enforce, for example, that the web browser in your `twitter` qube can only access the U2F key associated with `https://twitter.com`.
This means that if anything in your `twitter` qube were compromised --- the browser or even the OS itself --- it would still not be able to access the U2F keys on your token for any other websites or services, like your email and bank accounts.
This is another significant security advantage over monolithic systems.
(For details and instructions, see the [Advanced usage] section below.)
(For details and instructions, see the [Advanced usage](#advanced-usage-per-qube-key-access) section below.)
For even more protection, you can combine this with the [Qubes firewall] to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
For even more protection, you can combine this with the [Qubes firewall](/doc/firewall/) to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
By configuring the Qubes firewall to prevent your `banking` qube from accessing any other websites, you reduce the risk of another website compromising the browser in an attempt to bypass U2F authentication.
## Installation
@ -93,7 +93,7 @@ $ sudo apt install qubes-u2f
```
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your U2F token (but see [Browser support] below).
After that, you may use your U2F token (but see [Browser support](#templatevm-and-browser-support) below).
## Advanced usage: per-qube key access
@ -132,20 +132,5 @@ The large number of possible combinations of TemplateVM (Fedora 27, 28; Debian 8
In some cases, you may be the first person to try a particular combination.
Consequently (and as with any new feature), users will inevitably encounter bugs.
We ask for your patience and understanding in this regard.
As always, please [report any bugs you encounter].
As always, please [report any bugs you encounter](/doc/reporting-bugs/).
[Qubes U2F Proxy]: https://github.com/QubesOS/qubes-app-u2f
[USB]: /doc/usb/
[U2F]: https://en.wikipedia.org/wiki/U2F
[krebs]: https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/
[u2f-details]: https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs
[wired]: https://www.wired.com/story/chrome-yubikey-phishing-webusb/
[BadUSB]: https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil
[qrexec]: /doc/qrexec3/
[Split GPG]: /doc/split-gpg/
[Qubes firewall]: /doc/firewall/
[Advanced usage]: #advanced-usage-per-qube-key-access
[Browser support]: #templatevm-and-browser-support
[report any bugs you encounter]: /doc/reporting-bugs/
[ff-u2f-addon]: https://addons.mozilla.org/en-US/firefox/addon/u2f-support-add-on/?src=api
[qubes-devel]: /support/#qubes-devel

9
user/troubleshooting/hardware-troubleshooting.md
View file

@ -16,7 +16,7 @@ By default, the kernel that is installed in dom0 comes from the `kernel` package
For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues.
For example, the audio might not work if the sound card is too new for the LTS kernel.
To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested!
(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0).
(See [here](/doc/software-update-dom0/#kernel-upgrade) for more information about upgrading kernels in dom0).
In dom0:
~~~
@ -51,10 +51,5 @@ Do not edit it by hand, unless you know what you are doing.
Restarting `xorg` is required.
The most straightforward way is to reboot the system.
More information in [this discussion][layout_discussion] and [this GitHub issue][layout_issue].
More information in [this discussion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion) and [this GitHub issue](https://github.com/QubesOS/qubes-issues/issues/1396).
[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade
[hardware-reqs]: /doc/installation-guide/#hardware-requirements
[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion
[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396

3
user/troubleshooting/installation-troubleshooting.md
View file

@ -91,11 +91,10 @@ During Qubes installation, you may come across the error message which reads "Un
Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally".
This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS.
Return to the [hardware requirements][hardware-reqs] section to learn how to activate it.
Return to the [hardware requirements](/doc/installation-guide/#hardware-requirements) section to learn how to activate it.
If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
In Qubes 4.0, the default installation won't function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to "PV".
In Qubes 4.1, IOMMU is strictly required, even when the virtualization mode of a VM is changed to "PV"; it is not possible to use Qubes on a system without IOMMU.
[hardware-reqs]: /doc/installation-guide/#hardware-requirements

10
user/troubleshooting/update-troubleshooting.md
View file

@ -15,11 +15,11 @@ Usually, this is due to network problems (especially if downloading updates over
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- <https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/>
- <https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update>
- <https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/>
- <https://bugzilla.redhat.com/show_bug.cgi?id=1494178>
- <https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates>
- [https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/](https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/)
- [https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update](https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update)
- [https://www.reddit.com/r/Fedora/comments/74nldq/fedora\_26\_dnf\_error\_failed\_to\_synchronize\_cache/](https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/)
- [https://bugzilla.redhat.com/show\_bug.cgi?id=1494178](https://bugzilla.redhat.com/show_bug.cgi?id=1494178)
- [https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates](https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates)
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.

4
user/troubleshooting/usb-troubleshooting.md
View file

@ -62,9 +62,9 @@ Errors suggesting this issue:
- during `qvm-start sys-usb`:
`
```
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
`
```
Another solution would be to set the pci_strictreset option in dom0: