Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-01 19:16:27 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'QubesOS:main' into patch-7

Browse source
This commit is contained in:
Dr. Gerhard Weck 2023-12-20 10:15:39 +01:00 • committed by GitHub
commit d0aef81db6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
96 changed files with 3702 additions and 2749 deletions
Download patch file Download diff file Expand all files Collapse all files

153
user/advanced-topics/awesomewm.md
View file

@ -36,156 +36,3 @@ $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
For build instructions please check the repository _README_.
The repository attempts to follow the upstream Fedora repository.
## Common customizations
This section focuses on Qubes-specific customizations. For generic AwesomeWM customizations you might want to have a look at the [AwesomeWM website](https://awesomewm.org).
Customizations for AwesomeWM are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`.
### Application menu
Starting from Qubes 4.0 application menu entries specific to AwesomeWM can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created.
### Focus steal hardening
The default Qubes OS AwesomeWM installation comes with the defaults set by the AwesomeWM developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube.
#### Definition
For the below example we'll define _wanted focus changes_ as one of the below:
* mouse move & click afterwards
* workspace/tag change
* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k)
* tag assignments and unassignments
Everything else is considered an unwanted _focus steal_.
In particular the following events are not meant to cause a focus change:
* new window created
* a window was closed
* application request
* mouse move without click (sloppy focus)
For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
* windows shouldn't be able to change their size themselves
* windows shouldn't be able to modify their borders in any way
Users may want to adjust their definitions and respective implementations according to their needs.
#### Implementation
The implementation may be specific to the AwesomeWM version you're running. This guide refers to AwesomeWM version 3.5.9 which is available to Qubes 4.0 users.
Please keep in mind that this guide may not be conclusive. Your mileage may vary.
##### Change the autofocus implementation
The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your AwesomeWM instance.
In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`.
Then you can customise the focus behavior. According to our above definitions it would look as follows:
```lua
---autofocus_custom.lua
local client = client
local screen = screen
local aclient = require("awful.client")
local atag = require("awful.tag")
--- When loaded, this module makes sure that there's always a client that will have focus
-- on events such as tag switching, client unmanaging, etc.
-- awful.autofocus
-- Give focus when clients appear/disappear and no one else has focus.
-- @param obj An object that should have a .screen property.
function check_focus(obj)
-- When no visible client has the focus...
if not client.focus or not client.focus:isvisible() then
local c = aclient.focus.history.get(obj.screen, 0)
if c then client.focus = c end
end
end
-- Give focus on tag selection change.
-- @param tag A tag object
function check_focus_tag(t)
local s = atag.getscreen(t)
if not s then return end
check_focus({ screen = s })
if client.focus and client.focus.screen ~= s then
local c = aclient.focus.history.get(s, 0)
if c then client.focus = c end
end
end
--made above functions global & removed some focus switches below (user interaction required instead)
--clear any focus
function clear_focus()
--unfortunately this doesn't work at the moment
--cf. https://github.com/awesomeWM/awesome/issues/164
--(Qubes uses an older AwesomeWM version that doesn't have the fix yet)
--client.focus = nil
end
atag.attached_connect_signal(nil, "property::selected", check_focus_tag)
client.connect_signal("unmanage", clear_focus)
client.connect_signal("tagged", check_focus)
client.connect_signal("untagged", check_focus)
client.connect_signal("property::hidden", clear_focus)
client.connect_signal("property::minimized", clear_focus)
```
##### Remove unwanted focus changing key bindings
The mouse bindings
```lua
awful.button({ }, 4, awful.tag.viewnext),
awful.button({ }, 5, awful.tag.viewprev)
```
in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out.
##### Adjust client rules
The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`.
Alternatively users may provide their own focus filter functions.
##### Disable sloppy focus
In your _rc.lua_ you'll find a section such as
```lua
-- Enable sloppy focus
c:connect_signal("mouse::enter", function(c)
if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier
and awful.client.focus.filter(c) then
client.focus = c
end
end)
```
These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour.
##### Ignore requests from applications to the window manager
Handling of such requests is currently mostly implemented by AwesomeWM in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each AwesomeWM update though) or disconnect the signals in your _rc.lua_.
As of AwesomeWM 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_:
```lua
local ewmh = require("awful.ewmh")
client.disconnect_signal("request::activate", ewmh.activate)
client.disconnect_signal("request::tag", ewmh.tag)
```
The signal names may change across AwesomeWM versions.

32
user/advanced-topics/bind-dirs.md
View file

@ -24,19 +24,21 @@ In this way sys-whonix can benefit from the Tor anonymity feature 'persistent To
## How to use bind-dirs.sh? ##
In this example, we want to make `/var/lib/tor` persistent.
In this example, we want to make `/var/lib/tor` persistent. Enter all of the following commands in your app qube.
Inside the app qube.
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
1. Make sure the directory `/rw/config/qubes-bind-dirs.d` exists.
```
sudo mkdir -p /rw/config/qubes-bind-dirs.d
```
2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights.
2. Create the file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root permissions, if it doesn't already exist.
3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable.
```
sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf
```
3. Add a line to `/rw/config/qubes-bind-dirs.d/50_user.conf` that appends a folder or file to the `binds` variable.
```
binds+=( '/var/lib/tor' )
@ -44,14 +46,22 @@ Inside the app qube.
4. Save.
5. Reboot the app qube.
5. If the directory you wish to make persistent doesn't exist in the template on which the app qube is based, you'll need to create the directory (with its full path) under `/rw/bind-dirs` in the app qube. For example, if `/var/lib/tor` didn't exist in the template, then you would execute the following command in your app qube:
6. Done.
```
sudo mkdir -p /rw/bind-dirs/var/lib/tor
```
From now on any files within the `/var/lib/tor` folder will persist across reboots.
6. (optional) If the directory you want to persist across reboots (`/var/lib/tor` in this case) needs special ownership and permissions, make sure the directory you created just under `/rw/bind-dirs/` has the same ones (using the commands `chown` and `chmod`, respectively).
You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots.
7. Reboot the app qube.
8. Done.
From now on, all files in the `/var/lib/tor` directory will persist across reboots.
You can make make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file would also persist across reboots.
```
binds+=( '/var/lib/tor' )

329
user/advanced-topics/disposable-customization.md
View file

@ -15,62 +15,54 @@ title: Disposable customization
## Introduction
A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube).
You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables.
To prepare an app qube to be a disposable template, you need to set `template_for_dispvms` property, for example:
A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube). You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables. To prepare an app qube to be a disposable template, you need to set the `template_for_dispvms` property:
```shell_session
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
```
Additionally, if you want to have menu entries for starting applications in disposable based on this app qube (instead of in the app qube itself), you can achieve it with `appmenus-dispvm` feature:
Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the `appmenus-dispvm` feature:
```shell_session
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
```
Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
## Security
If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates.
In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it.
If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised. Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates. In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it.
## Creating a new disposable template
In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like.
To create new disposable template, lets say `custom-disposable-template`, based on `debian-9` template, use following commands:
In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template:
```shell_session
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposable-template
[user@dom0 ~]$ qvm-prefs custom-disposable-template template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-disposable-template appmenus-dispvm 1
[user@dom0 ~]$ qvm-create --template <TEMPLATE> --label red <DISPOSABLE_TEMPLATE>
[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
```
Additionally you may want to set it as default disposable template:
Optionally, set it as the default disposable template:
```shell_session
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposable-template
[user@dom0 ~]$ qubes-prefs default_dispvm <DISPOSABLE_TEMPLATE>
```
The above default is used whenever a qube request starting a new disposable and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details.
If you wish to use a [Minimal Template](/doc/templates/minimal/) as a disposable template, please see the [Minimal Template](/doc/templates/minimal/) page.
If you wish to use a [minimal template](/doc/templates/minimal/) as a disposable template, please see the [minimal template](/doc/templates/minimal/) page.
## Customization of disposable
_**Note:** If you are trying to customize Tor Browser in a Whonix disposable, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#disposable_Template_Customization)._
It is possible to change the settings for each new disposable.
This can be done by customizing the disposable template on which it is based:
It is possible to change the settings for each new disposable. This can be done by customizing the disposable template on which it is based:
1. Start a terminal in the `fedora-26-dvm` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new disposable based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
1. Start a terminal in the `<DISPOSABLE_TEMPLATE>` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`<DISPOSABLE_TEMPLATE>`) will be "Disposable: <DISPOSABLE_TEMPLATE>" (instead of "Domain: <DISPOSABLE_TEMPLATE>") and entries there will start new disposable based on that VM (`<DISPOSABLE_TEMPLATE>`). Not in that VM (`<DISPOSABLE_TEMPLATE>`) itself).
```shell_session
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
[user@dom0 ~]$ qvm-run -a <DISPOSABLE_TEMPLATE> gnome-terminal
```
2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
@ -78,50 +70,53 @@ This can be done by customizing the disposable template on which it is based:
- Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
- Changing the disposable's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new disposable, you can choose your desired ProxyVM manually (by changing the newly-started disposables settings). This is useful if you sometimes wish to use a disposable with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected disposable.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
3. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
## Using named disposables for sys-*
## Using named disposables for service qubes
You can use a [named disposable](/doc/glossary/#named-disposable) for `sys-*` as long as it is stateless.
For example, a `sys-net` using DHCP or `sys-usb` will work.
In most cases `sys-firewall` will also work, even if you have configured app qube firewall rules.
The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall app qube.
You can use a [named disposable](/doc/glossary/#named-disposable) for service qubes (such as those with the `sys-*` naming scheme) as long as they are stateless. For example, a `sys-net` using DHCP or `sys-usb` will work. In most cases `sys-firewall` will also work, even if you have configured app qube firewall rules. The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall app qube.
To create one that has no PCI devices attached, such as for `sys-firewall`:
~~~
qvm-create -C DispVM -l green <sys-VMName>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm <sys-net>
qvm-prefs <sys-VMName> provides_network true
qvm-features <sys-VMName> appmenus-dispvm ''
qvm-create -C DispVM -l green <SERVICE_QUBE>
qvm-prefs <SERVICE_QUBE> autostart true
qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
qvm-prefs <SERVICE_QUBE> provides_network true
qvm-features <SERVICE_QUBE> appmenus-dispvm ''
~~~
Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new.
For example, with `qvm-prefs work netvm sys-firewall2`.
Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new, for example, with `qvm-prefs work netvm sys-firewall2`.
To create one with a PCI device attached such as for `sys-net` or `sys-usb`, use the additional commands as follows.
**Note** You can use `qvm-pci` to [determine](/doc/how-to-use-pci-devices/#qvm-pci-usage) the `<BDF>`.
Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/how-to-use-pci-devices/#no-strict-reset) with USB controllers.
**Note:** You can use `qvm-pci` to [determine](/doc/how-to-use-pci-devices/#qvm-pci-usage) the `<BDF>`. Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/how-to-use-pci-devices/#no-strict-reset) with USB controllers.
~~~
qvm-create -C DispVM -l red <sys-VMName>
qvm-prefs <sys-VMName> virt_mode hvm
qvm-service <sys-VMName> meminfo-writer off
qvm-pci attach --persistent <sys-VMName> dom0:<BDF>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm ''
qvm-features <sys-VMName> appmenus-dispvm ''
# optional, if this disposable will be providing networking
qvm-prefs <sys-VMName> provides_network true
qvm-create -C DispVM -l red <SERVICE_QUBE>
qvm-prefs <SERVICE_QUBE> virt_mode hvm
qvm-service <SERVICE_QUBE> meminfo-writer off
qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
qvm-prefs <SERVICE_QUBE> autostart true
qvm-prefs <SERVICE_QUBE> netvm ''
qvm-features <SERVICE_QUBE> appmenus-dispvm ''
~~~
Next, set the old `sys-` VM's autostart to false, and update any references to the old one.
In particular, make sure to update `/etc/qubes-rpc/policy/qubes.UpdatesProxy` in dom0.
Optionally, if this disposable will also provide network access to other qubes:
For example, `qvm-prefs sys-firewall netvm <sys-VMName>`.
See below for a complete example of a `sys-net` replacement:
~~~
qvm-prefs <SERVICE_QUBE> provides_network true
~~~
Next, set the old service qube's autostart to false, and update any references to the old one, e.g.:
~~~
qvm-prefs sys-firewall netvm <SERVICE_QUBE>
~~~
Also make sure to update any [RPC policies](/doc/rpc-policy/), if needed.
Here is an example of a complete `sys-net` replacement:
~~~
qvm-create -C DispVM -l red sys-net2
@ -137,248 +132,38 @@ qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
~~~
## Adding programs to disposable Application Menu
## Adding programs to the app menu
For added convenience, arbitrary programs can be added to the Application Menu of the disposable.
For added convenience, arbitrary programs can be added to the app menu of the disposable.
In order to do that, select "Qube settings" entry in selected base app qube, go to "Applications" tab and select desired applications as for any other qube.
Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
## Create Custom sys-net sys-firewall and sys-usb disposables
Users have the option of creating customized disposables for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a disposable is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
Functionality is not limited, users can:
- Set custom firewall rule sets and run Qubes VPN scripts.
- Set disposables to autostart at system boot.
- Attach PCI devices with the `--persistent` option.
Using disposables in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate disposable template for use by each disposable. If disposable template customization is not needed, then a single disposable template is used as a template for all disposables.
### Create and configure the disposable template on which the disposable will be based
1. Create the disposable template:
```shell_session
[user@dom0 ~]$ qvm-create --class AppVM --label gray <disposable-Template-Name>
```
2. _(optional)_ In the disposable template, add custom firewall rule sets, Qubes VPN scripts, etc.
Firewall rules sets and Qubes VPN scripts can be added just like any other VM.
3. Set the disposable template as template for disposables:
```shell_session
[user@dom0 ~]$ qvm-prefs <disposable-Template-Name> template_for_dispvms true
```
### Create the sys-net disposable
1. Create `sys-net` disposable based on the disposable template:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label red disp-sys-net
```
2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
```
3. Set `disp-sys-net` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
```
4. Set `disp-sys-net` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
```
5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
```shell_session
[user@dom0 ~]$ qvm-pci
```
6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/how-to-use-pci-devices/):
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
```
7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
```
8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
```
9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
```shell_session
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
```
10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
### Create the sys-firewall disposable
1. Create `sys-firewall` disposable:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label green disp-sys-firewall
```
2. Set `disp-sys-firewall` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
```
3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```
4. Set `disp-sys-firewall` as NetVM for other app qubes:
```shell_session
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
```
5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
```
6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
```
7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
```shell_session
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```
### Create the sys-usb disposable
1. Create the `disp-sys-usb`:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposable-template-name> --class DispVM --label red disp-sys-usb
```
2. Set the `disp-sys-usb` virtualization mode to hvm:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
```
3. Set `disp-sys-usb` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
```
4. List all available PCI devices:
```shell_session
[user@dom0 ~]$ qvm-pci
```
5. Attach the USB controller to the `disp-sys-usb`:
>_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/how-to-use-pci-devices/#no-strict-reset).
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
```
6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
```
7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
```
8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-usb-controllers-from-dom0).
9. At this point, your mouse may not work.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
```
/etc/qubes-rpc/policy/qubes.InputMouse
```
Add a line like this to the top of the file:
```
disp-sys-usb dom0 allow,user=root
```
### Starting the disposables
Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created disposables fail to start.
Detach PCI device from VM:
```shell_session
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
```
### Troubleshooting
If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
## Deleting disposables
While working in a disposable, you may want to open a document in another disposable.
For this reason, the property `default_dispvm` may be set to the name of your disposable in a number of VMs:
While working in a disposable, you may want to open a document in another disposable. For this reason, the property `default_dispvm` may be set to the name of your disposable in a number of qubes:
```shell_session
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-disposable-template
[user@dom0 ~]$ qvm-prefs <QUBE> | grep default_dispvm
default_dispvm - <DISPOSABLE_TEMPLATE>
```
This will prevent the deletion of the disposable template. In order to fix this you need to unset the `default_dispvm` property:
This will prevent the deletion of the disposable template. In order to fix this, you need to unset the `default_dispvm` property:
```shell_session
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
[user@dom0 ~]$ qvm-prefs <QUBE> default_dispvm ""
```
You can then delete the disposable template:
```shell_session
[user@dom0 ~]$ qvm-remove custom-disposable-template
[user@dom0 ~]$ qvm-remove <DISPOSABLE_TEMPLATE>
This will completely remove the selected VM(s)
custom-disposable-template
<DISPOSABLE_TEMPLATE>
```
If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you:
If you still encounter a problem, you may have forgotten to clean an entry. Looking at the system logs will help you:
```shell_session
[user@dom0 ~]$ journalctl | tail

40
user/advanced-topics/guivm.md → user/advanced-topics/gui-domain.md
View file

@ -1,21 +1,21 @@
---
lang: en
layout: doc
permalink: /doc/guivm-configuration/
permalink: /doc/gui-domain/
redirect_from:
- /doc/guivm-configuration/
ref: 184
title: GuiVM Configuration
title: GUI domain
---
## Gui domain
In this section, we describe how to setup `GuiVM` in several case as described in [GUI Domain](/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured `GuiVM` is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding `GuiVM` to setup. For example, pillar data for `sys-gui` located at `/srv/pillar/base/qvm/sys-gui.sls`. Please note that each `GuiVM` has no `NetVM`.
On this page, we describe how to set up a [GUI domain](/news/2020/03/18/gui-domain/). In all the cases, the base underlying TemplateVM used is `Fedora` with `XFCE` flavor to match current desktop choice in `dom0`. That can be adapted very easily for other desktops and templates. By default, the configured GUI domain is a management qube with global admin permissions `rwx` but can be adjusted to `ro` (see [Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)) in pillar data of the corresponding GUI domain to setup. For example, pillar data for `sys-gui` located at `/srv/pillar/base/qvm/sys-gui.sls`. Please note that each GUI domain has no `NetVM`.
> Note: The setup is done using `SaltStack` formulas with the `qubesctl` tool. When executing it, apply step can take time because it needs to download latest Fedora XFCE TemplateVM and install desktop dependencies.
### Hybrid GuiVM `sys-gui`
### Hybrid GUI domain (`sys-gui`)
Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromise solution* in [GUI Domain](/news/2020/03/18/gui-domain/#the-compromise-solution).
Here, we describe how to setup `sys-gui` that we call *hybrid mode* or referenced as a *compromise solution* in [GUI domain](/news/2020/03/18/gui-domain/#the-compromise-solution).
[![sys-gui](/attachment/posts/guivm-hybrid.png)](/attachment/posts/guivm-hybrid.png)
@ -37,13 +37,13 @@ You can now disable the `sys-gui` formula:
sudo qubesctl top.disable qvm.sys-gui
```
At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui`. In order to use `sys-gui` as GuiVM, you need to logout and, in the top right corner, select `lightdm` session type to *Gui Domain (sys-gui)*. Once logged, you are running `sys-gui` as fullscreen window and you can perform any operation as if you would be in `dom0` desktop.
At this point, you need to shutdown all your running qubes as the `default_guivm` qubes global property has been set to `sys-gui`. In order to use `sys-gui` as GUI domain, you need to logout and, in the top right corner, select `lightdm` session type to **GUI domain (sys-gui)**. Once logged, you are running `sys-gui` as fullscreen window and you can perform any operation as if you would be in `dom0` desktop.
> Note: In order to go back to `dom0` desktop, you need to logout and then, select `lightdm` session to *Session Xfce*.
### GPU GuiVM `sys-gui-gpu`
### GPU GUI domain (`sys-gui-gpu`)
Here, we describe how to setup `sys-gui-gpu` which is a `GuiVM` with *GPU passthrough* in [GUI Domain](/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution).
Here, we describe how to setup `sys-gui-gpu` which is a GUI domain with *GPU passthrough* in [GUI domain](/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution).
[![sys-gui-gpu](/attachment/posts/guivm-gpu.png)](/attachment/posts/guivm-gpu.png)
@ -82,9 +82,9 @@ At this point, you need to reboot your Qubes OS machine in order to boot into `s
Once, `lightdm` is started, you can log as `user` where `user` refers to the first `dom0` user in `qubes` group and with corresponding `dom0` password. A better approach for handling password is currently discussed in [QubesOS/qubes-issues#6740](https://github.com/QubesOS/qubes-issues/issues/6740).
### VNC GuiVM `sys-gui-vnc`
### VNC GUI domain (`sys-gui-vnc`)
Here, we describe how to setup `sys-gui-vnc` that we call a *remote* `GuiVM` or referenced as *with a virtual server* in [GUI Domain](/news/2020/03/18/gui-domain/#virtual-server-the-perfect-remote-solution).
Here, we describe how to setup `sys-gui-vnc` that we call a *remote* GUI domain or referenced as *with a virtual server* in [GUI domain](/news/2020/03/18/gui-domain/#virtual-server-the-perfect-remote-solution).
[![sys-gui-vnc](/attachment/posts/guivm-vnc.png)](/attachment/posts/guivm-vnc.png)
@ -120,13 +120,13 @@ A VNC server session is running on `localhost:5900` in `sys-gui-vnc`. In order t
> **WARNING**: This setup raises multiple security issues: 1) Anyone who can reach the `VNC` server, can take over the control of the Qubes OS machine, 2) A second client can connect even if a connection is already active and potentially get disconnected, 3) You can get disconnected by some unrelated network issues. Generally, if this `VNC` server is exposed to open network, it must be protected with some other (cryptographic) layer like `VPN`. The setup as is, is useful only for purely testing machine.
### Troobleshooting
### Troubleshooting
#### Application menu lacks qubes entries in a fresh GuiVM
#### Application menu lacks qubes entries in a fresh GUI domain
See [QubesOS/qubes-issues#5804](https://github.com/QubesOS/qubes-issues/issues/5804)
#### Delete GuiVM
#### Delete GUI domain
The following commands have to be run in `dom0`.
@ -138,18 +138,18 @@ Set `default_guivm` as `dom0`:
qubes-prefs default_guivm dom0
```
and for every selected qubes not using default value for `guivm` property, for example with a qube `personal`:
and for every selected qubes not using default value for GUI domain property, for example with a qube `personal`:
```bash
qvm-prefs personal guivm dom0
```
You are now able to delete the GuiVM, for example `sys-gui-gpu`:
You are now able to delete the GUI domain, for example `sys-gui-gpu`:
```bash
qvm-remove -y sys-gui-gpu
qvm-remove -f sys-gui-gpu
```
#### General issue
#### General issues
For any general GuiVM issue, please take a loot at existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.
For any general GUI domain issues, please take a loot at existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.

2
user/advanced-topics/kde.md
View file

@ -16,7 +16,7 @@ R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/r
still possible to install KDE by issuing this command in dom0:
```shell_session
$ sudo qubes-dom0-update @kde-desktop-qubes
$ sudo qubes-dom0-update kde-settings-qubes
```
You can also change your default login manager (lightdm) to the new KDE default: sddm

6
user/advanced-topics/salt.md
View file

@ -193,12 +193,12 @@ $ 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](http://jinja.pocoo.org/).
This is most commonly done with [Jinja](https://palletsprojects.com/p/jinja/).
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](http://jinja.pocoo.org/docs/2.9/templates/).
So you should take a look at the [Jinja API documentation](https://jinja.palletsprojects.com/templates/).
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation](https://docs.saltproject.io/en/getstarted/config/jinja.html#get-data-using-salt).
@ -605,6 +605,6 @@ install template and shutdown updateVM:
- [Salt states](https://docs.saltproject.io/en/latest/ref/states/all/) ([files](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.cmd.html),
[packages](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltproject.io/en/latest/ref/states/ordering.html))
- [Top files](https://docs.saltproject.io/en/latest/ref/states/top.html)
- [Jinja templates](http://jinja.pocoo.org/)
- [Jinja templates](https://palletsprojects.com/p/jinja/)
- [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)

1
user/advanced-topics/secondary-storage.md
View file

@ -6,6 +6,7 @@ redirect_from:
- /en/doc/secondary-storage/
- /doc/SecondaryStorage/
- /wiki/SecondaryStorage/
- /doc/storage-pools/
ref: 187
title: Secondary storage
---

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

@ -1,162 +0,0 @@
---
advanced: true
lang: en
layout: doc
permalink: /doc/custom-install/
redirect_from:
- /doc/encryption-config/
ref: 152
title: Custom installation
---
In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
## Installer Defaults
For reference, these are the typical defaults for a single disk with legacy boot:
~~~
Mount Point: /boot
Desired Capacity: 1024 MiB
Device Type: Standard Partition
File System: ext4
Name: (none)
Mount Point: /
Desired Capacity: (your choice)
Device Type: LVM Thin Provisioning
Volume Group: qubes_dom0
File System: ext4
Name: root
Mount Point: (none)
Desired Capacity: 10 GiB
Device Type: LVM
Volume Group: qubes_dom0
File System: swap
Name: swap
~~~
~~~
SUMMARY OF CHANGES
Order Action Type Device Mount point
1 Destroy Format Unknown Disk (sda)
2 Create Format partition table (MSDOS) Disk (sda)
3 Create Device partition sda1 on Disk
4 Create Format ext4 sda1 on Disk /boot
5 Create Device partition sda2 on Disk
6 Create Format LUKS sda2 on Disk
7 Create Device luks/dm-crypt luks-sda2
8 Create Format physical volume (LVM) luks-sda2
9 Create Device lvmvg qubes_dom0
10 Create Device lvmthinpool qubes_dom0-pool00
11 Create Device lvmthinlv qubes_dom0-root
12 Create Device lvmlv qubes_dom0-swap
13 Create Format swap qubes_dom0-swap
14 Create Format ext4 qubes_dom0-root /
~~~
## Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
With a single disk, the result should look something like this:
~~~
NAME SIZE TYPE MOUNTPOINT
sda disk
├──sda1 1G part /boot
└──sda2 part
└──luks-<UUID> crypt
├──qubes_dom0-pool00_tmeta lvm
├──qubes_dom0-pool00_tdata lvm
└──qubes_dom0-swap lvm [SWAP]
~~~
## Encryption Defaults
By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
~~~
Version: 1
Cipher name: aes
Cipher mode: xts-plain64
Hash spec: sha256
~~~
~~~
$ cryptsetup --help
[...]
Default compiled-in device cipher parameters:
loop-AES: aes, Key 256 bits
plain: aes-cbc-essiv:sha256, Key: 256 bits, Password hashing: ripdemd160
LUKS1: aes-xts-plain64, Key: 256 bits, LUKS header hashing: sha256, RNG: /dev/urandom
~~~
This means that, by default, Qubes inherits these upstream defaults:
- 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
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
## Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
1. (Optional) Wipe the disk:
```
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
```
2. Create partitions:
```
# fdisk /dev/sda
```
Follow the steps to create two partitions:
- ~500MiB-1GiB for `/boot`
- The rest for `/` (might want to leave some for overprovisioning if it's an SSD)
4. Create LUKS encrypted volume:
```
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
```
5. Open encrypted volume:
```
# cryptsetup open /dev/sda2 luks
```
6. Create LVM volumes:
```
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root
```
8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation.
At the disk selection screen, select:
```
[x] I will configure partitioning.
[ ] Encrypt my data.
```
9. Decrypt your partition. After decrypting you may assign mount points:
Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top.
Repeat the process for `sda1` and `qubes_dom0-swap`. Those should be assigned to `/boot` and `swap` respectively.
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.

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

@ -24,4 +24,4 @@ helpful in streamlining the process.
* 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](/team/#wojtek-porczyk) or [Marek](/team/#marek-marczykowski-górecki).
* For website updates and fixes, please contact [Andrew](/team/#andrew-david-wong).
* For website updates and fixes, please contact [unman](/team/#unman).

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

@ -18,7 +18,7 @@ No operating system, not even Qubes, can help you if you're installing it on har
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)](/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).
Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](https://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
## Verifying the Qubes ISO

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

@ -15,14 +15,13 @@ redirect_from:
- /doc/InstallationGuideR3.0rc1/
- /doc/InstallationGuideR3.0rc2/
- /doc/live-usb/
- /doc/custom-install/
- /doc/encryption-config/
ref: 153
title: Installation guide
---
Welcome to the Qubes OS installation guide! This guide will walk you through
the process of installing Qubes. Please read it carefully and thoroughly, as it
contains important information for ensuring that your Qubes OS installation is
functional and secure.
Welcome to the Qubes OS installation guide! This guide will walk you through the process of installing Qubes. Please read it carefully and thoroughly, as it contains important information for ensuring that your Qubes OS installation is functional and secure.
## Pre-installation
@ -30,103 +29,56 @@ functional and secure.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Qubes has no control over what happens on your computer
before you install it. No software can provide security if it is installed on
compromised hardware. Do not install Qubes on a computer you don't trust.
See <a href="/doc/install-security/">installation security</a> for more
information.
<b>Warning:</b> Qubes has no control over what happens on your computer before you install it. No software can provide security if it is installed on compromised hardware. Do not install Qubes on a computer you don't trust. See <a href="/doc/install-security/">installation security</a> for more information.
</div>
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](/hcl/).
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](/hcl/).
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 or UEFI. 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 or UEFI, alongside the standard
Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions.
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 or
UEFI to locate and activate those settings. If those settings are not nested
under the Advanced tab, you might find them under the Security tab.
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 or UEFI. 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 or UEFI, alongside the standard Virtualization (**Intel VT-x**) and AMD Virtualization (**AMD-V**) extensions. 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 or UEFI 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">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
as a guest hypervisor. In other words, <b>nested virtualization</b> is not
supported. In order for a strict compartmentalization to be enforced, Qubes
OS needs to be able to manage the hardware directly.
<b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine as a guest hypervisor. In other words, <b>nested virtualization</b> is not supported. In order for a strict compartmentalization to be enforced, Qubes OS needs to be able to manage the hardware directly.
</div>
### Copying the ISO onto the installation medium
Pick the most secure existing computer and OS you have available for
downloading and copying the Qubes ISO onto the installation medium.
[Download](/downloads/) a Qubes ISO.
Pick the most secure existing computer and OS you have available for downloading and copying the Qubes ISO onto the installation medium. [Download](/downloads/) a Qubes ISO.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Any file you download from the internet could be malicious,
even if it appears to come from a trustworthy source. Our philosophy is to <a
href="/faq/#what-does-it-mean-to-distrust-the-infrastructure">distrust the
infrastructure</a>. Regardless of how you acquire your Qubes ISO, <a
href="/security/verifying-signatures/">verify its authenticity</a> before
continuing.
<b>Warning:</b> Any file you download from the internet could be malicious, even if it appears to come from a trustworthy source. Our philosophy is to <a href="/faq/#what-does-it-mean-to-distrust-the-infrastructure">distrust the infrastructure</a>. Regardless of how you acquire your Qubes ISO, <a href="/security/verifying-signatures/">verify its authenticity</a> before continuing.
</div>
Once the ISO has been verified as authentic, you should copy it onto the
installation medium of your choice, such as a USB drive, dual-layer DVD,
or Blu-ray disc. The size of each Qubes ISO is available on the
[downloads](/downloads/) page by hovering over the download button. The
instructions below assume you've chosen a USB drive as your medium. If you've
chosen a different medium, please adapt the instructions accordingly.
Once the ISO has been verified as authentic, you should copy it onto the installation medium of your choice, such as a USB drive, dual-layer DVD, or Blu-ray disc. The size of each Qubes ISO is available on the [downloads](/downloads/) page by hovering over the download button. The instructions below assume you've chosen a USB drive as your medium. If you've chosen a different medium, please adapt the instructions accordingly.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> There are important <a href="/doc/install-security/">security
considerations</a> to keep in mind when choosing an installation medium.
<b>Note:</b> There are important <a href="/doc/install-security/">security considerations</a> to keep in mind when choosing an installation medium. Advanced users may wish to <a href="/security/verifying-signatures/#how-to-re-verify-installation-media-after-writing">re-verify their installation media after writing</a>.
</div>
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Be careful to choose the correct device when copying the ISO,
or you may lose data. We strongly recommended making a full backup before
modifying any devices.
<b>Warning:</b> Be careful to choose the correct device when copying the ISO, or you may lose data. We strongly recommended making a full backup before modifying any devices.
</div>
#### Linux ISO to USB
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device,
e.g. using `dd`:
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
```
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync
```
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`).
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`).
#### Windows ISO to USB
On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the
ISO to a USB key. Be sure to select "Write in DD Image mode" *after* selecting
the Qubes ISO and pressing "START" on the Rufus main window.
On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the ISO to a USB key. Be sure to select "Write in DD Image mode" *after* selecting the Qubes ISO and pressing "START" on the Rufus main window.
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> Using Rufus to create the installation medium means that you
<a href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
to choose the "Test this media and install Qubes OS" option mentioned in the
example below. Instead, choose the "Install Qubes OS" option.
<b>Note:</b> Using Rufus to create the installation medium means that you <a href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a> to choose the "Test this media and install Qubes OS" option mentioned in the example below. Instead, choose the "Install Qubes OS" option.
</div>
[![Rufus menu](/attachment/doc/rufus-menu.png)](/attachment/doc/rufus-menu.png)
@ -135,37 +87,17 @@ the Qubes ISO and pressing "START" on the Rufus main window.
## Installation
This section will demonstrate a simple installation using mostly default
settings.
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.
This section will demonstrate a simple installation using mostly default settings.
### Getting to the boot screen
"Booting" is the process of starting your computer. When a computer boots up,
it first runs low-level software before the main operating system. Depending on
the computer, this low-level software is may be called the
["BIOS"](https://en.wikipedia.org/wiki/BIOS) or
["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
"Booting" is the process of starting your computer. When a computer boots up, it first runs low-level software before the main operating system. Depending on the computer, this low-level software is may be called the ["BIOS"](https://en.wikipedia.org/wiki/BIOS) or ["UEFI"](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface).
Since you're installing Qubes OS, you'll need to access your computer's BIOS or
UEFI menu so that you can tell it to boot from the USB drive to which you just
copied the Qubes installer ISO.
Since you're installing Qubes OS, you'll need to access your computer's BIOS or UEFI menu so that you can tell it to boot from the USB drive to which you just copied the Qubes installer ISO.
To begin, power off your computer and plug the USB drive into a USB port, but
don't press the power button yet. Right after you press the power button,
you'll have to immediately press a specific key to enter the BIOS or UEFI menu.
The key to press varies from brand to brand. `Esc`, `Del`, and `F10` are common
ones. If you're not sure, you can search the web for `<COMPUTER_MODEL> BIOS
key` or `<COMPUTER_MODEL> UEFI key` (replacing `<COMPUTER_MODEL>` with your
specific computer model) or look it up in your computer's manual.
To begin, power off your computer and plug the USB drive into a USB port, but don't press the power button yet. Right after you press the power button, you'll have to immediately press a specific key to enter the BIOS or UEFI menu. The key to press varies from brand to brand. `Esc`, `Del`, and `F10` are common ones. If you're not sure, you can search the web for `<COMPUTER_MODEL> BIOS key` or `<COMPUTER_MODEL> UEFI key` (replacing `<COMPUTER_MODEL>` with your specific computer model) or look it up in your computer's manual.
Once you know the key to press, press your computer's power button, then
repeatedly press that key until you've entered your computer's BIOS or UEFI
menu. To give you and idea of what you should be looking for, we've provided a
couple of example photos below.
Once you know the key to press, press your computer's power button, then repeatedly press that key until you've entered your computer's BIOS or UEFI menu. To give you and idea of what you should be looking for, we've provided a couple of example photos below.
Here's an example of what the BIOS menu looks like on a ThinkPad T430:
@ -175,39 +107,13 @@ And here's an example of what a UEFI menu looks like:
[![UEFI menu](/attachment/doc/uefi.jpeg)](/attachment/doc/uefi.jpeg)
Once you access your computer's BIOS or UEFI menu, you'll want to go to the
"boot menu," which is where you tell your computer which devices to boot from.
The goal is to tell the computer to boot from your USB drive so that you can
run the Qubes installer. If your boot menu lets you select which device to boot
from first, simply select your USB drive. (If you have multiple entries that
all look similar to your USB drive, and you're not sure which one is correct,
one option is just to try each one until it works.) If, on the other hand, your
boot menu presents you with a list of boot devices in order, then you'll want
to move your USB drive to the top so that the Qubes installer runs before
anything else.
Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boot menu," which is where you tell your computer which devices to boot from. The goal is to tell the computer to boot from your USB drive so that you can run the Qubes installer. If your boot menu lets you select which device to boot from first, simply select your USB drive. (If you have multiple entries that all look similar to your USB drive, and you're not sure which one is correct, one option is just to try each one until it works.) If, on the other hand, your boot menu presents you with a list of boot devices in order, then you'll want to move your USB drive to the top so that the Qubes installer runs before anything else.
Once you're done on the boot menu, save your changes. How you do this depends
on your BIOS or UEFI, but the instructions should be displayed right there on
the screen or in a nearby tab. (If you're not sure whether you've saved your
changes correctly, you can always reboot your computer and go back into the
boot menu to check whether it still reflects your changes.) Once your BIOS or
UEFI is configured the way you want it, reboot your computer. This time, don't
press any special keys. Instead, let the BIOS or UEFI load and let your
computer boot from your USB drive. If you're successful in this step, after a
few seconds you'll be presented with the Qubes installer screen:
Once you're done on the boot menu, save your changes. How you do this depends on your BIOS or UEFI, but the instructions should be displayed right there on the screen or in a nearby tab. (If you're not sure whether you've saved your changes correctly, you can always reboot your computer and go back into the boot menu to check whether it still reflects your changes.) Once your BIOS or UEFI is configured the way you want it, reboot your computer. This time, don't press any special keys. Instead, let the BIOS or UEFI load and let your computer boot from your USB drive. If you're successful in this step, after a few seconds you'll be presented with the Qubes installer screen:
[![Boot screen](/attachment/doc/boot-screen.png)](/attachment/doc/boot-screen.png)
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> When installing Qubes OS 4.0 on UEFI, there is intentionally no
boot menu. It goes straight to the installer. The boot menu will be back in
Qubes OS 4.1.
</div>
From here, you can navigate the boot screen using the arrow keys on your
keyboard. Pressing the "Tab" key will reveal options. You can choose one of
three options:
From here, you can navigate the boot screen using the arrow keys on your keyboard. Pressing the "Tab" key will reveal options. You can choose one of three options:
* Install Qubes OS
* Test this media and install Qubes OS
@ -215,74 +121,51 @@ three options:
Select the option to test this media and install Qubes OS.
If the boot screen does not appear, there are several options to troubleshoot.
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](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> If the latest stable release is not compatible with your hardware, you may wish to consider <a href="/doc/testing/">testing a newer release</a>.
</div>
If the boot screen does not appear, there are several options to troubleshoot. 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](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
### The installer home screen
On the first screen, you are asked to select the language that will be used
during the installation process. When you are done, select **Continue**.
On the first screen, you are asked to select the language that will be used during the installation process. When you are done, select **Continue**.
[![welcome](/attachment/doc/welcome-to-qubes-os-installation-screen.png)](/attachment/doc/welcome-to-qubes-os-installation-screen.png)
Prior to the next screen, a compatibility test runs to check whether
IOMMU-virtualization is active or not. If the test fails, a window will pop up.
Prior to the next screen, a compatibility test runs to check whether IOMMU-virtualization is active or not. If the test fails, a window will pop up.
[![Unsupported hardware detected](/attachment/doc/unsupported-hardware-detected.png)](/attachment/doc/unsupported-hardware-detected.png)
Do not panic. It may simply indicate that IOMMU-virtualization hasn't been
activated in the BIOS or UEFI. 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.
Do not panic. It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS or UEFI. 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. The
installer loads Xen right at the beginning. If you can see the installer's
graphical screen, and you pass the compatibility check that runs immediately
afterward, Qubes OS is likely to work on your system!
If the test passes, you will reach the installation summary screen. The installer loads Xen right at the beginning. If you can see the installer's graphical screen, and you pass the compatibility check that runs immediately afterward, Qubes OS is likely to work on your system!
Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with
RPM-based distributions should feel at home.
Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with RPM-based distributions should feel at home.
### Installation summary
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
even load any networking drivers, so there is no possibility of
internet-based data leaks or attacks during the installation process.
<b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't even load any networking drivers, so there is no possibility of internet-based data leaks or attacks during the installation process.
</div>
The Installation summary screen allows you to change how the system will be
installed and configured, including localization settings. At minimum, you are
required to select the storage device on which Qubes OS will be installed.
The Installation summary screen allows you to change how the system will be installed and configured, including localization settings. At minimum, you are required to select the storage device on which Qubes OS will be installed.
[![Installation summary not ready](/attachment/doc/installation-summary-not-ready.png)](/attachment/doc/installation-summary-not-ready.png)
### Localization
Let's assume you wish to add a German keyboard layout. Go to Keyboard Layout,
press the "Plus" symbol, search for "German" as indicated in the screenshot and
press "Add". If you want it be your default language, select the "German" entry
in the list and press the arrow button. Click on "Done" in the upper left
corner, and you're ready to go!
Let's assume you wish to add a German keyboard layout. Go to Keyboard Layout, press the "Plus" symbol, search for "German" as indicated in the screenshot and press "Add". If you want it be your default language, select the "German" entry in the list and press the arrow button. Click on "Done" in the upper left corner, and you're ready to go!
[![Keyboard layout selection](/attachment/doc/keyboard-layout-selection.png)](/attachment/doc/keyboard-layout-selection.png)
The process to select a new language is similar to the process to select a new
keyboard layout. Follow the same process in the "Language Support" entry.
The process to select a new language is similar to the process to select a new keyboard layout. Follow the same process in the "Language Support" entry.
[![Language support selection](/attachment/doc/language-support-selection.png)](/attachment/doc/language-support-selection.png)
You can have as many keyboard layout and languages as you want. Post-install,
you will be able to switch between them and install others.
You can have as many keyboard layout and languages as you want. Post-install, you will be able to switch between them and install others.
Don't forget to select your time and date by clicking on the Time & Date entry.
@ -292,82 +175,49 @@ Don't forget to select your time and date by clicking on the Time & Date entry.
[![Add-ons](/attachment/doc/add-ons.png)](/attachment/doc/add-ons.png)
On the software selection tab, you can choose which software to install in
Qubes OS. Two options are available:
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](/doc/templates/debian/) qubes in addition to the default Fedora
qubes.
* **Whonix:** Select this option if you would like to use
[Whonix](https://www.whonix.org/wiki/Qubes) qubes. Whonix allows you to use
[Tor](https://www.torproject.org/) 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](https://www.whonix.org/wiki/Qubes) 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.
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 [templates](/doc/templates/) later. If you're short on disk
space, you may wish to deselect these options.
Regardless of your choices on this screen, you will always be able to install these and other [templates](/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 Topics](/doc/#advanced-topics)).
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 topics](/doc/#advanced-topics)).
Press **Done** to go back to the installation summary screen.
### Installation destination
Under the System section, you must choose the installation destination. Select
the storage device on which you would like to install Qubes OS.
Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Be careful to choose the correct installation target, or you
may lose data. We strongly recommended making a full backup before
proceeding.
<b>Warning:</b> Be careful to choose the correct installation target, or you may lose data. We strongly recommended making a full backup before proceeding.
</div>
Your installation destination can be an internal or external storage drive,
such as an SSD, HDD, or USB drive. The installation destination must have a
least 32 GiB of free space available.
Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive. The installation destination must have a least 32 GiB of free space available.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> The installation destination cannot be the same as the
installation medium. For example, if you're installing Qubes OS <em>from</em>
a USB drive <em>onto</em> a USB drive, they must be two distinct USB drives,
and they must both be plugged into your computer at the same time. (Note:
This may not apply to advanced users who partition their devices
appropriately.)
<b>Note:</b> The installation destination cannot be the same as the installation medium. For example, if you're installing Qubes OS <em>from</em> a USB drive <em>onto</em> a USB drive, they must be two distinct USB drives, and they must both be plugged into your computer at the same time. (Note: This may not apply to advanced users who partition their devices appropriately.)
</div>
Installing an operating system onto a USB drive can be a convenient way to try
Qubes. However, USB drives are typically much slower than internal SSDs. We
recommend a very fast USB 3.0 drive for decent performance. Please note that a
minimum storage of 32 GiB is required. If you want to install Qubes OS onto a
USB drive, just select the USB device as the target installation device. Bear
in mind that the installation process is likely to take longer than it would on
an internal storage device.
Installing an operating system onto a USB drive can be a convenient way to try Qubes. However, USB drives are typically much slower than internal SSDs. We recommend a very fast USB 3.0 drive for decent performance. Please note that a minimum storage of 32 GiB is required. If you want to install Qubes OS onto a USB drive, just select the USB device as the target installation device. Bear in mind that the installation process is likely to take longer than it would on an internal storage device.
[![Select storage device](/attachment/doc/select-storage-device.png)](/attachment/doc/select-storage-device.png)
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> Qubes OS uses full-disk AES encryption (FDE) via LUKS by
default.
<b>Did you know?</b> By default, Qubes OS uses <a href="https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup">LUKS</a>/<a href="https://en.wikipedia.org/wiki/Dm-crypt">dm-crypt</a> to encrypt everything except the <code>/boot</code> partition.
</div>
As soon as you press **Done**, the installer will ask you to enter a passphrase
for disk encryption. The passphrase should be complex. Make sure that your
keyboard layout reflects what keyboard you are actually using. When you're
finished, press **Done**.
As soon as you press **Done**, the installer will ask you to enter a passphrase for disk encryption. The passphrase should be complex. Make sure that your keyboard layout reflects what keyboard you are actually using. When you're finished, press **Done**.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> If you forget your encryption passphrase, there is no way to
recover it.
<b>Warning:</b> If you forget your encryption passphrase, there is no way to recover it.
</div>
[![Select storage passhprase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
@ -378,27 +228,19 @@ When you're ready, press **Begin Installation**.
### Create your user account
While the installation process is running, you can create your user account.
This is what you'll use to log in after disk decryption and when unlocking the
screen locker. This is a purely local, offline account in dom0. By design,
Qubes OS is a single-user operating system, so this is just for you.
While the installation process is running, you can create your user account. This is what you'll use to log in after disk decryption and when unlocking the screen locker. This is a purely local, offline account in dom0. By design, Qubes OS is a single-user operating system, so this is just for you.
Select **User Creation** to define a new user with administrator privileges and
a password. Just as for the disk encryption, this password should be complex.
The root account is deactivated and should remain as such.
Select **User Creation** to define a new user with administrator privileges and a password. Just as for the disk encryption, this password should be complex. The root account is deactivated and should remain as such.
[![Account name and password](/attachment/doc/account-name-and-password.png)](/attachment/doc/account-name-and-password.png)
When the installation is complete, press **Reboot**. Don't forget to remove the
installation medium, or else you may end up seeing the installer boot screen
again.
When the installation is complete, press **Reboot**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
## Post-installation
### First boot
If the installation was successful, you should now see the GRUB menu during the
boot process.
If the installation was successful, you should now see the GRUB menu during the boot process.
[![Grub boot menu](/attachment/doc/grub-boot-menu.png)](/attachment/doc/grub-boot-menu.png)
@ -408,49 +250,27 @@ Just after this screen, you will be asked to enter your encryption passphrase.
### Initial Setup
You're almost done. Before you can start using Qubes OS, some configuration is
needed.
You're almost done. Before you can start using Qubes OS, some configuration is needed.
[![Initial setup menu](/attachment/doc/initial-setup-menu.png)](/attachment/doc/initial-setup-menu.png)
By default, the installer will create a number of qubes (depending on the
options you selected during the installation process). These are designed to
give you a more ready-to-use environment from the get-go.
By default, the installer will create a number of qubes (depending on the options you selected during the installation process). These are designed to give you a more ready-to-use environment from the get-go.
[![Initial setup menu configuration](/attachment/doc/initial-setup-menu-configuration.png)](/attachment/doc/initial-setup-menu-configuration.png)
Let's briefly go over the options:
* **Create default system qubes:**
These are the core components of the system, required for things like
internet access.
* **Create default application qubes:**
These are how you compartmentalize your digital life. There's nothing special
about the ones the installer creates. They're just suggestions that apply to
most people. If you decide you don't want them, you can always delete them
later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using
Whonix:**
If you select this option, then whenever you install or update software in
dom0 or a template, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the
USB controllers.
* **Use sys-net qube for both networking and USB devices:**
You should select this option if you rely on a USB device for network access,
such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:**
This is for very advanced users only. If you select this option, you'll have
to set everything up manually afterward.
* **Create default system qubes:** These are the core components of the system, required for things like internet access.
* **Create default application qubes:** These are how you compartmentalize your digital life. There's nothing special about the ones the installer creates. They're just suggestions that apply to most people. If you decide you don't want them, you can always delete them later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:** If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:** If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:** Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:** You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:** This is for very advanced users only. If you select this option, you'll have to set everything up manually afterward.
When you're satisfied with you choices, press **Done**. This configuration
process may take a while, depending on the speed and compatibility of your
system.
When you're satisfied with you choices, press **Done**. This configuration process may take a while, depending on the speed and compatibility of your system.
After the configuration is done, you will be greeted by the login screen. Enter
your password and log in.
After the configuration is done, you will be greeted by the login screen. Enter your password and log in.
[![Login screen](/attachment/doc/login-screen.png)](/attachment/doc/login-screen.png)
@ -462,67 +282,34 @@ Congratulations, you are now ready to use Qubes OS!
### Updating
Next, [update](/doc/how-to-update/) your installation to ensure you have
the latest security updates. Frequently updating is one of the best ways to
remain secure against new threats.
Next, [update](/doc/how-to-update/) 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
The Qubes OS Project occasionally issues [Qubes Security Bulletins
(QSBs)](/security/qsb/) as part of the [Qubes Security Pack
(qubes-secpack)](/security/pack/). It is important to make sure that you
receive all QSBs in a timely manner so that you can take action to keep your
system secure. (While [updating](#updating) will handle most security needs,
there may be cases in which additional action from you is required.) For this
reason, we strongly recommend that every Qubes user subscribe to the
[qubes-announce](/support/#qubes-announce) mailing list.
The Qubes OS Project occasionally issues [Qubes Security Bulletins (QSBs)](/security/qsb/) as part of the [Qubes Security Pack (qubes-secpack)](/security/pack/). It is important to make sure that you receive all QSBs in a timely manner so that you can take action to keep your system secure. (While [updating](#updating) will handle most security needs, there may be cases in which additional action from you is required.) For this reason, we strongly recommend that every Qubes user subscribe to the [qubes-announce](/support/#qubes-announce) mailing list.
In addition to QSBs, the Qubes OS Project also publishes
[Canaries](/security/canary/), XSA summaries, template releases and
end-of-life notices, and other items of interest to Qubes users. Since these
are not essential for all Qubes users to read, they are not sent to
[qubes-announce](/support/#qubes-announce) in order to keep the volume on that
list low. However, we expect that most users, especially novice users, will
find them helpful. If you are interested in these additional items, we
encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one
of our other [venues](/support/), where these news items are also announced.
In addition to QSBs, the Qubes OS Project also publishes [Canaries](/security/canary/), XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users. Since these are not essential for all Qubes users to read, they are not sent to [qubes-announce](/support/#qubes-announce) in order to keep the volume on that list low. However, we expect that most users, especially novice users, will find them helpful. If you are interested in these additional items, we encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one of our other [venues](/support/), where these news items are also announced.
For more information about Qubes OS Project security, please see the [security
center](/security/).
For more information about Qubes OS Project security, please see the [security center](/security/).
### Backups
It is extremely important to make regular backups so that you don't lose your
data unexpectedly. The [Qubes backup
system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this
securely and easily.
It is extremely important to make regular backups so that you don't lose your data unexpectedly. The [Qubes backup system](/doc/how-to-back-up-restore-and-migrate/) allows you to do this securely and easily.
### 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](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports).
Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports).
### Get Started
Find out [Getting Started](/doc/getting-started/) with Qubes, check out
the other [How-To Guides](/doc/#how-to-guides), and learn about
[Templates](/doc/#templates).
Find out [Getting Started](/doc/getting-started/) with Qubes, check out the other [How-To Guides](/doc/#how-to-guides), and learn about [Templates](/doc/#templates).
## Getting help
* 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](/doc/how-to-edit-the-documentation/) it!)
* 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](/doc/how-to-edit-the-documentation/) it!)
* If issues arise during installation, see the [Installation
Troubleshooting](/doc/installation-troubleshooting) guide.
* 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](/support/) 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](/support/) for appropriate places to ask questions.
* 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](/support/) for appropriate places to ask questions.

61
user/downloading-installing-upgrading/supported-releases.md
View file

@ -19,16 +19,17 @@ 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 |
| ----------- | ---------- | ---------- | --------------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported |
| 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 | 2022-08-04 | Supported |
| Release 4.1 | 2022-02-04 | TBA | Supported |
| Release 4.2 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.2%22) |
| Qubes OS | Start Date | End Date | Status |
| ----------- | ---------- | ---------- | -------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported |
| 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 | 2022-08-04 | Unsupported |
| Release 4.1 | 2022-02-04 | 2024-06-18 | Supported |
| Release 4.2 | 2023-12-18 | TBA | Supported |
| Release 4.3 | TBA | TBA | In development |
### Note on patch releases
@ -53,6 +54,7 @@ The table below shows the OS used for dom0 in each Qubes OS release.
| Release 3.2 | Fedora 23 |
| Release 4.0 | Fedora 25 |
| Release 4.1 | Fedora 32 |
| Release 4.2 | Fedora 37 |
### Note on dom0 and EOL
@ -89,18 +91,10 @@ upstream release on the upstream distribution's website (see [Fedora
EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian
Releases](https://wiki.debian.org/DebianReleases)).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | --------------------------------------------------- | ------ |
| Release 4.0 | 34 | 9 (Stretch),<sup>*</sup> 10 (Buster), 11 (Bullseye) | 16 |
| Release 4.1 | 34 | 10 (Buster), 11 (Bullseye) | 16 |
<sup>\*</sup> Although Debian 9 has reached regular EOL and is now in
[LTS](https://wiki.debian.org/LTS), we continue to support it for Qubes R4.0.
This is a *temporary* exception to our [policy](#note-on-debian-support) of
ending Qubes support at each Debian release's *regular* (not LTS) EOL date,
since this policy was introduced after the release of Qubes R4.0. In Qubes R4.1
and beyond, Qubes support for each Debian release will end when that release
reaches regular EOL and will not extend into LTS.
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ------ | ------ |
| Release 4.1 | 38 | 11, 12 | 16 |
| Release 4.2 | 38 | 12 | 17 |
### Note on Debian support
@ -114,23 +108,6 @@ chart that illustrates this. Qubes support ends at the *regular* EOL date,
[Whonix](https://www.whonix.org/wiki/Qubes) templates are supported by our
partner, the [Whonix Project](https://www.whonix.org/). The Whonix Project has
set its own support policy for Whonix templates in Qubes.
This policy requires Whonix template users to stay reasonably close to the
cutting edge by upgrading to new stable releases of Qubes OS and Whonix
templates within a month of their respective releases. To be precise:
* One month after a new stable version of Qubes OS is released, Whonix
templates will no longer be supported on any older release of Qubes OS. This
means that users who wish to continue using Whonix templates on Qubes must
always upgrade to the latest stable Qubes OS release within one month of its
release.
* One month after new stable versions of Whonix templates are released, older
releases of Whonix templates will no longer be supported. This means that
users who wish to continue using Whonix templates on Qubes must always
upgrade to the latest stable Whonix template releases within one month of
their release.
We aim to announce both types of events one month in advance in order to remind
users to upgrade.
set its own support policy for Whonix templates in Qubes. Please see the
[Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts)
for details.

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

@ -7,101 +7,52 @@ ref: 147
title: Testing new releases and updates
---
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. If
you're interested in helping with this, please [join the testing
team](https://forum.qubes-os.org/t/joining-the-testing-team/5190). There are
several different types of testing, which we'll cover below.
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. If you're interested in helping with this, please [join the testing team](https://forum.qubes-os.org/t/joining-the-testing-team/5190). There are several different types of testing, which we'll cover below.
**Warning:** Software testing is intended for advanced users and developers.
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!
**Warning:** Software testing is intended for advanced users and developers. 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!
## Releases
How to test upcoming Qubes OS releases:
* Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
* Test the latest release candidate (RC), if one is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at
[Qubes OpenQA](https://openqa.qubes-os.org/).
- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself.
- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
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.
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](/doc/how-to-install-software-in-dom0/#testing-repositories).
* Enable [template testing
repositories](/doc/how-to-install-software/#testing-repositories).
- Enable [dom0 testing repositories](/doc/how-to-install-software-in-dom0/#testing-repositories).
- Enable [template testing repositories](/doc/how-to-install-software/#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 last weeks
or even months, depending on the amount of feedback received (see [Providing
feedback](#providing-feedback)).
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 last 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.
"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`. This means that, if a newer version of a package is uploaded to
`current-testing`, it will no longer be possible to migrate any older versions
of that same package from `current-testing` to `current`, even if one of those
older versions has been deemed stable enough. While this limitation can be
inconvenient, the benefits outweigh the costs, since it greatly simplifies the
testing and reporting process.
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`. This means that, if a newer version of a package is uploaded to `current-testing`, it will no longer be possible to migrate any older versions of that same package from `current-testing` to `current`, even if one of those older versions has been deemed stable enough. While this limitation can be inconvenient, the benefits outweigh the costs, since it greatly simplifies the testing and reporting process.
## Templates
How to test [templates](/doc/templates/):
* For official templates, enable the `qubes-templates-itl-testing` repository,
then [install](/doc/templates/#installing) the desired template.
* For community templates, enable the `qubes-templates-community-testing`
repository, then [install](/doc/templates/#installing) the desired template.
- For official templates, enable the `qubes-templates-itl-testing` repository, then [install](/doc/templates/#installing) the desired template.
- For community templates, enable the `qubes-templates-community-testing` repository, then [install](/doc/templates/#installing) the desired template.
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. Example commands:
```
sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing
sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing
qvm-template --enablerepo=qubes-templates-itl-testing list --available
qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
```
To enable or disable any of these repos permanently, change the corresponding
`enabled` value to `1` in `/etc/yum.repos.d/qubes-templates.repo`.
To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`. To disable any of these repos permanently, change the corresponding `enabled` value to `0`.
## Providing feedback
Since the whole point of testing software is to discover and fix bugs, your
feedback is an essential part of this process.
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](/doc/issue-tracking/) in a package that is in a testing repository, please
reference the appropriate issue in
[updates-status](https://github.com/QubesOS/updates-status/issues).
Since the whole point of testing software is to discover and fix bugs, your feedback is an essential part of this process. 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> "thumbs up" or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> "thumbs down" reaction 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](/doc/issue-tracking/) in a package that is in a testing repository, please reference the appropriate issue in [updates-status](https://github.com/QubesOS/updates-status/issues).

21
user/downloading-installing-upgrading/upgrade/4_1.md
View file

@ -5,16 +5,17 @@ permalink: /doc/upgrade/4.1/
title: How to upgrade to Qubes 4.1
---
This page explains how to perform an in-place upgrade from Qubes 4.0 to Qubes
4.1. It is not possible to upgrade directly from releases earlier than 4.0. If
you're still on an earlier release, please either perform a [clean installation
of 4.1](#clean-installation) or [upgrade to 4.0](/doc/upgrade/4.0/) first.
This page explains how to upgrade from Qubes 4.0 to Qubes 4.1. There are two
ways to upgrade: a clean installation or an in-place upgrade. In general, a
clean installation is simpler and less error-prone, but an in-place upgrade
allows you to preserve your customizations.
## Back up
Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that you first [back up your
system](/doc/how-to-back-up-restore-and-migrate/).
system](/doc/how-to-back-up-restore-and-migrate/) so that you don't lose any
data.
## Clean installation
@ -24,14 +25,20 @@ in-place:
1. Create a
[backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your
current installation.
2. Follow the [installation guide](/doc/installation-guide/) to install Qubes
2. [Download](/downloads/) the latest 4.1 release.
3. Follow the [installation guide](/doc/installation-guide/) to install Qubes
4.1.
3. [Restore from your
4. [Restore from your
backup](/doc/how-to-back-up-restore-and-migrate/#restoring-from-a-backup) on
your new 4.1 installation.
## In-place upgrade
**Warning:** It is not possible to upgrade directly from releases earlier than
4.0. If you're still on an earlier release, please either perform a [clean
installation of 4.1](#clean-installation) or [upgrade to
4.0](/doc/upgrade/4.0/) first.
The upgrade may take several hours, and will download several gigabytes of
data.

109
user/downloading-installing-upgrading/upgrade/4_2.md Normal file
View file

@ -0,0 +1,109 @@
---
lang: en
layout: doc
permalink: /doc/upgrade/4.2/
title: How to upgrade to Qubes 4.2
---
This page explains how to upgrade from Qubes 4.1 to Qubes 4.2. There are two
ways to upgrade: a clean installation or an in-place upgrade. In general, a
clean installation is simpler and less error-prone, but an in-place upgrade
allows you to preserve your customizations.
## Back up
Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that you first [back up your
system](/doc/how-to-back-up-restore-and-migrate/) so that you don't lose any
data.
## Clean installation
If you would prefer to perform a clean installation rather than upgrading
in-place:
1. Create a
[backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your
current installation.
2. [Download](/downloads/) the latest 4.2 release.
3. Follow the [installation guide](/doc/installation-guide/) to install Qubes
4.2.
4. [Restore from your
backup](/doc/how-to-back-up-restore-and-migrate/#restoring-from-a-backup) on
your new 4.2 installation.
## In-place upgrade
**Warning:** It is not possible to upgrade directly from releases earlier than
4.1. If you're still on an earlier release, please either perform a [clean
installation of 4.2](#clean-installation) or [upgrade to
4.1](/doc/upgrade/4.1/) first.
The upgrade may take several hours, and will download several gigabytes of
data.
In place upgrade is a complex operation. For this reason, we provide a
`qubes-dist-upgrade` tool to handle all the necessary steps automatically. You
can install it with the following command in the dom0 terminal:
sudo qubes-dom0-update -y qubes-dist-upgrade
The upgrade consists of six stages --- three before restarting the system ---
labeled "STAGE 1" through "STAGE 3" in the options list below, and three after restarting the system --- labeled as "STAGE 4" through "STAGE 6" below.
Full list of options can be obtained with `qubes-dist-upgrade --help`:
Usage: qubes-dist-upgrade [OPTIONS]...
This script is used for updating current QubesOS R4.1 to R4.2.
Options:
--update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM.
--release-upgrade, -r (STAGE 2) Update 'qubes-release' for Qubes R4.2.
--dist-upgrade, -s (STAGE 3) Upgrade to Qubes R4.2 and Fedora 37 repositories.
--template-standalone-upgrade, -l (STAGE 4) Upgrade templates and standalone VMs to R4.2 repository.
--finalize, -x (STAGE 5) Finalize upgrade. It does:
- resync applications and features
- cleanup salt states
--convert-policy, -p (STAGE 6) Convert qrexec policy in /etc/qubes-rpc/policy
to the new format in /etc/qubes/policy.d.
--all-pre-reboot Execute stages 1 to 3
--all-post-reboot Execute stages 4 to 6
--assumeyes, -y Automatically answer yes for all questions.
--usbvm, -u Current UsbVM defined (default 'sys-usb').
--netvm, -n Current NetVM defined (default 'sys-net').
--updatevm, -f Current UpdateVM defined (default 'sys-firewall').
--skip-template-upgrade, -j Don't upgrade TemplateVM to R4.2 repositories.
--skip-standalone-upgrade, -k Don't upgrade StandaloneVM to R4.2 repositories.
--only-update Apply STAGE 4 and resync appmenus only to
selected qubes (comma separated list).
--keep-running List of extra VMs to keep running during update (comma separated list).
Can be useful if multiple updates proxy VMs are configured.
--max-concurrency How many TemplateVM/StandaloneVM to update in parallel in STAGE 1
(default 4).
After installing the tool, before-reboot stages can be performed at once with:
sudo qubes-dist-upgrade --all-pre-reboot
Optionally, an `--assumeyes` (or `-y`) option can be used to automatically
accept all the actions without confirmation.
Alternatively, each upgrade stage can be started separately (see the list of
options above).
After completing "STAGE 1" through "STAGE 3", restart the system. Then perform
the final steps:
sudo qubes-dist-upgrade --all-post-reboot
After performing those steps, it's recommended to restart the system one last time.
When this completes, you can start using Qubes OS 4.2.
## Update
After upgrading or performing a clean installation, we strongly recommend
[updating your system](/doc/how-to-update/).

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

@ -19,3 +19,4 @@ see [how to update](/doc/how-to-update/).
* [Upgrade from 3.1 to 3.2](/doc/upgrade/3.2/)
* [Upgrade from 3.2 to 4.0](/doc/upgrade/4.0/)
* [Upgrade from 4.0 to 4.1](/doc/upgrade/4.1/)
* [Upgrade from 4.1 to 4.2](/doc/upgrade/4.2/)

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

@ -10,175 +10,96 @@ ref: 144
title: Certified hardware
---
The Qubes OS Project aims to partner with a select few computer vendors to
ensure that Qubes users have reliable hardware purchasing options. We aim for
these vendors to be as diverse as possible in terms of geography, cost, and
availability.
The Qubes OS Project aims to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options. We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> The Qubes OS Project certifies only that a particular
hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is
available to purchase with Qubes OS preinstalled. We take no responsibility
for any vendor's manufacturing, shipping, payment, or other practices; nor
can we control whether physical hardware is modified (whether maliciously or
otherwise) <i>en route</i> to the user.
<b>Warning:</b> The Qubes OS Project certifies only that a particular hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is available to purchase with Qubes OS preinstalled. We take no responsibility for any vendor's manufacturing, shipping, payment, or other practices; nor can we control whether physical hardware is modified (whether maliciously or otherwise) <i>en route</i> to the user.
</div>
You may also be interested in the [community-recommended
hardware](https://forum.qubes-os.org/t/5560) list and the [hardware
compatibility list (HCL)](/hcl/).
You may also be interested in the [community-recommended hardware](https://forum.qubes-os.org/t/5560) list and the [hardware compatibility list (HCL)](/hcl/).
## Qubes-certified Laptops
## Qubes-certified computers
Qubes-certified laptops are certified for a [major
release](/doc/version-scheme/) and regularly tested by the Qubes developers to
ensure compatibility with all of Qubes' features within that major release. The
developers test all new updates within that major release to ensure that no
regressions are introduced.
Qubes-certified computers are certified for a [major release](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major release. The developers test all new updates within that major release to ensure that no regressions are introduced.
The current Qubes-certified models are listed below in chronological order of certification.
### Insurgo PrivacyBeast X230
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
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!
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) for details.
### NitroPad X230
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
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. Read our
[announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) of the
certification for further details!
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for details.
### NitroPad T430
[![nitropad-t-430.jpg](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
satisfies all hardware certification requirements for Qubes 4, offering users
extensive hardware security options. Read our
[announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) of the
certification for further details!
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for details.
### Dasharo FidelisGuard Z690
## Become Hardware Certified
[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
If you are a hardware vendor, you can have your hardware certified as
compatible with Qubes OS. The benefits of hardware certification include:
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) for details.
- Your customers can purchase with confidence, knowing that they can take full
advantage of Qubes OS on your hardware for a specific major version.
- We will continue testing your hardware to ensure compatibility with the
supported major version. In the course of this testing, we will also test
your hardware against upcoming versions, which can help with future planning.
- Your hardware will continue to be compatible with Qubes OS as it further
develops within that major version, and we will work with you toward
preserving compatibility and certification in future releases.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/)
The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for details.
### NitroPC Pro
[![Photo of the NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is a desktop based on the MSI PRO Z690-A DDR5 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/09/06/nitropc-pro-qubes-certified/) for details.
## Become hardware certified
If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS. The benefits of hardware certification include:
- Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware for a specific major version.
- We will continue testing your hardware to ensure compatibility with the supported major version. In the course of this testing, we will also test your hardware against upcoming versions, which can help with future planning.
- Your hardware will continue to be compatible with Qubes OS as it further develops within that major version, and we will work with you toward preserving compatibility and certification in future releases.
- You can support the development of Qubes OS.
## Hardware Certification Requirements
## Hardware certification requirements
(Please note that these are the requirements for hardware *certification*,
*not* the requirements for *running* Qubes OS. For the latter, please see the
[system requirements](/doc/system-requirements/).)
**Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware).
A basic requirement is that all Qubes-certified devices must be be available
for purchase with Qubes OS preinstalled. Customers may be offered the option to
select from a list of various operating systems (or no operating system at all)
to be preinstalled, but Qubes OS must be on that list in order to maintain
Qubes hardware certification.
A basic requirement is that all Qubes-certified devices must be be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
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](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.
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](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](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.
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](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.
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.
Finally, we require that Qubes-certified hardware does not have any built-in
_USB-connected_ microphones (e.g. as part of a USB-connected built-in camera)
that cannot be easily physically disabled by the user, e.g. via a convenient
mechanical switch. Thankfully, the majority of laptops on the market that we
have seen already satisfy this condition out-of-the-box, because their built-in
microphones are typically connected to the internal audio device, which itself
is a type of PCIe device. This is important, because such PCIe audio devices
are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through
our carefully designed protocol only to select app qubes when the user
explicitly chooses to do so. The rest of the time, they should be outside the
reach of malware.
Most laptops use PS/2 connections internally for their input devices (i.e., keyboard and touchpad). On most desktops, however, USB-connected keyboards and mice have become standard. This presents a dilemma when the computer has only one USB controller. If that single USB controller is dedicated solely to the input devices, then no untrusted USB devices can be used. Conversely, if the sole USB controller is completely untrusted, then there is no way for the user to physically control the system in a secure way. In practice, Qubes users on such hardware systems are generally forced to use a single USB controller for both trusted and untrusted purposes --- [an unfortunate security trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices). For this reason, we require that every Qubes-certified non-laptop device **either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a separate USB controller that is only for input devices.
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).
Finally, we require that Qubes-certified hardware does not have any built-in _USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) that cannot be easily physically disabled by the user, e.g. via a convenient mechanical switch. Thankfully, the majority of laptops on the market that we have seen already satisfy this condition out-of-the-box, because their built-in microphones are typically connected to the internal audio device, which itself is a type of PCIe device. This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select app qubes when the user explicitly chooses to do so. The rest of the time, they should be outside the reach of malware.
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](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.
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).
We hope these hardware requirements will encourage the development of more
secure and trustworthy devices.
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](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.
## Hardware Certification Process
We hope these hardware requirements will encourage the development of more secure and trustworthy devices.
## Hardware certification process
To have hardware certified, the vendor must:
1. Send the Qubes team two (2) units for testing (non-returnable) for each
configuration the vendor wishes to be offering.
2. Offer to customers the very same configuration (same motherboard, same
screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the
hardware vendor and the Qubes team.
1. Send the Qubes team two (2) units for testing (non-returnable) for each configuration the vendor wishes to be offering.
2. Offer to customers the very same configuration (same motherboard, same screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
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](/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.
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](/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](mailto:business@qubes-os.org).
If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org).

14
user/hardware/how-to-use-the-hcl.md
View file

@ -27,15 +27,11 @@ Also see [Certified Hardware](/doc/certified-hardware/).
Generating and Submitting New Reports
-------------------------------------
In order to generate an HCL report in Qubes, simply open a terminal in dom0 (KDE: start-menu -\> System Tools -\> Konsole or Terminal Emulator)
and run `qubes-hcl-report <vm-name>`, where `<vm-name>` is the name of the VM to which the generated HCL files will be saved.
(Note: If you are working with a new Qubes installation, you may need to update your system in order to download this script.)
In order to generate an HCL report in Qubes, simply open a terminal in dom0 (Applications Menu > Terminal Emulator) and run `qubes-hcl-report <qube-name>`, where `<qube-name>` is the name of the qube in which the generated HCL files will be saved.
You are encouraged to submit your HCL report for the benefit of further Qubes development and other users.
When submitting reports, test the hardware yourself, if possible.
If you would like to submit your HCL report, please send the **HCL Info** `.yml` file to [\`qubes-users@googlegroups.com\`](/support/#qubes-users) with the subject `HCL - <your machine model name>`. Alternatively you can also create a post in the [HCL Reports category](https://forum.qubes-os.org/c/user-support/hcl-reports/23) of the forum.
Please include any useful information about any Qubes features you may have tested (see the legend below), as well as general machine compatibility (video, networking, sleep, etc.).
Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To generate these add the `-s` or `--support` command line option.
You are encouraged to submit your HCL report for the benefit of further Qubes development and other users. When submitting reports, test the hardware yourself, if possible. If you would like to submit your HCL report, please copy and paste the contents of the **HCL Info** `.yml` file into an email to the [qubes-users mailing list](/support/#qubes-users) with the subject `HCL - <your machine model name>`, or create a post in the [HCL Reports category](https://forum.qubes-os.org/c/user-support/hcl-reports/23) of the forum. Pasting the contents into the email or post has the advantage that members of the mailing list and the forum can see the report without downloading and opening a file. In addition, new forum members are unable to attach files to posts.
Please include any useful information about any Qubes features you may have tested (see the legend below), as well as general machine compatibility (video, networking, sleep, etc.). Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To generate these add the `-s` or `--support` command line option.
**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.
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** post the `.cpio.gz` file on a public mailing list or forum.

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

@ -26,7 +26,9 @@ title: System requirements
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [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:** 6 GB RAM
- **Storage:** 32 GB free space
## Recommended
@ -34,19 +36,37 @@ title: System requirements
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [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](/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](/doc/anti-evil-maid/))
- **Other:** Satisfaction of all [hardware certification requirements for Qubes
4.x](/news/2016/07/21/new-hw-certification-for-q4/)
### Qubes-certified hardware
The following are *required* for [Qubes-certified hardware
devices](/doc/certified-hardware/) but *merely recommended* for *non-certified*
hardware (see the [hardware certification
requirements](/doc/certified-hardware/#hardware-certification-requirements) for
details).
- Open-source boot firmware (e.g., [coreboot](https://www.coreboot.org/))
- Hardware switches for all built-in USB-connected microphones (if any)
- Either support for non-USB input devices (e.g., via PS/2, which most laptops
already use internally) or a separate USB controller only for input devices
## Choosing Hardware

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

@ -67,14 +67,14 @@ encrypted and compressed.
4. Decrypt the `private.img` file.
~~~
[user@restore vm1]$ openssl enc -d -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
~~~
**Note:** For multi-part files, a loop can be used:
~~~
find -name 'private.img.*' | sort -V | while read f; do
openssl enc -d -pass pass:"$backup_pass" -aes-256-cbc -in $f -out
openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in $f -out
${f/.img/.img.dec}
done
~~~

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

@ -98,7 +98,7 @@ any GNU/Linux system with the following procedure.
6. Decrypt the `private.img` file.
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -pass pass:"$backup_pass" -aes-256-cbc -out private.img.dec
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -out private.img.dec
**Note:** If your backup was encrypted with a cipher algorithm other than
`aes-256-cbc`, you must substitute the correct cipher command. This

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

@ -170,7 +170,7 @@ occur. However, if you do wish to move all files from the dom0 backup out of
the subdirectory into your current dom0 home directory (overwriting any
existing files in the process), you may do so by following the instructions
[here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
Just remember that this can cause unexpected and desired configuration changes
Just remember that this can cause unexpected and undesired configuration changes
in dom0, depending on exactly which files you're adding and replacing.
## Emergency backup recovery without qubes

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

@ -73,15 +73,27 @@ For example, if you are certain that you never wish to paste *into* your "vault"
@anyvm @anyvm ask
~~~
Automatic clipboard wiping
--------------------------
By default data pasted into a qube will remain there until user copies something else or restarts the qube. It's possible to make the `qubes-gui` process inside a qube wipe the clipboard automatically after a minute from the last paste operation. This helps protect users from accidentally pasting the old content of the clipboard like a password in the wrong place like a browser search bar. Since qubes don't share the same clipboard, software like KeePassXC isn't able to automatically wipe the clipboard of other qubes.
To enable automatic wiping of the clipboard after a minute use `qvm-service`:
~~~
qvm-service --enable VMNAME gui-agent-clipboard-wipe
~~~
Shortcut configuration
----------------------
The copy/paste shortcuts are configurable in:
The copy/paste shortcuts are configurable via `qvm-features`, e.g.
~~~
/etc/qubes/guid.conf
qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'
~~~
If you edit a line in this file, you must uncomment it (by removing the initial `#` character), or else it will have no effect.
would change the *copy/paste to global clipboard* to the Win key plus c for copy, or v for paste.
VMs need to be restarted in order for changes in `/etc/qubes/guid.conf` to take effect.
You need to restart Qubes for the changes to take effect.

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

@ -144,11 +144,11 @@ Please see [How to Update](/doc/how-to-update/).
In order to protect you from performing risky activities in templates, they do
not have normal network access by default. Instead, templates use an [updates
proxy](#updates-proxy) that allows you to install and update software without
giving the template direct network access. **The updates proxy is already set
up to work automatically out-of-the-box and requires no special action from
you.** Most users should simply follow the normal instructions for [installing
software from default
proxy](#updates-proxy) that allows you to install and update software using
the distribution package manager without giving the template direct network
access.**The updates proxy is already setup to work automatically
out-of-the-box and requires no special action from you.** Most users should
simply follow the normal instructions for [installing software from default
repositories](#installing-software-from-default-repositories) and
[updating](/doc/how-to-update/) software. If your software is not available in
the default repositories, see [installing software from other
@ -304,19 +304,22 @@ This is like the simple revert, except:
### Updates proxy
Updates proxy is a service which allows access only from package managers. This
is meant to mitigate user errors (like using browser in the template), rather
than some real isolation. It is done with http proxy (tinyproxy) instead of
simple firewall rules because it is hard to list all the repository mirrors
(and keep that list up to date). The proxy is used only to filter the traffic,
not to cache anything.
Updates proxy is a service which allows access from package managers
configured to use the proxy by default, but can be used by any other
program that accepts proxy arguments.
The purpose of the proxy, instead of direct network access, is meant to
mitigate user errors of using applications such as the browser in the
template. Not necessarily what part of the network they can access, but only
to applications trusted by the user, configured to use the proxy.
The http proxy (tinyproxy) does not filter traffic because it is hard to list
all the repository mirrors and keep that list up to date). it also does not
cache anything.
The proxy is running in selected VMs (by default all the NetVMs (1)) and
intercepts traffic directed to 10.137.255.254:8082. Thanks to such
configuration all the VMs can use the same proxy address, and if there is a
proxy on network path, it will handle the traffic (of course when firewall
rules allow that). If the VM is configured to have access to the updates proxy
(2), the startup scripts will automatically configure dnf to really use the
intercepts traffic directed to 127.0.0.1:8082. Thanks to such
configuration all the VMs can use the same proxy address.
If the VM is configured to have access to the updates proxy
(2), the startup scripts will automatically configure dnf/apt to really use the
proxy (3). Also access to updates proxy is independent of any other firewall
settings (VM will have access to updates proxy, even if policy is set to block
all the traffic).
@ -343,7 +346,7 @@ sys-net and/or sys-whonix, depending on firstboot choices. This new design
allows for templates to be updated even when they are not connected to any
NetVM.
Example policy file in R4.0 (with Whonix installed, but not set as default
Example policy file in R4.1 (with Whonix installed, but not set as default
UpdateVM for all templates):
```shell_session
@ -352,7 +355,7 @@ UpdateVM for all templates):
@tag:whonix-updatevm @anyvm deny
# other templates use sys-net
@type:template @default allow,target=sys-net
@type:TemplateVM @default allow,target=sys-net
@anyvm @anyvm deny
```
@ -367,24 +370,24 @@ these in an app qube you need to take the following steps:
a terminal in the template and run:
```shell_session
[user@fedora-30-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:55:39 ago on Thu Nov 14 09:26:47 2019.
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
Dependencies resolved.
========================================================================================================
Package Arch Version Repository Size
========================================================================================================
Installing:
snapd x86_64 2.42.1-1.fc30 updates 17 M
qubes-snapd-helper noarch 1.0.1-1.fc30 qubes-vm-r4.0-current 10 k
snapd x86_64 2.56.2-4.fc36 updates 14 M
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
Installing dependencies:
[...]
Transaction Summary
========================================================================================================
Install 20 Packages
Install 19 Packages
Total download size: 37 M
Installed size: 121 M
Total download size: 27 M
Installed size: 88 M
Is this ok [y/N]: y
Downloading Packages:
@ -392,11 +395,11 @@ these in an app qube you need to take the following steps:
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed!
[...]
Last metadata expiration check: 0:57:08 ago on Thu Nov 14 09:26:47 2019.
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
Notifying dom0 about installed applications
Installed:
snapd-2.42.1-1.fc30.x86_64 qubes-snapd-helper-1.0.1-1.fc30.noarch
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch
[...]
Complete!
```
@ -413,7 +416,7 @@ these in an app qube you need to take the following steps:
Shutdown the template:
```shell_session
[user@fedora-30-snap-demo ~]$ sudo shutdown -h now
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
```
2. Now open the **app qube** in which you would like to install the Snap

538
user/how-to-guides/how-to-organize-your-qubes.md Normal file
View file

@ -0,0 +1,538 @@
---
lang: en
layout: doc
permalink: /doc/how-to-organize-your-qubes/
title: How to organize your qubes
---
When people first learn about Qubes OS, their initial reaction is often, "Wow,
this looks really cool! But... what can I actually *do* with it?" It's not
always obvious which qubes you should create, what you should do in each one,
and whether your organizational ideas makes sense from a security or usage
perspective.
Each qube is essentially a secure compartment, and you can create as many of
them as you like and connect them to each other in various ways. They're sort
of like Lego blocks in the sense that you can build whatever you want. But if
you're not sure what to build, then this open-ended freedom can be daunting.
It's a bit like staring at a blank document when you first sit down to write
something. The possibilities are endless, and you may not know where to begin!
The truth is that no one else can tell you *exactly* how you should organize
your qubes, as there is no single correct answer to that question. It depends
on your needs, desires, and preferences. Every user's optimal setup will be
different. However, what we *can* do is provide you with some illustrative
examples based on questionnaires and interviews with Qubes users and
developers, as well as our own personal experience and insight from using Qubes
over the years. You may be able to adapt some of these examples to fit your own
unique situation. More importantly, walking you through the rationale behind
various decisions will teach you how to apply the same thought process to your
own organizational decisions. Let's begin!
## Alice, the software developer
Alice is a freelance dev who works on several projects for different clients
simultaneously. The projects have varying requirements and often different
build environments. She has a separate set of qubes for each project. She keeps
them organized by coming up with a naming scheme, such as:
```
clientA-code
clientA-build
clientA-test
clientA-prod
projectB-code
projectB-build-test
projectB-prod
...
```
This helps her keep groups of qubes organized in a set. Some of her qubes are
based on [Debian templates](/doc/templates/debian/), while others are based on
[Fedora templates](/doc/templates/fedora/). The reason for this is that some
software packages are more readily available in one distribution as opposed to
the other. Alice's setup looks like this:
[![Alice's system: diagram 1](/attachment/doc/howto_use_qubes_alice_1.png)](/attachment/doc/howto_use_qubes_alice_1.png)
- **Several qubes for writing code.** Here's where she runs her IDE, commits
code, and signs her commits. These qubes are based on different templates
depending on which tools and which development environment she needs. In
general, Alice likes to have a separate qube of this type for each client or
each project. This allows her to keep everything organized and avoid
accidentally mixing up any access credentials or client code, which could be
disastrous. This also allows her to truthfully tell her clients that their
code is always securely isolated from all her other clients. She likes to use
the [Qubes firewall](/doc/firewall/) to restrict these qubes' network access
to only the code repositories she needs in that qube in order to avoid
accidentally interacting with anything else on her local network or on the
internet. Alice also has some qubes of this type for personal programming
projects that she works on just for fun when she has "free time" (whatever
that is).
- **Several qubes for building and testing.** Again, Alice usually likes to
have one of these for each client or project in order to keep things
organized. However, this can become rather cumbersome and memory-intensive
when many such qubes are running at the same time, so Alice will sometimes
use the same qube for building and testing, or for multiple projects that
require the same environment, when she decides that the marginal benefits of
extra compartmentalization aren't worth the trouble. Here's where she pulls
any dependencies she needs, compiles her code, runs her build toolchain, and
tests her deliverables. In some cases, she finds it useful to use
[standalones](/doc/standalones-and-hvms/) for these so that it's easier to
quickly [install different pieces of software](/doc/how-to-install-software/)
without having to juggle rebooting both the template and an app qube. She
also sometimes finds it necessary (or just convenient) to make edits to
config files in the root filesystem, and she'd rather not have to worry about
losing those changes during an app qube reboot. She knows that she could use
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
she doesn't want to get bogged down doing with all that and figures it
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
OS doesn't judge her this and just gives her the freedom to do things however
she likes while keeping everything securely compartmentalized. At times like
these, she takes comfort in knowing that things can be messy and disorganized
*within* a qube while her overall digital life remains well-organized.
[![Alice's system: diagram 2](/attachment/doc/howto_use_qubes_alice_2.png)](/attachment/doc/howto_use_qubes_alice_2.png)
- **Several email qubes.** Since Alice is a command-line aficionado, she likes
to use a terminal-based email client, so both her work and personal email
qubes are based on a template with
[Mutt](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md)
installed. The email qubes where she sends and receives PGP-signed and
encrypted email securely accesses the private keys in her PGP backend qube
(more on that below). To guard against malicious attachments, she configured
Mutt to open all attachment files in [disposable
qubes](/doc/how-to-use-disposables/).
- **Several qubes for communication tools,** like Signal, Slack, Zoom,
Telegram, IRC, and Discord. This is where she teleconferences and chats with
clients. She uses [USB passthrough](/doc/how-to-use-usb-devices/) to attach
her webcam to each qube as needed and detaches it afterward. Likewise, she
gives each qube access to her microphone while it's needed, then removes
access afterward. This way, she doesn't have to trust any given video chat
program's mute button and doesn't have to worry about being spied on when
she's not on a call. She also has a qube for social media platforms like
Twitter, Reddit, and Hacker News for networking and keeping up with new
developments (or so she claims; in reality, it's mostly for feuds over
programming language superiority, Vim vs. Emacs wars, and tabs vs. spaces
crusades).
- **A GPG backend vault.** Vaults are completely offline qubes that are
isolated from the network. This particular vault holds Alice's private keys
(e.g., for code signing and email) and is securely accessed by several other
"frontend" qubes via the [Split GPG](/doc/split-gpg/) system. Split GPG
allows only the frontend qubes that Alice explicitly authorizes to have the
ability to request PGP operations (e.g., signing and encryption) in the
backend vault. Even then, no qube ever has direct access to Alice's private
keys except the backend vault itself.
- **A password manager vault.** This is another completely offline,
network-isolated qube where Alice uses her offline password manager,
KeePassXC, to store all of her usernames and passwords. She uses the [secure
copy and paste](/doc/how-to-copy-and-paste-text/) system to quickly copy
credentials into other qubes whenever she needs to log into anything.
- **Personal qubes.** One of the things Alice loves the most about Qubes is
that she can use it for both work *and* personal stuff without having to
worry about cross-contamination. Accordingly, she has several qubes that
pertain to her personal life. For example, she has an offline vault that
holds her medical documents, test results, and vaccination records. She has
another offline vault for her government documents, birth certificate, scans
of her passport, and so on. She also has some personal social media accounts
in a separate qube for keeping up with family members and friends from
school.
When she finishes her work for a given client, Alice sends off her
deliverables, [backs up](/doc/how-to-back-up-restore-and-migrate/) the qubes
containing the work for that client, and deletes them from her system. If she
ever needs those qubes again or just wants to reference them, she can easily
restore them from her backup, and the internal state of each one will be
exactly as it was when she finished that project.
## Bob, the investigative journalist
As part of his research and reporting, Bob is frequently forced to interact
with suspicious files, often from anonymous sources. For example, he may
receive an email with an attachment that claims to be a tip about a story he's
working on. Of course, he knows that it could just as easily be malware
intended to infect his computer. Qubes OS is essential for Bob, since it allows
him to handle all this suspicious data securely, keeping it compartmentalized
so that it doesn't risk infecting the rest of his machine.
Bob isn't a super technical guy. He prefers to keep his tools simple so he can
focus on what's important to him: uncovering the truth, exposing the guilty,
exonerating the innocent, and shining light on the dark corners of society. His
mind doesn't naturally gravitate to the technical details of how his computer
works, but he's aware that people are getting hacked all the time and that the
nature of his work might make him a target. He wants to protect his sources,
his colleagues, his family, and himself; and he understands that computer
security is an important part of that. He has a Qubes laptop that he uses only
for work, which contains:
[![A diagram of Bob's system](/attachment/doc/howto_use_qubes_bob.png)](/attachment/doc/howto_use_qubes_bob.png)
- **One offline qube for writing.** It runs only LibreOffice Writer. This is
where Bob does all of his writing. This window is usually open side-by-side
with another window containing research or material from a source.
- **Multiple email qubes.** One is for receiving emails from the general
public. Another is for emailing his editor and colleagues. Both are based on
a [minimal template](/doc/templates/minimal/) with Thunderbird installed.
He's configured both to open all attachments in
[disposables](/doc/how-to-use-disposables/) that are offline in case an
attachment contains a beacon that tries to phone home.
- **Whonix qubes.** He has the standard `sys-whonix` service qube for providing
Torified network access, and he uses disposable `anon-workstation` app qubes
for using Tor Browser to do research on stories he's writing. Since the topic
is often of a sensitive nature and might implicate powerful individuals, it's
important that he be able to conduct this research with a degree of
anonymity. He doesn't want the subjects of his investigation to know that
he's looking into them. He also doesn't want his network requests being
traced back to his work or home IP addresses. Whonix helps with both of these
concerns. He also has another Whonix-based disposable template for receiving
tips anonymously via Tor, since some high-risk whistleblowers he's interacted
with have said that they can't take a chance with any other form of
communication.
- **Two qubes for
[Signal](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md).**
Bob has two Signal app qubes (both on the same template in which the Signal
desktop app is installed). One is linked to his own mobile number for
communicating with co-workers and other known, trusted contacts. The other is
a public number that serves as an additional way for sources to reach him
confidentially. This is especially useful for individuals who don't use Tor
but for whom unencrypted communication could be dangerous.
- **Several data vaults.** When someone sends Bob material that turns out to be
useful, or when he comes across useful material while doing his own research,
he stores a copy in a completely offline, network-isolated vault qube. Most
of these files are PDFs and images, though some are audio files, videos, and
text files. Since most of them are from unknown or untrusted sources, Bob
isn't sure if it would be safe to put them all in the same vault, so he makes
different vaults (usually one for each story or topic) just in case. This has
the side benefit of helping to keep things organized.
- **A [VPN
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md)
and associated qubes for accessing work resources.** The servers at work can
only be accessed from the organization's network, so Bob has certain qubes
that are connected to a VPN qube so that he can upload his work and access
anything he needs on the local network when he's not physically there.
- **A password manager vault.** Bob stores all of his login credentials in the
default password manager that came with his offline vault qube. He [securely
copies and pastes](/doc/how-to-copy-and-paste-text/) them into other qubes as
needed.
A colleague helped Bob set up his Qubes system initially and showed him how to
use it. Since Bob's workflow is pretty consistent and straightforward, the way
his qubes are organized doesn't change much, and this is just fine by him. His
colleague told him to remember a few simple rules: Don't copy or move
[text](/doc/how-to-copy-and-paste-text/) or
[files](/doc/how-to-copy-and-move-files/) from less trusted to more trusted
qubes; [update](/doc/how-to-update/) your system when prompted; and make
regular [backups](/doc/how-to-back-up-restore-and-migrate/). Bob doesn't have
the need to try out new software or tweak any settings, so he can do everything
he needs to do on a daily basis without having to interact with the command
line.
## Carol, the investor
Carol works hard and lives below her means so that she can save money and
invest it for her future. She hopes to become financially independent and maybe
even retire early someday, and she's decided that her best bet for achieving
this is by investing for the long term and allow compounding to do its work.
However, after doing some research into her country's consumer financial
protection laws, she learned that there's no legal guarantee that customers
will be made whole in the event of theft or fraud. The various insurance and
protection organizations only guarantee recovery in the case of a financial
institution *failing*, which is quite different from an individual customer
being hacked. Moreover, even though many financial institutions have their own
cybercrime policies, rarely, if ever, do they explicitly guarantee
reimbursement in the event that a *customer* gets hacked (rather than the
institution itself).
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
Carol looked into how thieves might actually try to steal her hard-earned
wealth and was surprised to learn that they have all sorts of ploys that she
had never even considered. For example, she had assumed that any theft would,
at the bare minimum, have to involve transferring money out of her account.
That seems like a safe assumption. But then she read about "pump and dump"
attacks, where thieves buy up some penny stock, hack into innocent people's
brokerage accounts, then use the victims' funds to buy that same penny stock,
"pumping" up its price so that the thieves can "dump" their shares on the
market, leaving the victims with worthless shares. No money is ever
transferred into or out of the victims' account; it's just used to buy and
sell securities. So, all the safeguards preventing new bank accounts from
being added or requiring extra approval for outbound transfers do nothing to
protect victims' funds in cases like these. And this is just one example!
Carol realized that she couldn't assume that existing safeguards against
specific, known attacks were enough. She had to think about security at a
more fundamental level and design it into her digital life from the ground
up.
</div>
After learning about all this, Carol decided that it was ultimately up to her
to take care of her own cybersecurity. She couldn't rely on anyone else to do
it for her. Sure, most people just use regular consumer tech and will probably
end up fine, but, she reminded herself, most people also don't have as much to
lose. It's not a risk that she was willing to take with her future, especially
knowing that there's probably no government bailout waiting for her and that
all the brokerage firms' vaguely reassuring marketing language about
cybersecurity isn't legally binding. So, Carol started reading more about
computer security and eventually stumbled upon Qubes OS after searching the web
for "most secure operating system." She read about how it's designed and why.
Although she didn't immediately understand all of the technical details, the
fundamental principle of [security-by-compartmentalization](/doc/architecture/)
made intuitive sense to her, and the more she learned about the technical
aspects, the more she realized that this is what she'd been looking for. Today,
her setup looks like this:
[![A diagram of Carol's system](/attachment/doc/howto_use_qubes_carol.png)](/attachment/doc/howto_use_qubes_carol.png)
- **One qube for each investment firm and bank.** Carol has a few different
retirement accounts, brokerage accounts, and bank accounts. She treats each
qube like a "secure terminal" for accessing only that one institution's
website. She makes her transactions and saves any statements and
confirmations she downloads in that qube. She uses the [Qubes
firewall](/doc/firewall/) to enable access only to that institution's website
in that qube so that she doesn't accidentally visit any others. Since most of
what she does involves using websites and PDFs, most of Carol's app qubes are
based on a [minimal template](/doc/templates/minimal/) with just a web
browser (which doubles as a PDF viewer) and a file manager installed.
- **One qube for all her credit card accounts.** Carol started to make a
separate qube for each credit card account but ultimately decided against it.
For one thing, the consumer protections for credit card fraud in her country
are much better than for losing assets to theft or fraud in a bank or
brokerage account, so the security risk isn't as high. Second, there's
actually not a whole lot that an attacker could do with access to her credit
cards' online accounts or her old credit card statements, since online access
to these generally doesn't allow spending or withdrawing any money. So, even
the worst case scenario here wouldn't be catastrophic, unlike with her bank
and brokerage accounts. Third, she's not too worried about any of her credit
card company websites being used to attack each other or her qube. (As long as
it's contained to a single qube, she's fine with that level of risk.) Last,
but not least: She has way too many credit cards! While Carol is very frugal,
she likes to collect the sign-up bonuses that are offered for opening new
cards, so she's accumulated quite a few of them. (However, she's always
careful to pay off her balance each month, so she never pays interest. She's
also pretty disciplined about only spending what she would have spent
*anyway* and not being tempted to spend more just to meet a spending
requirement or because she can.) At any rate, Carol has decided that the tiny
benefit she stands to gain from having a separate qube for every credit card
website wouldn't be worth the hassle of having to manage so many extra qubes.
- **A qube for credit monitoring, credit reports, and credit history
services.** Carol has worked hard to build up a good credit score, and she's
concerned about identity theft, so she has one qube dedicated to managing her
free credit monitoring services and downloading her free annual credit
reports.
- **Two qubes for taxes.** Carol has a [Windows
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md)
for running her Windows-only tax software. She also has an offline vault
where she stores all of her tax-related forms and documents, organized by
year.
- **A qube for financial planning and tracking.** Carol loves spreadsheets, so
this offline qube is where she maintains a master spreadsheet to track all of
her investments and her savings rate. She also keeps her budgeting
spreadsheet, insurance spreadsheet, and written investment policy statement
here. This qube is based on a template with some additional productivity
software, like LibreOffice and Gnumeric (so that Carol can run her own Monte
Carlo simulations).
- **Various email qubes.** Carol likes to have one email qube for her most
important financial accounts; a separate one for her credit cards accounts,
online shopping accounts, and insurance companies; and another one for
personal email. They're all based on the same template with Thunderbird
installed.
- **A password manager vault.** A network-isolated qube where Carol stores all
of her account usernames and passwords in KeePassXC. She uses the [Qubes
global clipboard](/doc/how-to-copy-and-paste-text/) to copy and paste them
into her other qubes when she needs to log into her accounts.
### Bonus: Carol explores new financial technology
The vast majority of Carol's assets are in broad-based, low-cost,
passively-managed indexed funds. Lately, however, she's started getting
interested in cryptocurrency. She's still committed to staying the course with
her tried-and-true investments, and she's always been skeptical of new asset
classes, especially those that don't generate cash flows or that often seem to
be associated with scams or wild speculation. However, she finds the ability to
self-custody a portion of her assets appealing from a long-term risk management
perspective, particularly as a hedge against certain types of political risk.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
Some of Carol's friends warned her that cryptocurrency is extremely volatile
and that hacking and theft are common occurrences. Carol agreed and reassured
them that she's educated herself about the risks and will make sure she never
invests more than she can afford to lose.
</div>
Carol has added the following to her Qubes setup:
- **A standalone qube for running Bitcoin Core and an offline wallet vault.**
Carol finds the design and security properties of Bitcoin very interesting,
so she's experimenting with running a full node. She also created a
network-isolated vault in order to try running a copy of Bitcoin Core
completely offline as a "cold storage" wallet. She's still trying to figure
out how this compares to an actual hardware wallet, paper wallet, or
physically air-gapped machine, but she's figures they all have different
security properties. She also recently heard about using [Electrum as a
"split" wallet in
Qubes](https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md)
and is interested in exploring that further.
- **Whonix qubes.** Carol read somewhere that Bitcoin nodes should be run over
Tor for privacy and security. She found it very convenient that Whonix is
already integrated into Qubes, so she simply set her Bitcoin Core "full node"
qube to use `sys-whonix` as its networking qube.
- **Various qubes for DeFi and web3.** Carol has also started getting into DeFi
(decentralized finance) and web3 on Ethereum and other smart contract
blockchains, so a friend recommended that she get a Ledger hardware wallet.
She downloaded the Ledger Live software in an app qube and [set up her system
to recognize the
Ledger](https://www.kicksecure.com/wiki/Ledger_Hardware_Wallet). She can now
start her [USB qube](/doc/usb-qubes/), plug her Ledger into it into a USB
port, [use the Qubes Devices widget to attach it](/doc/how-to-use-devices/)
to her Ledger Live qube, and from there she can interact with the software.
She has a separate qube with the Metamask extension installed in a web
browser. She can also use the Qubes Devices widget to attach her Ledger to
this qube so she can use Metamask in conjunction with her Ledger to interact
with smart contracts and decentralized exchanges.
- **Various qubes for research and centralized exchanges.** Carol uses these
when she wants to check block explorer websites, coin listing and market cap
sites, aggregation tools, or just to see what the latest buzz is on Crypto
Twitter.
Carol makes sure to back up all of her qubes that contain important account
statements, confirmations, spreadsheets, cryptocurrency wallets, and her
password manager vault. If she has extra storage space, she'll also back up her
templates and even her Bitcoin full node qube, but she'll skip them if she
doesn't have time or space, since she knows she can always recreate them again
later and download what she needs from the Internet.
## Conclusion
The characters we've met today may be fictional, but they represent the needs
of real users like you. You may find that your own needs overlap with more than
one of them, in which case you may find it useful to model certain subsets of
your overall Qubes system on different examples. You probably also noticed that
there are commonalities among them. Most people need to use email, for example,
so most people will need at least one email qube and a suitable template to
base it on. But not everyone will need [Split GPG](/doc/split-gpg/), and not
everyone will want to use the same email client. On the other hand, almost
everyone will need a password manager, and it pretty much always makes sense to
keep it in an offline, network-isolated vault.
<div class="alert alert-info" role="alert">
<i class="fa fa-circle-info"></i>
As you gain experience with Qubes, you may find yourself disagreeing with
some of the decisions our fictional friends made. That's okay! There are many
different ways to organize a Qubes system, and the most important criterion
is that it serves the needs of its owner. Since everyone's needs are
different, it's perfectly normal to find yourself doing things a bit
differently. Nonetheless, there are some general principles that almost all
users find helpful, especially when they're first starting out.
</div>
As you're designing your own Qubes system, keep in mind some of the following
lessons from our case studies:
- **You'll probably change your mind as you go.** You'll realize that one qube
should really be split into two, or you'll realize that it doesn't really
make sense for two qubes to be separate and that they should instead be
merged into one. That's okay. Qubes OS supports your ability to adapt and
make changes as you go. Try to maintain a flexible mindset. Things will
eventually settle down, and you'll find your groove. Changes to the way you
organize your qubes will become less drastic and less frequent over time.
- **[Make frequent backups.](/doc/how-to-back-up-restore-and-migrate/)** Losing
data is never fun, whether it's from an accidental deletion, a system crash,
buggy software, or a hardware failure. By getting into the habit of making
frequent backups now, you'll save yourself from a lot of pain in the future.
Many people never take backups seriously until they suffer catastrophic data
loss. That's human nature. If you've experienced that before, then you know
the pain. Resolve now never to let it happen again. If you've never
experienced it, count yourself lucky and try to learn from the hard-won
experience of others. Keeping good backups also allows you to be a bit more
free with reorganizations. You can delete qubes that you think you won't need
anymore without having to worry that you might need them again someday, since
you know you can always restore them from a backup.
- **Think about which programs you want to run and where you want to store
data.** In some cases, it makes sense to run programs and store data in the
same qube, for example, if the data is generated by that program. In other
cases, it makes sense to have qubes that are exclusively for storing data
(e.g., offline data storage vaults) and other qubes that are exclusively for
running programs (e.g., web browser-only qubes). Remember that when you make
backups, it's only essential to back up data that can't be replaced. This can
allow you to achieve minimal backups that are quite small compared to the
total size of your installation. Templates, service qubes, and qubes that are
used exclusively for running programs and that contain no data don't
necessarily have to be backed up as long as you're confident that you can
recreate them if needed. This is why it's a good practice to keep notes on
which packages you installed in which templates and which customizations and
configurations you made. Then you can refer to your notes the next time you
need to recreate those qubes. Of course, backing up everything is not a bad
idea either. It may require a bit more time and disk space upfront, but for
some people, it can be just as important as backing up their irreplaceable
data. If your system is mission-critical, and you can't afford more than a
certain amount of downtime, then by all means, back everything up!
- **Introspect on your own behavior.** For example, if you find yourself
wanting to find some way to get two qubes to share the same storage space,
then this is probably a sign that those two qubes shouldn't be separate in
the first place. Sharing storage with each other largely breaks down the
secure wall between them, making the separation somewhat pointless. But you
probably had a good reason for wanting to make them two separate qubes
instead of one to begin with. What exactly was that reason? If it has to do
with security, then why are you okay with them freely sharing data that could
allow one to infect the other? If you're sure sharing the data wouldn't cause
one to infect the other, then what's the security rationale for keeping them
separate? By critically examining your own thought process in this way, you
can uncover inconsistencies and contradictions that allow you to better
refine your system, resulting in a more logical organization that serves your
needs better and better over time.
- **Don't assume that just because *you* can't find a way to attack your
system, an adversary wouldn't be able to.** When you're thinking about
whether it's a good idea to combine different activities or data in a single
qube, for example, you might think, "Well, I can't really see how these pose
a risk to each other." The problem is that we often miss attack vectors that
sophisticated adversaries spot and can use against us. After all, most people
don't think that using a conventional monolithic operating system is risky,
when in reality their entire digital life can be taken down in one fell
swoop. That's why a good rule of thumb is: When in doubt, compartmentalize.
- **But remember that compartmentalization --- like everything else --- can be
taken to an extreme.** The appropriate amount depends on your temperament,
time, patience, experience, risk tolerance, and expertise. In short, there
can be such a thing as *too much* compartmentalization! You also have to be
able to actually *use* your computer efficiently to do the things you need to
do. For example, if you immediately try to jump into doing everything in
[disposables](/doc/how-to-use-disposables/) and find yourself constantly
losing work (e.g., because you forget to transfer it out before the
disposable self-destructs), then that's a big problem! Your extra
self-imposed security measures are interfering with the very thing they're
designed to protect. At times like these, take a deep breath and remember
that you've already reaped the vast majority of the security benefit simply
by using Qubes OS in the first place and performing basic
compartmentalization (e.g., no random web browsing in templates). Each
further step of hardening and compartmentalization beyond that represents an
incremental gain with diminishing marginal utility. Try not to allow the
perfect to be the enemy of the good!

0
user/templates/how-to-reinstall-a-template.md → user/how-to-guides/how-to-reinstall-a-template.md
View file

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

@ -8,27 +8,9 @@ ref: 200
title: How to update
---
*This page is about updating your system while staying on the same [supported
version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead
looking to upgrade from your current version of Qubes OS to a newer version,
see the [Upgrade Guides](/doc/upgrade/).*
*This page is about updating your system while staying on the same [supported version of Qubes OS](/doc/supported-releases/#qubes-os). If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see [Upgrade guides](/doc/upgrade/).*
## Security updates
Security updates are an extremely important part of keeping your Qubes
installation secure. When there is an important security issue, we will issue a
[Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security
Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new
QSB and follow any user instructions it contains. Most of the time, simply
[updating your system normally](#routine-updates) will be sufficient to obtain
security updates. However, in some cases, special action may be required on
your part, which will be explained in the QSB.
## Routine updates
It is important to keep your Qubes OS system up-to-date to ensure you have the
latest [security updates](#security-updates), as well as the latest
non-security enhancements and bug fixes.
It is important to keep your Qubes OS system up-to-date to ensure you have the latest security updates, as well as the latest non-security enhancements and bug fixes.
Fully updating your Qubes OS system means updating:
@ -36,116 +18,71 @@ Fully updating your Qubes OS system means updating:
- [templates](/doc/glossary/#template)
- [standalones](/doc/glossary/#standalone) (if you have any)
You can accomplish this using the **Qubes Update** tool. (**Warning:** This
tool is currently affected by bug
[#6585](https://github.com/QubesOS/qubes-issues/issues/6585). See below for a
mitigation.)
## Security updates
[![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a [Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new QSB and follow any user instructions it contains. Most of the time, simply updating your system normally, as described below, will be sufficient to obtain security updates. However, in some cases, special action may be required on your part, which will be explained in the QSB.
By default, the Qubes Update tool will appear as an icon in the Notification
Area when updates are available.
## Checking for updates
By default, the **Qubes Update** tool will appear as an icon in the Notification Area when updates are available.
[![Qube Updates Available](/attachment/doc/r4.0-qube-updates-available.png)](/attachment/doc/r4.0-qube-updates-available.png)
However, you can also start the tool manually by selecting it in the
Applications Menu under "System Tools." Even if no updates have been detected,
you can use this tool to check for updates manually at any time by selecting
"Enable updates for qubes without known available updates," then selecting all
desired items from the list and clicking "Next."
However, you can also start the tool manually by selecting it in the Applications Menu under "Qubes Tools." Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting "Enable updates for qubes without known available updates," then selecting all desired items from the list and clicking "Next."
<div class="alert alert-info" role="alert">
<i class="fa fa-question-circle"></i>
For information about how templates download updates, please see <a href="/doc/how-to-install-software/#why-dont-templates-have-network-access">Why don't templates have network access?</a> and the <a href="/doc/how-to-install-software/#updates-proxy">Updates proxy</a>.
</div>
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. If updates are available, you will receive a notification as described above. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. Therefore, you should regularly update such templates manually instead.
## Installing updates
The standard way to install updates is with the **Qubes Update** tool. (However, you can also perform the same action via the [command-line interface](#command-line-interface).)
[![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)
Simply follow the on-screen instructions, and the tool will download and install all available updates for you. Note that if you are downloading updates over Tor (`sys-whonix`), this can take a very long time, especially if there are a lot of updates available.
## Restarting after updating
Certain updates require certain components to be restarted in order for the updates to take effect:
- QSBs may instruct you to restart certain components after installing updates.
- Dom0 should be restarted after all **Xen** and **kernel** updates.
- On Intel systems, dom0 should be restarted after all `microcode_ctl` updates.
- On AMD systems, dom0 should be restarted after all `linux-firmware` updates.
- After updating a template, first shut down the template, then restart all running qubes based on that template.
## AEM resealing after updating
If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal" after certain updates. It's common for QSBs to contain instructions to this effect. See the relevant QSB and the [AEM `README`](https://github.com/QubesOS/qubes-antievilmaid/blob/main/README) for details.
## Command-line interface
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Updating <em>exclusively</em> with direct commands such as
<code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt
update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS
update security measures. Instead, we strongly recommend <em>first</em> using
the <b>Qubes Update</b> tool or its command-line equivalents, as described
below, <em>then</em> using the direct commands for confirmation (see <a
href="https://github.com/QubesOS/qubes-issues/issues/6585">#6585</a> and <a
href="https://github.com/QubesOS/qubes-posts/pull/79">PR #79</a>). (By
contrast, <a href="/doc/how-to-install-software/">installing</a> packages
using direct package manager commands is fine.)
<b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
</div>
As a temporary mitigation until
[#6585](https://github.com/QubesOS/qubes-issues/issues/6585) is fixed, the
following update sequence is recommended (see
[PR #79](https://github.com/QubesOS/qubes-posts/pull/79)
for explanation and discussion):
Advanced users may wish to perform updates via the command-line interface. The recommended way to do this is by applying the following two Salt states. **Applying these two Salt states is the same as updating via the Qubes Update tool.**
1. Update dom0 with Salt.
2. Update dom0 by direct command.
3. Update templates and standalones with Salt.
4. Update templates and standalones by direct commands.
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
Example using only the command line (all commands with `sudo` or as root):
In your update qube, a terminal window opens that displays the progress of operations and output as it is logged. At the end of the process, logs are sent back to dom0. You answer any yes/no prompts in your dom0 terminal window.
1. In dom0: `qubesctl --show-output state.sls update.qubes-dom0`
2. In dom0: `qubes-dom0-update --clean -y`
3. In dom0: `qubesctl --show-output --skip-dom0 --templates state.sls
update.qubes-vm`
4. In dom0: `qubesctl --show-output --skip-dom0 --standalones state.sls
update.qubes-vm`
5. In every Fedora template and standalone: `dnf -y --refresh upgrade`
6. In every Debian template and standalone: `apt-get clean && apt-get -y update
&& apt-get -y dist-upgrade && apt-get clean`
### Qubes 4.0
Advanced users may wish to perform updates via the command-line interface. The
recommended way to do this is by using the command-line equivalents of the
**Qubes Update** tool.
There are two Salt formulae and two corresponding `qubesctl` commands:
- [`update.qubes-dom0`](/doc/salt/#updatequbes-dom0)
- [`update.qubes-vm`](/doc/salt/#updatequbes-vm)
Advanced users may also be interested in learning [how to enable the
testing repos](/doc/testing/).
### Qubes 4.1
The recommendation, commands, and Salt formulae from 4.0 remain the same.
Command-line updates in dom0 behave differently in 4.1. In your update qube, a
terminal window opens that displays the progress of operations and output as it
is logged. At the end of the process, logs are sent back to dom0. You answer any
yes/no prompts in your dom0 terminal window.
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
## Upgrading to avoid EOL
The above covers updating *within* a given operating system (OS) release.
Eventually, however, most OS releases will reach **end-of-life (EOL)**, after
which point they will no longer be supported. This applies to Qubes OS itself
as well as OSes used in [templates](/doc/templates/) (and
[standalones](/doc/standalones-and-hvms/), if you have any).
The above covers updating *within* a given operating system (OS) release. Eventually, however, most OS releases will reach **end-of-life (EOL)**, after which point they will no longer be supported. This applies to Qubes OS itself as well as OSes used in [templates](/doc/templates/) (and [standalones](/doc/standalones-and-hvms/), if you have any).
**It's very important that you use only supported releases so that you continue
to receive security updates.** This means that you *must* periodically upgrade
Qubes OS and your templates before they reach EOL. You can always see which
versions of Qubes OS and select templates are supported on the [Supported
Versions](/doc/supported-releases/) page.
**It's very important that you use only supported releases so that you continue to receive security updates.** This means that you *must* periodically upgrade Qubes OS and your templates before they reach EOL. You can always see which versions of Qubes OS and select templates are supported on [Supported releases](/doc/supported-releases/).
In the case of Qubes OS itself, we will make an
[announcement](/news/categories/#releases) when a supported Qubes OS release is
approaching EOL and another when it has actually reached EOL, and we will
provide [instructions for upgrading to the next stable supported Qubes OS
release](/doc/upgrade/).
In the case of Qubes OS itself, we will make an [announcement](/news/categories/#releases) when a supported Qubes OS release is approaching EOL and another when it has actually reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
Periodic upgrades are also important for templates. For example, you might be
using a [Fedora template](/doc/templates/fedora/). The [Fedora
Project](https://getfedora.org/) is independent of the Qubes OS Project. They
set their own
[schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule)
for when each Fedora release reaches EOL. You can always find out when an OS
reaches EOL from the upstream project that maintains it. We also pass along any
EOL notices we receive for official template OSes as a convenience to Qubes
users (see [Supported Versions:
Templates](/doc/supported-releases/#templates)).
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
The one exception to all this is the specific release used for dom0 (not to be
confused with Qubes OS as a whole), which [doesn't have to be
upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).

100
user/how-to-guides/how-to-use-disposables.md
View file

@ -14,14 +14,9 @@ ref: 203
title: How to use disposables
---
A [disposable](/doc/glossary/#disposable) is a lightweight [qube](/doc/glossary/#qube) that can be created quickly and will self-destruct when closed.
Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
A [disposable](/doc/glossary/#disposable) is a lightweight [qube](/doc/glossary/#qube) that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file.
Changes made to a file opened in a disposable are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
Disposables can be launched either directly from dom0's Start Menu or terminal window, or from within app qubes.
While running, disposables will appear in Qubes VM Manager with the name `disp####`.
From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file. Changes made to a file opened in a disposable are passed back to the originating qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0's app menu or terminal window, or from within app qubes. Disposables are generated with names like `disp####`, where `####` is random number.
[![disposablevm-example.png](/attachment/doc/disposablevm-example.png)](/attachment/doc/disposablevm-example.png)
@ -29,89 +24,66 @@ This diagram provides a general example of how disposables can be used to safely
## Security
If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised.
In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default disposable template on a trusted template.
If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised. In particular, the *default* disposable template is important because it is used by the "Open in disposable" feature. This means that it will have access to everything that you open with this feature. For this reason, it is strongly recommended that you base the default disposable template on a trusted template.
### Disposables and Local Forensics
At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## Disposables and Networking
Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template).
R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template). R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default disposable template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default template).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
On a fresh installation of Qubes, the default disposable template is called `fedora-X-dvm` or `debian-X-dvm` (where `X` is a release number). If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
You can set any app qube to have the ability to act as a disposable template with:
```
qvm-prefs <vmname> template_for_dispvms True
qvm-prefs <APP_QUBE> template_for_dispvms True
```
The default system wide disposable template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
The default system wide disposable template can be changed with `qubes-prefs default_dispvm`. By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that VM.
This can also be changed from the command line with:
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the "Advanced" tab. Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
```
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
```
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default. You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
NetVM and firewall rules for disposable templates can be set as they can for a normal VM.
By default a disposable will inherit the NetVM and firewall settings of the disposable template on which it is based.
This is a change in behaviour from R3.2, where disposables would inherit the settings of the app qube from which they were launched.
Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based.
For example, if an app qube uses sys-net as its NetVM, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its NetVM.
Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior from R3.2, where disposables would inherit the settings of the app qube from which they were launched. Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based. For example, if an app qube uses sys-net as its net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
**Warning:** The opposite is also true.
This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside anon-whonix will result in the disposable using sys-net.
**Warning:** The opposite is also true. This means if you have changed `anon-whonix`'s `default_dispvm` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside `anon-whonix` will result in the disposable using `sys-net`.
A disposable launched from the Start Menu inherits the NetVM and firewall settings of the disposable template on which it is based.
Note that changing the "NetVM" setting for the system default disposable template *does* affect the NetVM of disposables launched from the Start Menu.
Different disposable templates with individual NetVM settings can be added to the Start Menu.
A disposable launched from the app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
**Important Notes:**
Some disposable templates will automatically create a menu item to launch a disposable, if you do not see an entry and want to add one please use the command:
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
```
qvm-features <DISPOSABLE> appmenus-dispvm 1
qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
```
To launch a disposable template from the command line, in dom0 please type the following:
To launch a disposable template from the command line, execute the following command in dom0:
```
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+NameOfApp
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
```
## Opening a file in a disposable via GUI
In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a disposable created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole disposable will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable". Wait a few seconds and the default application for this file type should appear displaying the file content. This app is running in its own dedicated qube -- a disposable created for the purpose of viewing or editing this very file. Once you close the viewing application the whole disposable will be destroyed. If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
![r4.0-open-in-dispvm-1.png](/attachment/doc/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/doc/r4.0-open-in-dispvm-2.png)
![r4.0-open-in-dispvm-1.png](/attachment/doc/r4.0-open-in-dispvm-1.png)
![r4.0-open-in-dispvm-2.png](/attachment/doc/r4.0-open-in-dispvm-2.png)
## Opening a fresh web browser instance in a new disposable
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable.
This can be done easily using the Start Menu: just go to **Application Menu -\> Disposable -\> Disposable:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole disposable will be destroyed.
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to **Application Menu -> Disposable -> Disposable: Firefox web browser**. Wait a few seconds until a web browser starts. Once you close the viewing application the whole disposable will be destroyed.
![r4.0-open-in-dispvm-3.png](/attachment/doc/r4.0-open-in-dispvm-3.png)
@ -140,10 +112,7 @@ This will _not_ override the internal handling of PDF documents in Web browsers.
## Starting an arbitrary program in a disposable from an app qube
Sometimes it can be useful to start an arbitrary program in a disposable.
The disposable will stay running so long as the process which started the disposable has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
Starting an arbitrary program can be done from an app qube by running
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)). Starting an arbitrary program can be done from an app qube by running
~~~
[user@vault ~]$ qvm-run '@dispvm' xterm
@ -153,24 +122,17 @@ The created disposable can be accessed via other tools (such as `qvm-copy-to-vm`
## Starting an arbitrary application in a disposable via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks.
The disposable will stay running so long as the process which started the disposable has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
It is possible to start an arbitrary application in a disposable directly from dom0 by running:
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
~~~
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
~~~
The label color will be inherited from `<DISPOSABLE_TEMPLATE>`.
(The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
The label color will be inherited from `<DISPOSABLE_TEMPLATE>`. (The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
### Opening a link in a disposable based on a non-default disposable template from a qube
Suppose that the default disposable template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in disposables.
Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template.
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
Suppose that the default disposable template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home). However, sometimes you want to open email links in disposables. Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
@ -187,16 +149,14 @@ In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/pol
~~~
This line means:
- FROM: Any VM
- FROM: Any qube
- TO: A disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
In other words, any VM will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
In other words, any qube will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
More information about RPC policies for disposables can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing disposables
You can change the template used to generate the disposables, and change settings used in the disposable savefile.
These changes will be reflected in every new disposable based on that template.
Full instructions can be found [here](/doc/disposable-customization/).
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found [here](/doc/disposable-customization/).

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

@ -24,6 +24,7 @@ Please make sure you carefully read and understand the **[security consideration
Unlike other devices ([USB](/doc/how-to-use-usb-devices/), [block](/doc/how-to-use-block-storage-devices/), mic), PCI devices need to be attached on VM-bootup.
Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported.
Moreover, PCI devices can be attached only to VMs running in certain virtualization modes. See [FAQ: Which virtualization modes do VMs use?](/faq/#which-virtualization-modes-do-vms-use)
The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install.
While this covers most use cases, there are some occasions when you may want to manually attach one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually attach.

8
user/reference/glossary.md
View file

@ -128,9 +128,6 @@ example, it is common for the net qube of an [app qube](#app-qube) to be the
[service qube](#service-qube) `sys-firewall`, which in turn uses `sys-net` as
its net qube.
* If a qube does not have a net qube (i.e., its `netvm` is set to `None`), then
that qube is offline. It is disconnected from all networking.
* The name `netvm` derives from "Networking Virtual Machine." Before Qubes 4.0,
there was a type of [service qube](#service-qube) called a "NetVM." The name
of the `netvm` property is a holdover from that era.
@ -144,11 +141,12 @@ still be called "qubes."
* **Important:** The term "qube" is a common noun and should follow the
capitalization rules of common nouns. For example, "I have three qubes" is
correct," while "I have three Qubes" is incorrect.
correct, while "I have three Qubes" is incorrect.
* Note that starting a sentence with the plural of "qube" (i.e., "Qubes...")
can be ambiguous, since it may not be clear whether the referent is a
plurality of qubes or [Qubes OS](#qubes-os).
plurality of qubes or [Qubes OS](#qubes-os). You may wish to rephrase
sentences in order to avoid this ambiguity.
* Example usage: "In Qubes OS, you do your banking in your 'banking' qube and
your web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube

65
user/security-in-qubes/firewall.md
View file

@ -145,10 +145,10 @@ In the case where a specific TCP port needs to be exposed from a qubes to anothe
Consider the following example. `mytcp-service` qube has a TCP service running on port `444` and `untrusted` qube needs to access this service.
- In dom0, add the following to `/etc/qubes-rpc/policy/qubes.ConnectTCP`:
- In dom0, add the following to `/etc/qubes/policy.d/30-user-networking.policy`: (it could be `another-other-name.policy` -- just remember to keep it consistent)
~~~
untrusted @default allow,target=mytcp-service
qubes.ConnectTCP * untrusted @default allow target=mytcp-service
~~~
- In untrusted, use the Qubes tool `qvm-connect-tcp`:
@ -171,13 +171,13 @@ which means to use default local port of `unstrusted` as the same of the remote
**2. Binding remote port on another local port**
Consider now the case where someone prefers to specify the destination qube and use another port in untrusted,for example `10044`. Instead of previous case, add
Consider now the case where someone prefers to specify the destination qube and use another port in untrusted, for example `10044`. Instead of previous case, add
~~~
untrusted mytcp-service allow
qubes.ConnectTCP * untrusted mytcp-service allow
~~~
in `/etc/qubes-rpc/policy/qubes.ConnectTCP` and in untrusted, use the tool as follow:
in `/etc/qubes/policy.d/30-user-networking.policy` and in untrusted, use the tool as follow:
~~~
[user@untrusted #]$ qvm-connect-tcp 10444:mytcp-service:444
@ -187,10 +187,10 @@ The service of `mytcp-service` running on port `444` is now accessible in `untru
**3. Binding to different qubes using RPC policies**
One can go further than the previous examples by redirecting different ports to different qubes. For example, let assume that another qube `mytcp-service-bis` with a TCP service is running on port `445`. If someone wants `untrusted` to be able to reach this service but port `445` is reserved to `mytcp-service-bis` then, in dom0, add the following to `/etc/qubes-rpc/policy/qubes.ConnectTCP+445`:
One can go further than the previous examples by redirecting different ports to different qubes. For example, let assume that another qube `mytcp-service-bis` with a TCP service is running on port `445`. If someone wants `untrusted` to be able to reach this service but port `445` is reserved to `mytcp-service-bis` then, in dom0, add the following to `/etc/qubes/policy.d/30-user-networking.policy`:
~~~
untrusted @default allow,target=mytcp-service-bis
qubes.ConnectTCP +445 untrusted @default allow target=mytcp-service-bis
~~~
In that case, calling `qvm-connect-tcp` like previous examples, will still bind TCP port `444` of `mytcp-service` to `untrusted` but now, calling it with port `445`
@ -268,22 +268,24 @@ Note the IP addresses you will need.
**2. Route packets from the outside world to the FirewallVM**
For the following example, we assume that the physical interface eth0 in sys-net has the IP address 192.168.x.y and that the IP address of sys-firewall is 10.137.1.z.
In the sys-net VM's Terminal, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.x -j DNAT --to-destination 10.137.1.x
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT --to-destination 10.137.1.z
```
Code the appropriate new filtering firewall rule to allow new connections for the service
```
iptables -I FORWARD 2 -i eth0 -d 10.137.1.x -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
> If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
> In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain.
`nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.0.x tcp dport 443 ct state new counter accept`
`nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept`
Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2)
@ -301,7 +303,7 @@ nft list table ip qubes-firewall
Send a test packet by trying to connect to the service from an external device
```
telnet 192.168.x.x 443
telnet 192.168.x.y 443
```
Once you have confirmed that the counters increase, store these command in `/rw/config/rc.local` so they get set on sys-net start-up
@ -320,8 +322,8 @@ sudo nano /rw/config/rc.local
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
# Add a natting rule if it did not exit (to avoid cluter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.1.x
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.1.z
fi
@ -330,7 +332,7 @@ fi
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.0.x -j MY-HTTPS
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j MY-HTTPS
fi
@ -340,7 +342,7 @@ fi
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exit (to avoid cluter if script executed multiple times)
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
fi
@ -349,7 +351,7 @@ fi
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 2 -d 10.137.1.x -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
iptables -w -I FORWARD 2 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~
@ -364,23 +366,25 @@ fi
if nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.0.x tcp dport 443 ct state new counter accept
nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept
fi
~~~
**3. Route packets from the FirewallVM to the VM**
For the following example, we use the fact that the physical interface of sys-firewall, facing sys-net, is eth0. Furthermore, we assume that the target VM running the web server has the IP address 10.137.0.xx and that the IP address of sys-firewall is 10.137.1.z.
In the sys-firewall VM's Terminal, code a natting firewall rule to route traffic on its outside interface for the service to the qube
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j DNAT --to-destination 10.137.2.y
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j DNAT --to-destination 10.137.0.xx
```
Code the appropriate new filtering firewall rule to allow new connections for the service
```
iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.2.y -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
```
> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
@ -388,7 +392,7 @@ iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.2.y -p tcp --dport 443
> Note: On Qubes R4
```
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.y tcp dport 443 ct state new counter accept
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
```
Once you have confirmed that the counters increase, store these command in `/rw/config/qubes-firewall-user-script`
@ -407,8 +411,8 @@ sudo nano /rw/config/qubes-firewall-user-script
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
# Add a natting rule if it did not exit (to avoid cluter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.2.y
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.0.xx
fi
@ -417,7 +421,7 @@ fi
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.x -j MY-HTTPS
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j MY-HTTPS
fi
@ -427,7 +431,7 @@ fi
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exit (to avoid cluter if script executed multiple times)
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
fi
@ -436,7 +440,7 @@ fi
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 4 -d 10.137.2.y -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
iptables -w -I FORWARD 4 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
@ -447,7 +451,7 @@ fi
if ! nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.y tcp dport 443 ct state new counter accept
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
fi
~~~
@ -458,13 +462,16 @@ Finally make this file executable (so it runs at every Firewall VM update)
sudo chmod +x /rw/config/qubes-firewall-user-script
~~~
If the service should be available to other VMs on the same system, do not forget to specify the additional rules described above.
**4. Allow packets into the qube to reach the service**
Here no routing is required, only filtering.
Proceed in the same way as above but store the filtering rule in the `/rw/config/rc.local` script.
For the following example, we assume that the target VM running the web server has the IP address 10.137.0.xx
```
sudo name /rw/config/rc.local
sudo nano /rw/config/rc.local
```
~~~
@ -474,7 +481,7 @@ sudo name /rw/config/rc.local
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exit (to avoid cluter if script executed multiple times)
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -j ACCEPT
fi
@ -483,7 +490,7 @@ fi
if ! iptables -w -n -L INPUT | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I INPUT 5 -d 10.137.2.x -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
iptables -w -I INPUT 5 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~

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

@ -226,48 +226,43 @@ Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be ab
## Using Git with Split GPG
Git can be configured to used with Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed.
The most basic `~/.gitconfig` file to with working Split GPG looks something like this.
Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed.
The most basic `~/.gitconfig` file enabling Split GPG looks something like this.
```
[user]
name = YOUR NAME
email = YOUR EMAIL ADDRESS
signingkey = YOUR KEY ID
name = <YOUR_NAME>
email = <YOUR_EMAIL_ADDRESS>
signingKey = <YOUR_KEY_ID>
[gpg]
program = qubes-gpg-client-wrapper
program = qubes-gpg-client-wrapper
```
Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client -k`.
In this instance, the key id is DD160C74.
Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client --list-keys`.
In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
```shell_session
[user@work-email ~]$ qubes-gpg-client -k
[user@work-email ~]$ qubes-gpg-client --list-keys
/home/user/.gnupg/pubring.kbx
-----------------------------
pub rsa4096/DD160C74 2016-04-26
uid Qubes User
pub ed25519 2022-08-16 [C]
E142F75A6B1B610E0E8F874FB45589245791CACB
uid [ultimate] Qubes User <user@example.com>
sub ed25519 2022-08-16 [S]
sub cv25519 2022-08-16 [E]
sub ed25519 2022-08-16 [A]
```
To sign commits, you now add the "-S" flag to your commit command, which should prompt for Split GPG usage.
If you would like automatically sign all commits, you can add the following snippet to `~/.gitconfig`.
If you would like to automatically sign all commits, you can add the following snippet to `~/.gitconfig`.
```
[commit]
gpgsign = true
gpgSign = true
```
Lastly, if you would like to add aliases to sign and verify tags using the conventions the Qubes OS Project recommends, you can add the following snippet to `~/.gitconfig`.
```
[alias]
stag = "!id=`git rev-parse --verify HEAD`; git tag -s user_${id:0:8} -m \"Tag for commit $id\""
vtag = !git tag -v `git describe`
```
Replace `user` with your short, unique nickname.
Now you can use `git stag` to add a signed tag to a commit and `git vtag` to verify the most recent tag that is reachable from a commit.
Lastly, if you would like to add aliases to sign and verify tags using the conventions the Qubes OS Project recommends, refer to the [code signing documentation](/doc/code-signing/#using-pgp-with-git).
## Importing public keys

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

@ -99,10 +99,10 @@ If you are using Qubes 4.0, you can further compartmentalise your U2F keys by re
For example, you could make it so that your `twitter` qube (and, therefore, all web browsers in your `twitter` qube) can access only the key on your U2F token for `https://twitter.com`, regardless of whether any of the web browsers in your `twitter` qube or the `twitter` qube itself are compromised.
If your `twitter` qube makes an authentication request for your bank website, it will be denied at the Qubes policy level.
To enable this, create a file in dom0 named `/etc/qubes-rpc/policy/policy.RegisterArgument+u2f.Authenticate` with the following content:
To enable this, create a file in dom0 named `/etc/qubes/policy.d/30-user-u2fproxy.policy` with the following content:
```
sys-usb @anyvm allow,target=dom0
policy.RegisterArgument +u2f.Authenticate sys-usb @anyvm allow target=dom0
```
Next, empty the contents of `/etc/qubes-rpc/policy/u2f.Authenticate` so that it is a blank file.
@ -124,7 +124,7 @@ systemctl disable qubes-u2fproxy@sys-usb.service
Replace `USB_QUBE` with the actual USB qube name.
Do not forget to change the sys-usb qube name in the policy `/etc/qubes-rpc/policy/u2f.Authenticate`.
Do not forget to change the sys-usb qube name in the policy `/etc/qubes/policy.d/30-user-u2fproxy.policy`.
## Template and browser support

81
user/security-in-qubes/vm-sudo.md
View file

@ -103,86 +103,15 @@ Below is a complete list of configuration made according to the above statement,
Replacing passwordless root access with Dom0 user prompt
--------------------------------------------------------
While ITL supports the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway.
We do not support it in any of our packages, but of course nothing is preventing the user from modifying his or her own system.
A list of steps to do so is provided here **without any guarantee of safety, accuracy, or completeness.
While the Qubes developers support the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway.
We do not support this in any of our packages, but of course nothing is preventing a user from modifying his or her own system.
A list of steps to do so is provided in the [Qubes community guide, Replacing passwordless root with a dom0 prompt
](https://forum.qubes-os.org/t/replacing-passwordless-root-with-a-dom0-prompt/19074) **without any guarantee of safety, accuracy, or completeness.
Proceed at your own risk.
Do not rely on this for extra security.**
1. Adding Dom0 "VMAuth" service:
```
[root@dom0 /]# echo "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth
[root@dom0 /]# echo "@anyvm dom0 ask,default_target=dom0" \
>/etc/qubes-rpc/policy/qubes.VMAuth
```
(Note: any VMs you would like still to have passwordless root access (e.g. Templates) can be specified in the second file with "\<vmname\> dom0 allow")
2. Configuring Fedora template to prompt Dom0 for any authorization request:
- In `/etc/pam.d/system-auth`, replace all lines beginning with "auth" with these lines:
```
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
```
- Require authentication for sudo.
Replace the first line of `/etc/sudoers.d/qubes` with:
```
user ALL=(ALL) ALL
```
- Disable PolKit's default-allow behavior:
```
[root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
[root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
```
3. Configuring Debian/Whonix template to prompt Dom0 for any authorization request:
- In `/etc/pam.d/common-auth`, replace all lines beginning with "auth" with these lines:
```
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
```
- Require authentication for sudo.
Replace the first line of `/etc/sudoers.d/qubes` with:
```
user ALL=(ALL) ALL
```
- Disable PolKit's default-allow behavior:
```
[root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
[root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
```
- In `/etc/pam.d/su.qubes`, comment out this line near the bottom of the file:
```
auth sufficient pam_permit.so
```
- For Whonix, if prompts appear during boot, create `/etc/sudoers.d/zz99` and add these lines:
```
ALL ALL=NOPASSWD: /usr/sbin/virt-what
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck restart
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck start
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck stop
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck status
```
Dom0 passwordless root access
-----------------------------
There is also passwordless user->root access in dom0.
As stated in comment in sudo configuration there (different one than VMs one), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account.
As stated in the comment in sudo configuration there (which is different from the one in individual qubes), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account.

158
user/security-in-qubes/yubi-key.md
View file

@ -10,61 +10,115 @@ ref: 169
title: YubiKey
---
You can use a YubiKey to enhance Qubes user authentication, for example to mitigate risk of someone snooping the password.
This can also slightly improve security when you have a [USB keyboard](/doc/device-handling-security/#security-warning-on-usb-input-devices).
"The YubiKey is a hardware authentication device manufactured by Yubico to
protect access to computers, networks, and online services that supports
one-time passwords (OTP), public-key cryptography, and authentication, and the
Universal 2nd Factor (U2F) and FIDO2 protocols[1] developed by the FIDO
Alliance." ([Wikipedia](https://en.wikipedia.org/wiki/YubiKey))
## Challenge-response mode
## General usage in Qubes OS
In this mode, your YubiKey will generate a response based on the secret key, and a random challenge (instead of counter).
This means that it isn't possible to generate a response in advance even if someone gets access to your YubiKey.
This makes it reasonably safe to use the same YubiKey for other services (also in challenge-response mode).
Most use cases for the YubiKey can be achieved exactly as described by the
manufacturer or other instructions found online. One usually just needs to
attach the YubiKey to the corresponding app qube to get the same result (see the
documentation on how to use [USB devices](/doc/how-to-use-usb-devices/) in Qubes
OS accordingly). The recommended way for using U2F in Qubes is described
[here](https://www.qubes-os.org/doc/u2f-proxy/).
Same as in the OTP case, you will need to set up your YubiKey, choose a separate password (other than your login password!) and apply the configuration.
## Multi-factor login for Qubes OS
To use this mode you need to:
You can use a YubiKey to enhance the user authentication in Qubes. The following
instructions explain how to setup the YubiKey as an *additional* way to login.
1. Install yubikey personalization the packages in your template on which your USB VM is based.
After setting it up, you can login by providing both - a password typed in via
keyboard *and* the YubiKey plugged in. Someone eavesdropping your login attempt
would not be able to login by only observing and remembering your password.
Stealing your YubiKey would not suffice to login either. Only if an attacker has
both, the password and the Yubikey, it would be possible to login (it is thus
called [Multi-factor
authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication)).
The following instructions keep your current login password untouched and
recommends to define a new, additional password that is used in combination with
the YubiKey only. This ensures that you a) do not accidentally lock yourself out
during setup and b) you do not need to fear [shoulder
surfing](https://en.wikipedia.org/wiki/Shoulder_surfing_(computer_security)) so
much (i.e. by not using your standard login password in public).
### Setup login with YubiKey
To use the YubiKey for multi-factor authentication you need to
* install software for the YubiKey,
* configure the YubiKey for the
[Challenge-Response](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication)
mode,
* store the password for YubiKey Login and the Challenge-Response secret in
dom0,
* enable YubiKey authentication for every service you want to use it for.
All these requirements are described below, step by step.
1. Install YubiKey software in the template on which your USB VM is based.
Without this software the challenge-response mechanism is not working.
For Fedora.
```
sudo dnf install ykpers yubikey-personalization-gui
sudo dnf install ykpers
```
For Debian.
```
sudo apt-get install yubikey-personalization yubikey-personalization-gui
sudo apt-get install yubikey-personalization
```
Shut down your template.
Then, either reboot your USB VM (so changes inside the template take effect in your USB app qube) or install the packages inside your USB VM if you would like to avoid rebooting it.
Shut down your template. Then, either reboot your USB VM (so changes inside
the template take effect in your USB app qube) or install the packages inside
your USB VM as well if you would like to avoid rebooting it.
2. Configure your YubiKey for challenge-response `HMAC-SHA1` mode, for example [following this tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/).
On Debian, you can run the graphical user interface `yubikey-personalization-gui` from the command line.
- Choose `configuration slot 2`.
- It is recommended to enable `Require user input (button press)` but this is optional.
- Note: Different from the above video, use the following settings select
`HMAC-SHA1 mode`: `fixed 64 bit input`.
- We will refer the `Secret Key (20 bytes hex)` as `AESKEY`.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
- Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
- If you have multiple YubiKeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other YubiKeys.
3. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in dom0.
2. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in
dom0. This provides the program to authenticate with password and YubiKey.
```
sudo qubes-dom0-update qubes-yubikey-dom0
```
4. Adjust the USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0.
3. Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be
done on any qube, e.g. a disposable (you need to [attach the
YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube
though) or directly on the sys-usb vm.
5. Paste your `AESKEY` from step 2 into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
You need to (temporarily) install the package "yubikey-personalization-gui" and
run it by typing `yubikey-personalization-gui` in the command line.
6. Paste your hashed password (other than your standard Qubes password) into
- In the program go to `Challenge-Response`,
- select `HMAC-SHA1`,
- choose `Configuration Slot 2`,
- optional: enable `Require user input (button press)` (recommended),
- use `fixed 64 bit input` for `HMAC-SHA1 mode`,
- insert the YubiKey (if not done already) and make sure that it is attached
to the vm,
- press `Write Configuration` once you are ready.
We will refer the `Secret Key (20 bytes hex)` as `AESKEY`.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
- Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
- If you have multiple YubiKeys for backup purposes (in case a yubikey gets
lost, stolen or breaks) you can write the same settings into other
YubiKeys. You can choose "Program multiple YubiKeys" in the program, make sure
to select `Same secret for all keys` in this case.
4. Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
5. As mentioned before, you need to define a new password that is only used in
combination with the YubiKey. You can write this password in plain text into
`/etc/qubes/yk-keys/yk-login-pass` in dom0. This is considered safe as dom0 is
ultimately trusted anyway.
However, if you prefer you can paste a hashed password instead into
`/etc/qubes/yk-keys/yk-login-pass-hashed.hex` in dom0.
You can calculate your hashed password using the following two commands.
@ -78,41 +132,44 @@ To use this mode you need to:
Now run the following command to calculate your hashed password.
```
echo -n "$password" | openssl dgst -sha1
echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
```
7. Edit `/etc/pam.d/login` in dom0, adding this line at the beginning:
6. To enable multi-factor authentication for a service, you need to add
```
auth include yubikey
```
8. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using another screen locker program) in dom0, adding this line at the beginning:
to the corresponding service file in `/etc/pam.d/` in dom0. This means, if
you want to enable the login via YubiKey for xscreensaver (the default screen
lock program), you add the line at the beginning of `/etc/pam.d/xscreensaver`.
If you want to use the login for a tty shell, add it to `/etc/pam.d/login`. Add
it to `/etc/pam.d/lightdm` if you want to enable the login for the default
display manager and so on.
```
auth include yubikey
```
It is important, that `auth include yubikey` is added at the beginning of
these files, otherwise it will most likely not work.
9. Edit `/etc/pam.d/lightdm` (or appropriate file if you are using another display manager) in dom0, adding this line at the beginning:
```
auth include yubikey
```
7. Adjust the USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0.
### Usage
When you want to unlock your screen...
When you want to authenticate
1) Plug YubiKey into USB slot.
2) Enter password associated with YubiKey.
3) Press Enter.
4) If you configured so, YubiKey will request confirmation by pressing button on it (it will blink).
1. plug your YubiKey into an USB slot,
2. enter the password associated with the YubiKey,
3. press Enter and
4. press the button of the YubiKey, if you configured the confirmation (it will
blink).
When everything is ok, your screen will be unlocked.
In any case you can still use your login password, but do it in a secure location where no one can snoop your password.
In any case you can still use your normal login password, but do it in a secure
location where no one can snoop your password.
### Mandatory YubiKey Login
### Optional: Enforce YubiKey Login
Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen locker program) and remove `default=ignore` so the line looks like this.
@ -120,8 +177,9 @@ Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen loc
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
```
## Locking the screen when YubiKey is removed
### Optional: Locking the screen when YubiKey is removed
Look into it
You can setup your system to automatically lock the screen when you unplug your YubiKey.
This will require creating a simple qrexec service which will expose the ability to lock the screen to your USB VM, and then adding a udev hook to actually call that service.

4
user/templates/debian/debian-upgrade.md
View file

@ -2,8 +2,10 @@
advanced: true
lang: en
layout: doc
permalink: /doc/template/debian/upgrade/
permalink: /doc/templates/debian/in-place-upgrade/
redirect_from:
- /doc/template/debian/upgrade/
- /doc/templates/debian/upgrade/
- /doc/template/debian/upgrade-8-to-9/
- /doc/debian-template-upgrade-8/
- /en/doc/debian-template-upgrade-8/

2
user/templates/debian/debian.md
View file

@ -52,7 +52,7 @@ There are two ways to upgrade your template to a new Debian release:
- **Recommended:** [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.
- **Advanced:** [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.**
- **Advanced:** [Perform an in-place upgrade of an existing Debian template.](/doc/templates/debian/in-place-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

4
user/templates/fedora/fedora-upgrade.md
View file

@ -2,8 +2,10 @@
advanced: true
lang: en
layout: doc
permalink: /doc/template/fedora/upgrade/
permalink: /doc/templates/fedora/in-place-upgrade/
redirect_from:
- /doc/template/fedora/upgrade/
- /doc/templates/fedora/upgrade/
- /doc/template/fedora/upgrade-26-to-27/
- /doc/fedora-template-upgrade-26/
- /en/doc/fedora-template-upgrade-26/

2
user/templates/fedora/fedora.md
View file

@ -44,4 +44,4 @@ There are two ways to upgrade your template to a new Fedora release:
- **Recommended:** [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.
- **Advanced:** [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.**
- **Advanced:** [Perform an in-place upgrade of an existing Fedora template.](/doc/templates/fedora/in-place-upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**

18
user/templates/minimal-templates.md
View file

@ -25,9 +25,13 @@ templates, along with some examples of common use cases.
## Important
1. [The minimal templates are intended only for advanced
users.](https://forum.qubes-os.org/t/9717/15) If you encounter problems with
the minimal templates, we recommend that you use their standard template
counterparts instead.
users.](https://forum.qubes-os.org/t/9717/15) Most things will *not* work
out-of-the-box, and you *will* have to fix them yourself. If you are not
prepared to do a lot of reading, searching, learning, and troubleshooting,
then you should instead stick to the standard templates, which are perfectly
suitable for the vast majority of users. In particular, if you are new to
Qubes, you should not attempt to use minimal templates until you have gained
more experience.
2. If something works with a standard template but not the minimal version,
this is most likely due to user error (e.g., a missing package or
@ -245,6 +249,10 @@ list of packages to be installed):
- [USB qube](/doc/usb-qubes/), such as the template for `sys-usb`:
`qubes-usb-proxy` to provide USB devices to other Qubes and
`qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- Qubes to which USB devices are attached: `libpam-systemd` (Until
[#7689](https://github.com/QubesOS/qubes-issues/issues/7689) is fixed, either
pair it with `qubes-core-agent-passwordless-root` or manually activate the
user session with `loginctl activate <USER_SESSION_ID>`.)
- [VPN
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md):
You may need to install network-manager VPN packages, depending on the VPN
@ -254,6 +262,10 @@ list of packages to be installed):
to configure it.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
- [Yubikey](/doc/yubikey/): You may need to install `xserver-xorg-input-libinput` for 2FA responses to work in web browsers like Firefox.
- Thumbnails (e.g., file previews in Nautilus): `libgdk-pixbuf2.0-bin` (images),
`ffmpegthumbnailer` (videos). (Try `apt search thumbnailer` for other file
types.)
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be
needed to make the customized minimal template work properly. These packages

108
user/templates/templates.md
View file

@ -83,6 +83,15 @@ developers do not test them.
* [Gentoo](/doc/templates/gentoo/)
* [Gentoo Minimal](/doc/templates/minimal/)
## Windows
Windows templates are constructed differently from Linux-based templates as
Windows is a closed source system that can be modified only after installing.
So it is not possible to provide preconfigured Windows templates for Qubes.
The process of installing a Windows qube and connecting it to the Qubes
environment via installing Qubes Windows Tools (QWT) is described in several
chapters in [Windows qubes](/doc/templates/windows/).
## Installing
Certain templates come preinstalled with Qubes OS. However, there may be times
@ -95,28 +104,23 @@ when you wish to install a fresh template from the Qubes repositories, e.g.:
* When you suspect your template has been compromised.
* When you have made modifications to your template that you no longer want.
Please refer to each template's installation instructions. Usually, the
installation method is to execute the following type of command in dom0:
You can use a command line tool - `qvm-template` - or a GUI - `qvm-template-gui`.
At the command line in dom0, `qvm-template list --available` will show available templates. To install a template, use:
```
$ sudo qubes-dom0-update qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
$ qvm-template install <template_name>
```
`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>` is the name of the desired
template package. Advanced users can install a
[minimal](/doc/templates/minimal/) version of the template, if one exists, by
appending `-minimal` directly to the end of the template package name.
If you wish to install a community template, you must enable the community
template repo:
You can also use `qvm-template` to upgrade or reinstall templates.
Repo definitions are stored in `/etc/qubes/repo-templates` and associated keys in `/etc/qubes/repo-templates/keys`.
There are additional repos for testing releases and community templates.
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. E.g. :
```
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
$ qvm-template --enablerepo qubes-templates-community install <template_name>
```
If you receive the message that no match is found for
`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>`, see
[here](/faq/#when-i-try-to-install-a-template-it-says-no-match-is-found).
To permanently enable a repo, set the line `enabled = 1` in the repo definition in `/etc/qubes/repo-templates`.
To permanently disable, set the line to `enabled = 0`.
If you wish to install a template that is in testing, please see
[here](/doc/testing/#templates).
@ -132,6 +136,13 @@ After installing a fresh template, we recommend performing the following steps:
3. If desired, [uninstall the old template](#uninstalling).
## Network access
For information about how templates access the network, please see [Why don’t
templates have network
access?](/doc/how-to-install-software/#why-dont-templates-have-network-access)
and the [Updates proxy](/doc/how-to-install-software/#updates-proxy).
## Updating
Please see [How to Update](/doc/how-to-update/).
@ -211,40 +222,57 @@ Please see [How to Reinstall a Template](/doc/reinstall-template/).
## Switching
When you install a new template or upgrade a clone of a template, it is
recommended that you switch everything that was set to the old template to the
When you install a new template or
[upgrade](/doc/how-to-update/#upgrading-to-avoid-eol) a template, it is
recommended that you switch everything that was using the old template to the
new template:
1. Make the new template the default template.
1. **Make the new template the default template.** In the App Menu, go
to Qubes Tools, then click on Qubes Global Settings. In the Qube Defaults
section, next to Template, select the new template from the
drop-down list. Press OK.
```
Applications Menu -> System Tools -> Qubes Global Settings -> Default template
```
2. **Base your [disposable templates](/doc/glossary/#disposable-template) on
the new template.**
2. If your keyboard or mouse is connected through `sys-usb`, switch `sys-usb`
to the new template. (Note that this is a single command to ensure that
`sys-usb` restarts. If it does not, you will not be able to use your USB
keyboard or mouse.)
- If your only keyboard and mouse are *not* connected through a [USB
qube](/doc/usb-qubes/), or that USB qube is *not* a disposable, then shut
down all disposables. In the App Menu, go to Qubes Tools, then click on
Qube Manager. In the Qube Manager, find your disposable template(s). (By
default, they end in `-dvm`.) Right click, hover over Template, then click
on the new template. Repeat for each disposable template.
```
[user@dom0 ~]$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template <NEW_TEMPLATE>; qvm-start sys-usb
```
- If your only keyboard or mouse *are* connected through a USB qube, and
that USB qube *is* a disposable, then you will have to enter a special
command that shuts down all of your qubes, switches the USB qube's
disposable template to the new template, then starts the USB qube again.
In order to avoid being locked out of your system, you must be very
careful to enter this command without typos and with the correct
substitutions.
3. Base app qubes on the new template.
In the App Menu, click on Terminal Emulator. Type the command below,
substituting `<SYS_USB_DISPOSABLE_TEMPLATE>` with the name of the
disposable template on which `sys-usb` is based, `<NEW_TEMPLATE>` with the
name of the new template, and `<USB_QUBE>` with the name of your USB qube.
Other than these substitutions, make sure to enter the command exactly as
written.
```
Applications Menu -> System Tools -> Qubes Template Manager
```
```
qvm-shutdown --wait --all; qvm-prefs <SYS_USB_DISPOSABLE_TEMPLATE> template <NEW_TEMPLATE>; qvm-start <USB_QUBE>
```
4. Base the [disposable template](/doc/glossary/#disposable-template) on the new
template.
With substitutions, your command should look similar to this example.
(Warning: This is just an example. Do not attempt to use it.)
```
[user@dom0 ~]$ qvm-create -l red -t <NEW_TEMPLATE> <NEW_DISPOSABLE_TEMPLATE>
[user@dom0 ~]$ qvm-prefs <NEW_DISPOSABLE_TEMPLATE> template_for_dispvms True
[user@dom0 ~]$ qvm-features <NEW_DISPOSABLE_TEMPLATE> appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm <NEW_DISPOSABLE_TEMPLATE>
```
```
qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb
```
3. **Base your app qubes on the new template.** In the Qube Manager, click on
the Template heading to sort by template. Select all the qubes based on the
old template by clicking on the first one, holding shift, then clicking on
the last one. With multiple qubes selected, right-click on any of them,
hover your cursor over Template, then click on the new template.
## Advanced

54
user/templates/windows/migrate-to-4-1.md Normal file
View file

@ -0,0 +1,54 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/migrate-to-4-1/
redirect_from:
- /doc/templates/windows/windows-migrate41/
- /user/templates/windows/windows-migrate41/
- /doc/windows-migrate41/
title: Migrating Windows qubes to Qubes OS 4.1
---
For Windows 7, 10 and 11, there is a way to migrate backups created under Qubes R4.0 to R4.1. For this, the version of Qubes Windows Tools (QWT) 4.1-68, available from [tabit-pro/qubes-windows-tools-cross](https://github.com/tabit-pro/qubes-windows-tools-cross/releases), has to be installed under Qubes R4.0, selecting the option to install the Xen PV disk driver, which emulates SCSI disks. For template VMs, the option to move user profiles may be selected, too. Then, the backup may be created, and this backup can be restored under Qubes R4.1, resulting in a VM well integrated into Qubes R4.1. If `qvm-features <VMname> audio-model ich6` is set, Windows even will have audio, although for Windows 10 and 11 somewhat scratchy.
While this is somewhat straightforward, things get difficult if QWT 4.0.1.3 was installed in the VM. Prior to installing version 4.1-68, the old version has to be removed, which can be quite tricky for Windows 10 and 11.
## Preparation for Windows 7
- Uninstall QWT 4.0.1.3, using the standard procedure from the system control panel of Windows. This will most likely result in a crash.
- Restart Windows again, hitting the F8 key, select the restart menu, and there select a start in safe mode.
- The system will start gain, but in a rather useless way. Just shut it down, and reboot again.
- Now Windows will start normally. Check in the control panel, if there are any Xen drivers left. If so, uninstall them.
- In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-68 will not install.
- In the control panel, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared.
- There probably will be a drive `D:` containing the private user data. For Qubes, R4.1, QWT will expect this drive to be called `Q:`, so it has to be renamed:
- Start the command prompt as administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
- In the command prompt type `diskmgmt.msc`
- In the disk manager, select the volume `Private (D:)`
- Select the option `Change Drive Letter and Path`
- Select option `Change...`
- Select the letter `Q`
- Click `OK` in all still open windows of the disk manager and terminate it.
## Preparation for Windows 10 and 11
If there is a drive `D:` from this earlier installation of Qubes Windows Tools, it will probably contain incomplete private data; especially the folder `AppData` containing program configuration data will be missing. In this situation, it may be better to perform a new Windows installation, because repair may be difficult and trouble-prone.
- First, be sure that the automatic repair function is disabled. In a command window, execute `bcdedit /set recoveryenabled NO`, and check that this worked by issuing the command `bcdedit`, without parameters, again.
- Now, uninstall QWT 4.0.1.3, using the Apps and Features function of Windows. This will most likely result in a crash.
- Restart Windows again, possibly two or three times, until repair options are offered. By hitting the F8 key, select the restart menu, and there select a start in safe mode (in German, it's option number 4).
- The system will start gain, but in a rather useless way. Just shut it down, and reboot again.
- Now Windows will start normally. Check in the Apps and Features display, if there are any Xen drivers left. If so, uninstall them.
- In the Windows device manager, check if there is still a (probably non working) Xen PV disk device. If so, uninstall it. Otherwise, QWT 4.1-68 will not install.
- In the Apps and Features display, check again, if the Xen drivers are removed. A Xen Bus Package (version 8.2.1.8) may remain and cannot be removed, but does no harm. Any other Xen drivers should have disappeared.
## Transferring the Windows Qube
- Now, finally, after one additional reboot, Qubes Windows Tools 4.1-68 can be installed. The option `Move user profiles` should be used **if and only if** there was **no** separate drive `D:` in the earlier Windows installation.
- After one more reboot, the backup for R4.1 may be created.
- This backup can be installed in Qubes R4.1 and will (probably) work.
The PV disk drivers used for migration can be removed after successful installation of the VM under Qubes R4.1. For this, the QWT installation has to be started, the option Change has to be selected, and the PV disk driver must be unselected. After completion, the VM has to be rebooted. For Windows 10 and 11, the VM will crash with the error INACCESSIBLE BOOT DEVICE, which can be repaired as described above.
After successful uninstallation of the PV disk drivers, the disks will appear as QEMU ATA disks.
:warning: **Caution:** This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided.

358
user/templates/windows/qubes-windows-tools-4-0.md Normal file
View file

@ -0,0 +1,358 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/qubes-windows-tools-4-0/
redirect_from:
- /doc/templates/windows/windows-tools/
- /user/templates/windows/windows-tools/
- /doc/windows-tools/
- /doc/windows-appvms/
- /en/doc/windows-appvms/
- /doc/WindowsAppVms/
- /wiki/WindowsAppVms/
- /doc/windows-tools-3/
- /en/doc/windows-tools-3/
- /doc/WindowsTools3/
- /doc/WindowsTools/
- /wiki/WindowsTools/
title: Qubes Windows Tools (QWT) in Qubes OS 4.0
---
**Warning:** *The content below describes Qubes Windows Tools installation in Qubes R4.0. The text has been updated to reflect the newer R4.1 release and QWT recent development. Please see [this updated document](/doc/templates/windows/qubes-windows-tools-4-1) for instructions for Qubes R4.1 and the updated version of Qubes Windows Tools.*
Qubes Windows Tools are a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools:
- **Qubes Video Driver** - provides for the Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop
- **File sender/receiver** - Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs
- **File sender/receiver** - Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs
- **Copy/Edit in Disposable VM** - Support for editing files in DisposableVMs as well as for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- **Xen PV drivers** for Windows that increase performance compared to qemu emulated devices
Below is a breakdown of the feature availability depending on the windows version:
| Feature | Windows 7 x64 | Windows 10 x64 |
| ------------------------------------ | :------------: | :------------: |
| Qubes Video Driver | + | - |
| Qubes Network Setup | + | + |
| Private Volume Setup (move profiles) | + | + |
| File sender/receiver | + | + |
| Clipboard Copy/Paste | + | + |
| Application shortcuts | + | + |
| Copy/Edit in Disposable VM | + | + |
| Block device | + | + |
| USB device | + | + |
| Audio | - | - |
Qubes Windows Tools are open source and are distributed under a GPL license.
**Notes:**
- Qubes Windows Tools are currently unmaintained
- Currently only 64-bit versions of Windows 7 and Windows 10 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- __This page documents the process of installing Qubes Windows Tools on versions up to R3.2.__. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585)).
Installing Windows OS in a Qubes VM
-----------------------------------
Please refer to [this page](/doc/templates/windows/windows-vm) for instructions on how to install Windows in a Qubes VM.
**Note:** It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option.
Installing Qubes guest tools in Windows 10 VMs
----------------------------------------------
This will allow you to install the Qubes Windows Tools on Windows 10 both as a StandaloneVM as well as a Template VM and a corresponding AppVM. But some features are not available:
**Note:** seamless mode is currently not available for windows. Please check the top of this document for the full feature availability breakdown.
1. In the Windows 10 VM, download from the [XEN website](https://xenproject.org/downloads/windows-pv-drivers/windows-pv-drivers-9-series/windows-pv-drivers-9-0-0/) the installation kits for Xen bus (`xenbus`) and storage drivers (`xenvbd`) Version 9.0.0 (two files`xenvbd.tar`and `xenbus.tar`).
2. Use an archive extractor like [7-zip](https://www.7-zip.org/) to extract the contents of the `.tar` files.
3. Install `xenvbd` and `xenbus` by starting the file `dpinst.exe` from the `x64` directories of the extracted tar-files. If during installation, the Xen driver requests a reboot, select "No" and let the installation continue.
4. After installation, reboot.
5. Download the Qubes Windows Tools (`qubes-tools-4.0.1.3.exe`) from [the qubes FTP server](https://ftp.qubes-os.org/qubes-windows-tools/) and move it to `C:\`.
6. Check the integrity of the file `qubes-tools-4.0.1.3.exe`by comparing its hash checksum. This can be done using the Windows command `certutil` on the windows command prompt (`cmd.exe`) and specifying an appropriate hash algorithm like:
certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256
And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
**Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
8. Shut down Windows and wait until the VM is really stopped, i.e. Qubes shows no more activity.
9. On a `dom0` terminal write: *(where `<VMname>` is the name of your Windows 10 VM)*
qvm-features <VMname> gui 1
qvm-prefs <VMname> qrexec_timeout 300
10. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager, wait until it has really stopped, and reboot Windows once more.
11. Now the system should be up, with QWT running correctly.
12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows 10 VM)*
`qvm-prefs <VMname> default_user <username> `
**Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\<source_VM>
If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown.
Installing Qubes guest tools in Windows 7 VMs
---------------------------------------------
First, make sure that `qubes-windows-tools` is installed in your system:
~~~
sudo qubes-dom0-update qubes-windows-tools
~~~
(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.)
You can also install the package from testing repositories, where we usually publish new versions first:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
~~~
This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
- In the command prompt type `bcdedit /set testsigning on`
- Reboot your Windows VM
In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
~~~
qvm-start lab-win7 --install-windows-tools
~~~
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory.
After successful installation, the Windows VM must be shut down and started again, possibly a couple of times.
Qubes will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command:
~~~
qvm-prefs <your-appvm-name>
~~~
**Note:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
~~~
qvm-prefs <vm-name> qrexec_timeout 300
~~~
Xen PV drivers and Qubes Windows Tools
--------------------------------------
Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers:
1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html)
2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
Notes about using Xen's VBD (storage) PV driver:
- **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above).
- the option to install the storage PV driver is disabled by default in Qubes Windows Tools
- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar).
**Caution:** Installing the version 9.0.0 Xen drivers on Windows 7 (a system without QWT - QWT uninstalled) leads to an unbootable system. The drivers install without error, but after reboot, the system aborts the reboot saying `Missing driver xenbus.sys`.
- **Windows 10:** The version 9.0.0 Xen drivers have to be installed before installing Qubes Windows Tools. Installing them on a system with QWT installed is likely to produce a system which crashes or has the tools in a non-functional state. Even if the tools were installed and then removed before installing the Xen drivers, they probably will not work as expected.
With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver:
~~~
qvm-prefs -s win7new debug false
~~~
Using Windows AppVMs in seamless mode
-------------------------------------
**Note:** This feature is only available for Windows 7
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
~~~
qvm-run -a my-win7-appvm explorer.exe
~~~
[![windows-seamless-4.png](/attachment/doc/windows-seamless-4.png)](/attachment/doc/windows-seamless-4.png)
[![windows-seamless-1.png](/attachment/doc/windows-seamless-1.png)](/attachment/doc/windows-seamless-1.png)
Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM:
~~~
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
~~~
~~~
[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com
~~~
... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation.
Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM.
To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground.
[![windows-seamless-7.png](/attachment/doc/windows-seamless-7.png)](/attachment/doc/windows-seamless-7.png)
Changing between seamless and full desktop mode
-----------------------------------------------
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default.
Using template-based Windows AppVMs
-----------------------------------
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM).
In order to create a HVM TemplateVM one can use the following command, suitably adapted:
~~~
qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green
~~~
... , set memory as appropriate, and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/).
If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - the User directory will be wiped when the HVN is closed down.
If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs.
This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically.
To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`.
It's a selectable feature of the installer, enabled by default, but working only for Windows 7.
If that feature is selected during installation, completion of the process requires two reboots:
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
- User profiles are moved to the private disk on the next reboot after the private disk is initialized.
Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there.
This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot.
That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
For Windows 10, the user directories have to be moved manually, because the automatic transfer during QWT installation is bound to crash due to undocumented new features of NTFS, and a system having the directory `users`on another disk than `C:` will break on Windows update. So the following steps should be taken:
- The Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\<username>\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected.
- Configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM.
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on it:
~~~
qvm-create --property virt_mode=hvm <new windows appvm name> --template <name of template vm> --label <label color>
~~~
Components
----------
Qubes Windows Tools (QWT for short) contain several components than can be enabled or disabled during installation:
- Shared components (required): common libraries used by QWT components.
- Xen PV drivers: drivers for the virtual hardware exposed by Xen.
- Base Xen PV Drivers (required): paravirtual bus and interface drivers.
- Xen PV Disk Drivers: paravirtual storage drivers.
- Xen PV Network Drivers: paravirtual network drivers.
- Qubes Core Agent: qrexec agent and services. Needed for proper integration with Qubes.
- Move user profiles: user profile directory (c:\users) is moved to VM's private disk backed by private.img file in dom0 (useful mainly for HVM templates).
- Qubes GUI Agent: video driver and gui agent that enable seamless showing of Windows applications on the secure Qubes desktop.
- Disable UAC: User Account Control may interfere with QWT and doesn't really provide any additional benefits in Qubes environment.
**In testing VMs only** it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
**NOTE**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms.
Xen PV driver components may display a message box asking for reboot during installation -- it's safe to ignore them and defer the reboot.
Installation logs
-----------------
If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `<user profile>\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`.
Uninstalling QWT is supported from version 3.2.1. Uninstalling previous versions is **not recommended**.
After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access.
Configuration
-------------
Starting from version 2.2.\* various aspects of Qubes Windows Tools can be configured through registry. Main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QWT components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
|**Level**| **Type** |**Description** |
|:--------|:-----------|:-----------------------------------------------------|
| 1 |Error |Serious errors that most likely cause irrecoverable failures|
| 2 |Warning |Unexpected but non-fatal events|
| 3 |Info |Useful information (default)|
| 4 |Debug |Internal state dumps for troubleshooting|
| 5 |Verbose |Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension. For example, to change qrexec-agent's log level to Debug, set it like this:
[![qtw-log-level.png](/attachment/doc/qtw-log-level.png)](/attachment/doc/qtw-log-level.png)
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
Troubleshooting
---------------
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `qvm-start --debug vmname`
- mash F8 on the boot screen to enable boot options and select Safe Mode (optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from c:\Windows.
Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
||
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-wrapper|Helper executable that's responsible for launching qrexec services, handling their I/O and vchan communication.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|qga|Gui agent.|
|QgaWatchdog|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (ctrl-alt-del).|
|qubesdb-daemon|Service for accessing Qubes configuration database.|
|network-setup|Service that sets up network parameters according to VM's configuration.|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QWT setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|relocate-dir|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `c:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
Updates
-------
When we publish new QWT version, it's usually pushed to the `current-testing` or `unstable` repository first. To use versions from current-testing, run this in dom0:
`qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools`
That command will download a new QWT .iso from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.

357
user/templates/windows/qubes-windows-tools-4-1.md Normal file
View file

@ -0,0 +1,357 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/qubes-windows-tools-4-1/
redirect_from:
- /doc/templates/windows/windows-tools41/
- /user/templates/windows/windows-tools41/
title: Qubes Windows Tools (QWT)
---
Qubes Windows Tools (QWT) are a set of programs and drivers that provide integration of Windows 7, 8.1, 10 and 11 Standalone, TemplateVMs and AppVMs with the rest of the Qubes system. They contain several components than can be enabled or disabled during installation, and rely on specific functions of Qubes which support this integration:
- **Shared components (required)** - common libraries used by QWT components
- **Qubes GUI Agent** - video driver and GUI agent that enable the seamless GUI mode that integrates windows apps onto the common Qubes trusted desktop (currently only for Windows 7)
- **Disable UAC** - User Account Control may interfere with QWT and doesn't really provide any additional benefits in Qubes environment
- **Clipboard sender/receiver** - Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs
- **File sender/receiver** - Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs
- **Xen PV drivers** - drivers for the virtual hardware exposed by Xen for Windows that increase performance compared to QEMU emulated devices and are required for attaching USB devices
- Base Xen PV Drivers (required): paravirtual bus and interface drivers
- Xen PV Disk Drivers: paravirtual storage drivers
- Xen PV Network Drivers: paravirtual network drivers
- Move user profiles: user profile directory (`C:\users`) is moved to VM's private disk backed by `private.img file` in `dom0` (useful mainly for HVM templates).
- **Qubes Core Agent** (part of Qubes) - Needed for proper integration with Qubes as well as for `qvm-run` and generic `qrexec` for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- **Copy/Edit in Disposable VM** (part of Qubes) - Support for editing files in DisposableVMs
- **Audio** - Audio support is available even without QWT installation if `qvm-features audio-model` is set as `ich6`
**Note:** Due to the security problems described in [QSB-091](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt), installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or dom0 and thus be dangerous for Qubes itself. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
sudo qubes-dom0-update qubes-windows-tools-4.1.68
for Qubes R4.1.2, or
sudo qubes-dom0-update qubes-windows-tools-4.1.69
for Qubes R4.2.0, respectively, instead of the command listed in step 1 of the installation described below. This will provide the .iso file to be presented as installation drive to the Windows qube in step 3 of the QWT installation.
If you prefer to download the corresponding .rpm files for manual QWT installation, these are still available from the repositories (version [4.1.68-1](https://yum.qubes-os.org/r4.1/current/dom0/fc32/rpm/qubes-windows-tools-4.1.68-1.noarch.rpm) for Qubes R4.1.2 and version [4.1.69-1](https://yum.qubes-os.org/r4.2/current/dom0/fc37/rpm/qubes-windows-tools-4.1.69-1.fc37.noarch.rpm) for Qubes R4.2.0).
**Warning**: These older versions of Qubes Windows Tools will be replaced during the next dom0 update by the current dummy version 4.1.70-1. This can be inhibited by appending the line `exclude=qubes-windows-tools` to the file `/etc/dnf/dnf.conf` in dom0. But this will also stop any further QWT updates - so be sure to remove this line when - hopefully - a new functional version 4.1.71-1 of Qubes Windows Tools will be made available!!!
**Note**: If you choose to move profiles, drive letter `Q:` must be assigned to the secondary (private) disk.
**Note**: Xen PV disk drivers are not installed by default. This is because they seem to cause problems (BSOD = Blue Screen Of Death). We're working with upstream devs to fix this. *However*, the BSOD seems to only occur after the first boot and everything works fine after that. **Enable the drivers at your own risk** of course, but we welcome reports of success/failure in any case (backup your VM first!). With disk PV drivers absent `qvm-block` will not work for the VM, but you can still use standard Qubes inter-VM file copying mechanisms. On the other hand, the Xen PV drivers allow USB device access even without QWT installation if `qvm-features stubdom-qrexec` is set as `1`
Below is a breakdown of the feature availability depending on the windows version:
| Feature | Windows 7 x64 | Windows 8.1/10/11 x64 |
| ------------------------------------ | :------------: | :-------------------: |
| Qubes Video Driver | + | - |
| Qubes Network Setup | + | + |
| Private Volume Setup (move profiles) | + | + |
| File sender/receiver | + | + |
| Clipboard Copy/Paste | + | + |
| Application shortcuts | + | + |
| Copy/Edit in Disposable VM | + | + |
| Block device | + | + |
| USB device | + | + |
| Audio | + | + |
Qubes Windows Tools are open source and are distributed under a GPL license.
**Notes:**
- Currently only 64-bit versions of Windows 7, 8.1, 10 and 11 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- This page documents the process of installing Qubes Windows Tools in version **R4.1**.
- *In testing VMs only* it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS.
## Preparation
**Windows 7 only:** Before proceeding with the installation we need to disable the Windows mechanism that allows only signed drivers to be installed, because currently the Qubes video driver, available for Windows 7, provided as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
1. Start the command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
2. In the command prompt type `bcdedit /set testsigning on`
3. Reboot your Windows VM
In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation `iso` file can be verified as described in step 3 below. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
The Xen PV Drivers bundled with QWT are signed by a Linux Foundation certificate. Thus Windows 10 and 11 do not require this security mitigation.
**Warning:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when `qrexec` is not yet running, so timeout may occur with the default value. To change the property use this command in `dom0`: *(where `<VMname>` is the name of your Windows VM)*
[user@dom0 ~] $ qvm-prefs <VMname> qrexec_timeout 7200
## Installing Windows OS as a Qubes VM
Please refer to [this page](/doc/templates/windows/windows-qubes-4-1/) for instructions on how to install Windows in a Qubes VM.
**Warning:** It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option.
## Installing Qubes Windows Tools (QWT) in a Windows VM
Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a StandaloneVM as well as a Template VM and a corresponding AppVM is described in the following sections.
**Note:** Seamless mode is currently not available for windows 10 and 11. Please check the top of this document for the full feature availability breakdown.
1. First, make sure that `qubes-windows-tools` is installed in your system:
sudo qubes-dom0-update qubes-windows-tools
(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.)
You can also install the package from testing repositories, where we usually publish new versions first:
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
If an earlier version of Qubes Windows Tools is already installed, with enabled current-testing repo you need to specify as action to `upgrade` the existing package, because the default action is `install`, which will fail if it detects that QWT is already present in Dom0:
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing --action=upgrade qubes-windows-tools
This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
2. **For Windows 8.1, 10 and 11:** From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which may lead to corruption of the VM's disk.
powercfg -H off
Also, these versions of Windows won’t show the CD-ROM drive after starting the qube with `qvm-start vm --cdrom ...` or `qvm-start ... --install-windows-tools`. The solution is to disable hibernation in Windows with this command. (That command is included in QWT’s setup but it’s necessary to run it manually in order to be able to open QWT’s setup ISO/CD-ROM in Windows).
3. To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
qvm-start <VMname> --install-windows-tools
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:` or `E:`) with the setup program `qubes-tools-x64.msi` in its main directory.
4. Install Qubes Windows Tools by starting `qubes-tools-x64.msi` (logged in as administrator), optionally selecting the `Xen PV disk drivers`. For installation in a template, you should select `Move user profiles`.
[![QWT_install_select](/attachment/doc/QWT_install_select.png)](/attachment/doc/QWT_install_select.png)
Several times, Windows security may ask for confirmation of driver installation. Driver installation has to be allowed; otherwise the installation of Qubes Windows Tools will abort.
[![QWT_install_driver](/attachment/doc/QWT_install_driver.png)](/attachment/doc/QWT_install_driver.png)
If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
[![QWT_install_no_restart](/attachment/doc/QWT_install_no_restart.png)](/attachment/doc/QWT_install_no_restart.png)
5. After successful installation, the Windows VM must be shut down and started again, possibly a couple of times. On each shutdown, wait until the VM is really stopped, i.e. Qubes shows no more activity.
6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using the `qvm-prefs` command *(where `<VMname>` is the name of your Windows VM)*:
[user@dom0 ~] $ qvm-prefs <VMname>
It is advisable to set some other parameters in order to enable audio and USB block device access, synchronize the Windows clock with the Qubes clock, and so on:
[user@dom0 ~] $ qvm-features <VMname> audio-model ich9
[user@dom0 ~] $ qvm-features <VMname> stubdom-qrexec 1
[user@dom0 ~] $ qvm-features <VMname> timezone localtime
For audio, the parameter `audio-model`can be selected as `ich6` or `ich9`; select the value that gives the best audio quality. Audio quality may also be improved by setting the following parameters, but this can depend on the Windows version and on your hardware:
[user@dom0 ~] $ qvm-features <VMname> timer-period 1000
[user@dom0 ~] $ qvm-features <VMname> out.latency 10000
[user@dom0 ~] $ qvm-features <VMname> out.buffer-length 4000
With the value `localtime` the dom0 `timezone` will be provided to virtual hardware, effectively setting the Windows clock to that of Qubes. With a digit value (negative or positive) the guest clock will have an offset (in seconds) applied relative to UTC.
7. Reboot Windows. If the VM starts, but does not show any window then shutdown Windows from the Qube manager, wait until it has really stopped, and reboot Windows once more.
8. Now the system should be up, with QWT running correctly.
9. **Windows 7 only:** Optionally enable seamless mode on VM startup. This can be done by setting appropriate values in the Windows registry:
- Start the command prompt as administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
- In the command prompt type `regedit`
- In the registry editor, position to the key `\HKEY_LOCAL_MACHINE\Software\Invisible Things Lab\Qubes Tools\`
- Change the value `SeamlessMode` from 0 to 1
- Position to the key `\HKEY_LOCAL_MACHINE\Software\Invisible Things Lab\Qubes Tools\qga\`
- Change the value `SeamlessMode` from 0 to 1
- Terminate the registry editor.
After the next boot, the VM will start in seamless mode.
If Windows is used in a TemplateVM / AppVM combination, this registry fix has to be applied to the TemplateVM, as the `HKLM` registry key belongs to the template-based part of the registry.
10. Lastly to enable file copy operations to a Windows VM, the `default_user` property of this VM should be set to the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows VM)*
`[user@dom0 ~] $ qvm-prefs <VMname> default_user <username>`
**Warning:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\<source_VM>
If the target VM is an AppVM, this has the consequence that the files are stored in the corresponding TemplateVM and so are lost on AppVM shutdown.
## Xen PV drivers and Qubes Windows Tools
Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Windows VM are usually very stable). They can be installed as an optional part of Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
**Notes** about using Xen's VBD (storage) PV driver:
- **Windows 7:** Installing the driver requires a fully updated VM or else you'll likely get a BSOD ("Blue Screen Of Death") and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps or attach block devices. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools. Installing the driver will probably cause Windows 7 activation to become invalid, but the activation can be restored using the Microsoft telephone activation method.
- The option to install the storage PV driver is disabled by default in Qubes Windows Tools
- In case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver by again starting the QWT installer and selecting the change option.
## Using Windows AppVMs in seamless mode
**Note:** This feature is only available for Windows 7
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
~~~
[user@dom0 ~] $ qvm-run -a my-win-appvm explorer.exe
~~~
[![windows-seamless-4.png](/attachment/doc/windows-seamless-4.png)](/attachment/doc/windows-seamless-4.png)
[![windows-seamless-1.png](/attachment/doc/windows-seamless-1.png)](/attachment/doc/windows-seamless-1.png)
Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM:
~~~
[user@dom0 ~] $ qvm-open-in-vm my-win-appvm roadmap.pptx
[user@dom0 ~]$ qvm-open-in-vm my-win-appvm https://invisiblethingslab.com
~~~
... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation.
Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM.
To simulate Ctrl-Alt-Delete in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground.
[![windows-seamless-7.png](/attachment/doc/windows-seamless-7.png)](/attachment/doc/windows-seamless-7.png)
**Changing between seamless and full desktop mode**
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default.
## Using template-based Windows AppVMs
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM).
In order to create an HVM TemplateVM, the type "TemplateVM" has to be selected on creating the VM. Then set memory as appropriate, and install the Windows OS (or any other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/).
If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - the User directory will be wiped when the HVM is closed down.
If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs.
This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically.
To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`.
It's a selectable feature of the installer. For Windows 7, it requires the private disk to be renamed to `Q:` before QWT installation (see above); for Windows 8.1, 10 and 11, this renaming occurs during QWT installation automatically.
If that feature is selected during installation, completion of the process requires two reboots:
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
- User profiles are moved to the private disk on the next reboot after the private disk is initialized.
Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there.
This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot.
That's a false alarm (you can increase the AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives). Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on it, by selecting the type "AppVM" and a suitable template.
## Using Windows disposables
Windows qubes can be used as disposables, like any other Linux-based qubes. On creating a template for Windows disposables, certain preparations have to be executed:
- Create an AppVM based on a Windows TemplateVM.
- Start this AppVM and insert a link to the command prompt executable in the `Autostart` directory of the Windows menu tree:
- **For Windows 7:**
- If the Windows qube started in seamless mode, hit the Windows keyboard key while the cursor is positioned in a window of this VM. In non-seamless mode, klick on the Start button. In both cases, the Windows menu will be displayed.
- Position into the `Autostart` submenu.
- **For Windows 8.1, 10 or 11:**
- Type Win+R to open the execution Prompt.
- Type `shell:startup`.
- An explorer window will open, which is positioned to the `Autostart` folder.
- Right-click and select the option "New -> Link".
- Select `C:\Windows\System32\CMD.exe`as executable.
- Name the link, e.g. as `Command Prompt`.
- Close the Window with `OK`.
- Shut down this AppVM.
- In the Qube Manager, refresh the applications of the newly created AppVM and select those applications that you want to make available from the disposable. Alternatively, in dom0 execute the command `qvm-sync-appmenus <VMname>`, *where `<VMname>` is the name of your windows qube*.
- In the Qube Manager, go to the "Advanced" tab and enable the option `Disposable template` for your Windows qube. Alternatively, in dom0 execute the commands `qvm-prefs <VMname> template_for_dispvms True` and `qvm-features <VMname> appmenus-dispvm 1`.
- Click `Apply`.
- Still in the Advanced tab, select your Windows qube as its own `Default disposable template`. Alternatively, in dom0 execute the command `qvm-prefs <VMname> default_dispvm <VMname>`.
- Close the Qube Manager by clicking `OK`.
Now you should have a menu `Disposable: <VMname>` containing the applications that can be started in a disposable Windows VM. If you set the newly created and configured Windows VM as `Default disposable template`for any other Windows- (or Linux-) based qube, this qube can use the Windows-based dispvm like any other disposable.
For further information on usage of disposables, see [How to use disposables](/doc/how-to-use-disposables/).
**Caution:** *If a Windows-based disposable is used from another qube via the `Open/Edit in DisposableVM` command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down manually.*
## Installation logs
If the install process fails or something goes wrong during it, include the installation logs in your bug report. They are created in the `%TEMP%` directory, by default `<user profile>\AppData\Local\Temp`. There are two text files, one small and one big, with names starting with `Qubes_Windows_Tools`.
Uninstalling QWT is supported. After uninstalling you need to manually enable the DHCP Client Windows service, or set IP settings yourself to restore network access.
## Configuration
Various aspects of Qubes Windows Tools (QWT) can be configured through the registry. The main configuration key is located in `HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools`. Configuration values set on this level are global to all QWT components. It's possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
|**Name**|**Type**|**Description**|**Default value**|
|:-------|:-------|:--------------|:----------------|
|LogDir|String|Directory where logs are created|c:\\Program Files\\Invisible Things Lab\\Qubes Tools\\log|
|LogLevel|DWORD|Log verbosity (see below)|2 (INFO)|
|LogRetention|DWORD|Maximum age of log files (in seconds), older logs are automatically deleted|604800 (7 days)|
Possible log levels:
|**Level**|**Title**|**Description**|
|:-----|:-----|:--------------|
|1|Error|Serious errors that most likely cause irrecoverable failures|
|2|Warning|Unexpected but non-fatal events|
|3|Info|Useful information (default)|
|4|Debug|Internal state dumps for troubleshooting|
|5|Verbose|Trace most function calls|
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
To override global settings for a specific component, create a new key under the root key mentioned above and name it as the executable name, without `.exe` extension.
Component-specific settings currently available:
|**Component**|**Setting**|**Type**|**Description**|**Default value**|
|:------------|:----------|:-------|:--------------|:----------------|
|qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1|
## Troubleshooting
If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functioning), try to boot it in safe mode:
- `[user@dom0 ~] $ qvm-start --debug <VMname>`
- Enable boot options and select Safe Mode (method depends on the Windows version; optionally with networking)
Safe Mode should at least give you access to logs (see above).
**Please include appropriate logs when reporting bugs/problems.** Logs contain the QWT version. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from `C:\Windows`.
Xen logs in dom0 (`/var/log/xen/console/guest-*`) are also useful as they contain pvdrivers diagnostic output.
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
|**Component**|**Description**|
|:------------|:--------------|
|qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.|
|qrexec-wrapper|Helper executable that's responsible for launching qrexec services, handling their I/O and vchan communication.|
|qrexec-client-vm|Used for communications by the qrexec protocol.|
|qga|Gui agent.|
|QgaWatchdog|Service that monitors session/desktop changes (logon/logoff/locking/UAC...) and simulates SAS sequence (Ctrl-Alt-Del).|
|qubesdb-daemon|Service for accessing Qubes configuration database.|
|network-setup|Service that sets up network parameters according to VM's configuration.|
|prepare-volume|Utility that initializes and formats the disk backed by `private.img` file. It's registered to run on next system boot during QWT setup, if that feature is selected (it can't run *during* the setup because Xen block device drivers are not yet active). It in turn registers move-profiles (see below) to run at early boot.|
|relocate-dir|Utility that moves user profiles directory to the private disk. It's registered as an early boot native executable (similar to chkdsk) so it can run before any profile files are opened by some other process. Its log is in a fixed location: `C:\move-profiles.log` (it can't use our common logger library so none of the log settings apply).|
If there are network-related issues, the qube doesn't resolve DNS and has trouble accessing the Internet, this might be an issue with the PV Network Drivers.
In this case it's recommended that the PV Network Drivers be unchecked during installation of Qubes Windows Tools as seen in the screenshot below.
[![QWT_no_PV_network](/attachment/doc/QWT_no_PV_network.png)](/attachment/doc/QWT_no_PV_network.png)
## Updates
When we publish a new QWT version, it's usually pushed to the `current-testing` or `unstable` repository first. To use versions from current-testing, run this in dom0:
[user@dom0 ~] $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
That command will download a new QWT `iso` file from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.

260
user/templates/windows/windows-qubes-4-0.md Normal file
View file

@ -0,0 +1,260 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/windows-qubes-4-0/
redirect_from:
- /doc/templates/windows/windows-vm/
- /user/templates/windows/windows-vm/
- /doc/windows-vm/
title: How to install Windows qubes in Qubes OS 4.0
---
**Warning:** *The content below describes Windows installation in Qubes R4.0. The text has been updated to reflect the newer R4.1 release and QWT recent development. Please see [this updated document](/doc/templates/windows/windows-qubes-4-1) for instructions for Qubes R4.1.*
## Simple Windows install
If you just want something simple and you can live without some features.
Works:
- display (1440x900 or 1280x1024 are a nice fit onto FHD hw display)
- keyboard (incl. correct mapping), pointing device
- network (emulated Realtek NIC)
Does not work:
- copy & paste (the qubes way)
- copying files into / out of the VM (the qubes way)
- assigning USB devices (the qubes way via the tray applet)
- audio output and input
- PCI device 5853:0001 (Xen platform device) - no driver
- all other features/hardware needing special tool/driver support
Installation procedure:
- Have the Windows 10 ISO image (I used the 64-bit version) downloaded in some qube.
- Create a new Qube:
- Name: Win10, Color: red
- Standalone Qube not based on a template
- Networking: sys-firewall (default)
- Launch settings after creation: check
- Click "OK".
- Settings:
- Basic:
- System storage: 30000+ MB
- Advanced:
- Include in memory balancing: uncheck
- Initial memory: 4096+ MB
- Kernel: None
- Mode: HVM
- Click "Apply".
- Click "Boot from CDROM":
- "from file in qube":
- Select the qube that has the ISO.
- Select ISO by clicking "...".
- Click "OK" to boot into the windows installer.
- Windows Installer:
- Mostly as usual, but automatic reboots will halt the qube - just restart
it again and again until the installation is finished.
- Install on first disk.
- Windows license may be read from flash via root in dom0:
`strings < /sys/firmware/acpi/tables/MSDM`
Alternatively, you can also try a Windows 7 license key (as of 2018/11
they are still accepted for a free upgrade).
I first installed Windows and all updates, then entered the license key.
- Afterwards:
- In case you switch from `sys-network` to `sys-whonix`, you'll need a static
IP network configuration, DHCP won't work for `sys-whonix`.
- Use `powercfg -H off` and `disk cleanup` to save some disk space.
## Qubes 4.0 - importing a Windows VM from R3.2
Importing should work, simply make sure that you are not using Xen's newer linux stubdomain and that the VM is in HVM mode (these steps should be done automatically when importing the VM):
~~~
qvm-features VMNAME linux-stubdom ''
qvm-prefs VMNAME virt_mode hvm
~~~
Note however that you are better off creating a new Windows VM to benefit from the more recent emulated hardware: R3.2 uses a MiniOS based stubdomain with an old and mostly unmaintained 'qemu-traditional' while R4.0 uses a Linux based stubdomain with a recent version of upstream qemu (see [this post](https://groups.google.com/d/msg/qubes-devel/tBqwJmOAJ94/xmFCGJnuAwAJ)).
## Windows qube installation
### qvm-create-windows-qube
An unofficial, third-party tool for automating this process is available [here](https://github.com/elliotkillick/qvm-create-windows-qube).
(Please note that this tool has not been reviewed by the Qubes OS Project.
Use it at your own risk.)
However, if you are an expert or want to do it manually you may continue below.
### Summary
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
qvm-prefs win7new kernel ''
qvm-volume extend win7new:root 25g
qvm-prefs win7new debug true
qvm-features win7new video-model cirrus
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start win7new
# once Windows is installed and working
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
qvm-features --unset win7new video-model
qvm-prefs win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs win7new debug false
~~~
To install Qubes Windows Tools, follow instructions in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-0).
### Detailed instructions
MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64. Note that there are [known issues](https://github.com/QubesOS/qubes-issues/issues/3585) with QWT on Qubes 4.x
- For Windows 10 under Qubes 4.0, a way to install QWT 4.0.1.3, which has worked in several instances, is described in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-0).
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
~~~
Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
`/var/log/xen/console/hypervisor.log`:
~~~
p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
(XEN) domain_crash called from p2m-pod.c:1218
(XEN) Domain 120 (vcpu#0) crashed on cpu#3:
~~~
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing).
~~~
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
~~~
Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence:
~~~
qvm-prefs win7new kernel ''
~~~
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
~~~
qvm-volume extend win7new:root 25g
~~~
Set the debug flag in order to have a graphical console:
~~~
qvm-prefs win7new debug true
~~~
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in "transient" mode with the following error in `guest-win7new-dm.log`:
~~~
qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
~~~
To avoid that error we temporarily have to switch the video adapter to 'cirrus':
~~~
qvm-features win7new video-model cirrus
~~~
The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/standalones-and-hvms/#installing-an-os-in-an-hvm):
~~~
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
~~~
Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'win7new'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-win7new-dm.log
~~~
The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone win7new win7newbkp1`). Then, (re)start the VM with `qvm-start win7new`.
The second part of Windows' installer should then be able to complete successfully. You may then perform the following post-install steps:
Decrease the VM's memory to a more reasonable value (memory balancing on Windows is unstable so keep `memory` equal to `maxmen`).
~~~
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
~~~
Revert to the standard VGA adapter: the 'cirrus' adapter will limit the maximum screen resolution to 1024x768 pixels, while the default VGA adapter allows for much higher resolutions (up to 2560x1600 pixels).
~~~
qvm-features --unset win7new video-model
~~~
Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won't complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation.
~~~
qvm-prefs win7new qrexec_timeout 300
~~~
At that point you should have a functional and stable Windows VM, although without updates, Xen's PV drivers nor Qubes integration (see sections [Windows Update](/doc/templates/windows/windows-qubes-4-0/#windows-update) and [Xen PV drivers and Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-0/#xen-pv-drivers-and-qubes-windows-tools)). It is a good time to clone the VM again.
## Windows as a template
Windows 7 and 10 can be installed as TemplateVM by selecting
~~~
qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template
~~~
when creating the VM. To have the user data stored in AppVMs depending on this template, Windows 7 and 10 have to be treated differently:
- For Windows 7, the option to move the user directories from drive `C` to drive `D` works and causes any user data to be stored in the AppVMs based on this template, and not in the template itself.
- After installation of Windows 10 as a TemplateVM, the Windows disk manager may be used to add the private volume as disk `D:`, and you may, using the documented Windows operations, move the user directories `C:\users\<username>\Documents` to this new disk, allowing depending AppVMs to have their own private volumes. Moving the hidden application directories `AppData`, however, is likely to invite trouble - the same trouble that occurs if, during QWT installation, the option `Move user profiles` is selected.
For Windows 10, configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM.
AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
~~~
qvm-create --class=AppVM --template=<VMname>
~~~
On starting the AppVM, sometimes a message is displayed that the Xen PV Network Class needs to restart the system. This message can be safely ignored and closed by selecting "No".
**Caution:** These AppVMs must not be started while the corresponding TemplateVM is running, because they share the TemplateVM's license data. Even if this could work sometimes, it would be a violation of the license terms.
### Windows 10 Usage According to GDPR
If Windows 10 is used in the EU to process personal data, according to GDPR no automatic data transfer to countries outside the EU is allowed without explicit consent of the person(s) concerned, or other legal consent, as applicable. Since no reliable way is found to completely control the sending of telemetry from Windows 10, the system containing personal data must be completely shielded from the internet.
This can be achieved by installing Windows 10 on a TemplateVM with the user data directory moved to a separate drive (usually `D:`). Personal data must not be stored within the TemplateVM, but only in AppVMs depending on this TemplateVM. Network access by these AppVMs must be restricted to the local network and perhaps additional selected servers within the EU. Any data exchange of the AppVMs must be restricted to file and clipboard operations to and from other VMs in the same Qubes system.
## Windows update
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn't specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. This [comment](https://github.com/QubesOS/qubes-issues/issues/3585#issuecomment-366471111) provides useful links on updating a Windows 7 SP1 VM.
Note: if you already have Qubes Windows Tools installed the video adapter in Windows will be "Qubes video driver" and you won't be able to see the Windows Update process when the VM is being powered off because Qubes services would have been stopped by then. Depending on the size of the Windows update packs it may take a bit of time until the VM shutdowns by itself, leaving one wondering if the VM has crashed or still finalizing the updates (in dom0 a changing CPU usage - eg. shown with `xentop` - usually indicates that the VM hasn't crashed).
To avoid guessing the VM's state enable debugging (`qvm-prefs -s win7new debug true`) and in Windows' device manager (My computer -> Manage / Device manager / Display adapters) temporarily re-enable the standard VGA adapter and disable "Qubes video driver". You can disable debugging and revert to Qubes' display once the VM is updated.
## Further customization
Please see the [Customizing Windows 7 templates](/doc/windows-template-customization/) page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM).

272
user/templates/windows/windows-qubes-4-1.md Normal file
View file

@ -0,0 +1,272 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/windows-qubes-4-1/
redirect_from:
- /doc/templates/windows/windows-vm41/
- /doc/templates/windows/windows-vm41/
title: How to install Windows qubes in Qubes OS
---
You can install Windows just like any other OS as an [HVM](/doc/hvm/), if you just want something simple and you can live without some features. This works for Windows XP, 7, 8.1, 10 and 11.
Please keep in mind that Qubes Windows Tools are not supported on Windows XP.
You will get an environment in which basic functions are supported, but integration into the Qubes environment is rather restricted. The following functions will work right out of the box:
- display (1440x900 or 1280x1024 are a nice fit onto FHD hw display)
- keyboard (incl. correct mapping), pointing device
- network (emulated Realtek NIC)
- audio output and input (available even without QWT installation if `qvm-features audio-model` is set as `ich6`)
For better integration, a set of drivers and services, called Qubes Windows Tools (QWT) is available. Installation of these tools is straightforward and is described in a [separate document](/doc/templates/windows/qubes-windows-tools-4-1). QWT’s main features are:
- copy/paste between qubes
- copy files between qubes
- attaching USB devices to the qube
- attaching block devices to the qube (XEN PV disk driver must be installed)
- automatically set up networking
- automatically set up time/clock synchronization
- XEN PV drivers (some of them optional)
- optional user migration from `C:` to the qubes’ private volume (to be able use the qubes as a TemplateVM).
- seamless mode (Windows 7 only for now)
- propagating keyboard layout ?
## Importing a Windows VM from an earlier version of Qubes
- Importing from R3.2 or earlier will not work, because Qubes R3.2 has the old stubdomain by default and this is preserved over backup and restore (as Windows otherwise won't boot.
- Importing from R4.0 should work, see [Migrate backups of Windows VMs created under Qubes R4.0 to R4.1](/doc/templates/windows/migrate-to-4-1).
## Windows VM installation
**qvm-create-windows-qube**: An unofficial, third-party tool for automating this process is available [here](https://github.com/elliotkillick/qvm-create-windows-qube). (Please note that this tool has not been reviewed by the Qubes OS Project. Use it at your own risk.)
However, if you are an expert or want to do it manually you may continue below.
**Notes:**
- The instructions may work on other versions than Windows 7, 8.1, 10 and 11 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7, 8.1, 10 and 11 x64. For installation, see [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1).
**Provide installation media**
Have the Windows ISO image (preferrably the 64-bit version) downloaded in some qube.
Windows ISOs can be downloaded directly from Microsoft (eg. [here](https://www.microsoft.com/en-us/software-download/windows10ISO) for Win10), or selected and downloaded via the [Windows Media Creation Tool](https://go.microsoft.com/fwlink/?LinkId=691209). You should, however, regard the downloaded image to be untrustworthy, since there is no reliable way to check that the download was not somehow compromised (see the discussion in issue [Simplify Qubes Windows Tools Installation for R4.1 #7240](https://github.com/QubesOS/qubes-issues/issues/7240)).
Unofficial “debloated” ISOs from projects like reviOS 18 or ameliorated 10 can be found on the net, although obviously you should consider them even “unsafer” than MS provided ISOs. Alternatively, one could download an official ISO and run scripts/apply patches before installation. Some of the “tweaks” might end up being too much depending on the qube’s planned usage though (eg. no appx functionality in ameliorated windows - so the installation of Windows Store apps is impossible, even with powershell).
**Create Windows VM**
Create a VM named WindowsNew in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH). This can be done in either of two ways:
- Using Qube Manager
In order to create the new qube, select the command Qube -> New Qube in the Qube Manager::
- Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template)
- Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)`
- Template: `(none)`
- Networking: `sys-firewall (default)`
- Launch settings after creation: check
- Click "OK".
- Settings:
- Basic:
- System storage: 60.0+ GB
- Advanced:
- Include in memory balancing: uncheck
- Initial memory: 4096+ MB
- Kernel: `(none)`
- Mode: `HVM`
- Click "Apply".
After creation, set `qvm-prefs WindowsNew qrexec_timeout 7200` via CLI in a dom0 terminal.
- Using CLI in a dom0 terminal
- This can also be done via the following CLI commands in dom0, for a standalone qube:
~~~
qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew
~~~
and for a template:
~~~
qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew
~~~
- After creation, set the following parameters via CLI in a dom0 terminal:
~~~
qvm-volume extend WindowsNew:root 60g
qvm-prefs WindowsNew memory 4096
qvm-prefs WindowsNew maxmem 4096
qvm-prefs WindowsNew kernel ''
qvm-prefs WindowsNew qrexec_timeout 7200
~~~
These parameters are set for the following reasons:
- A typical Windows installation requires between 25GB up to 60GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to at least 60GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
- Setting memory to 4096MB may work in most cases, but using 6144MB (or even 8192MB) may reduce the likelihood of crashes during installation, especially for Windows 10 or 11. This is important as Windows qubes have to be created without memory balancing, as requested by the parameter settings described above.
- The Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
~~~
/var/log/xen/console/hypervisor.log:
p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
(XEN) domain_crash called from p2m-pod.c:1218
(XEN) Domain 120 (vcpu#0) crashed on cpu#3:
~~~
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing), or 6144MB / 8192MB, as recommended above.
- Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence. This is done by setting the qube's kernel to an empty value.
- After creating the new qube, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like `chkdsk` won't complete on restart before `qrexec_timeout` automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher `qrexec_timeout`, `chkdsk` or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation. So set the parameter via the following CLI command from a dom0 terminal, because the Qube manager does not support this setting:
**Start Windows VM**
- The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/standalones-and-hvms/#installing-an-os-in-an-hvm). Now boot the newly created qube from the Windows installation media. In the Qubes Manager:
- Select the new qube, in this example "WindowsNew".
- Switch to the "Advanced" tab.
- Click "Boot from CDROM":
- "from file in qube":
- Select the qube that has the ISO.
- Select ISO by clicking "...".
- Click "OK" to boot into the windows installer.
This can also be done via the following CLI command in dom0 (assuming that the Windows installer ISO is stored in the directory `/home/user/` in the AppVM `untrusted`):
~~~
qvm-start --cdrom=untrusted:/home/user/windows_install.iso WindowsNew
~~~
- Install Windows on the new VM
- At the first start, the Windows logo may be briefly shown, and then a black screen with a blinking cursor may appear and stay for a few minutes. This is normal, and you just have to wait until the installation window appears.
- The installation will run mostly as usual, but automatic reboots will halt the qube - just restart it again and again until the installation is finished. Note, however, that for these restarts, the parameter `--cdrom` **must not** be used, because otherwise the installation will start all over.
- Install on first disk.
- **For Windows 11 only**: Windows 11 requires TPM 2.0, which currently is not supported from Xen. In Order to install Windows 11 under Qubes, the check for TPM in the Windows installer has to be disabled:
- When you start setup without having a TPM, you get an error message like *This PC does not fulfil the minimum requirements for Windows 11*.
- Typing Shift-F10 then opens a console window.
- Here you type `regedit` to start the registry editor.
- There you position to the key `HKEY_LOCAL_MACHINE\SYSTEM\Setup`.
- Now create the key `LabConfig`.
- Position to this key and create 3 DWORD values called `BypassTPMCheck`, `BypassSecureBootCheck` and `BypassRAMCheck` and set each value to `1`.
- Close the registry editor and console windows.
- In the setup window, hit the left arrow in the left upper corner. You will then return into the setup, which will continue normally and install Windows 11 without TPM 2.0.
:warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft some time.
The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft:
- When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
- Here you type `taskmgr` to start the Task Manager window so you can see all running processes.
- Expand the Task Manager by clicking the “More Details” button, and then find “Network Connection Flow.”
- Select this process and then hit the “End Task” button.
- Now you can close these newly opened windows and return to the Windows 11 setup, where you will enter local account information.
For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published:
- Enter `no@thankyou.com` (or some other senseless address) as the email address and click `Next` when Windows 11 setup prompts you to log into your Microsoft account.
- Enter any text you want in the password field and click `Sign in`. If this method works, you'll get a message saying "Oops, something went wrong."
- Click `Next`. A screen appears saying "Who's going to use this device?" This is the local account creation screen.
- Enter the username you want to use and click `Next`.
- Enter a password and click `Next`. You can leave the field blank but it's not recommended.
- On systems shipped with a Windows license, the product key may be read from flash via root in dom0:
`strings < /sys/firmware/acpi/tables/MSDM`
Alternatively, you can also try a Windows 7 license key (as of 2018/11 they are still accepted for a free upgrade to Windows 10).
- The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone WindowsNew WindowsNewbkp1`). Then, (re)start the VM via the Qubes Manager or with `qvm-start WindowsNew` from a dom0 terminal (without the `--cdrom` parameter!).
The second part of Windows' installer should then be able to complete successfully.
**After Windows installation**
- From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which could lead to corruption of the VM's disk.
~~~
powercfg -H off
~~~
Also, recent versions of Windows won’t show the CD-ROM drive after starting the qube with `qvm-start vm --cdrom ...` (or using the GUI). The solution is to disable hibernation in Windows with this command. (That command is included in QWT’s setup but it’s necessary to run it manually in order to be able to open QWT’s setup ISO/CD-ROM in Windows).
- In case you switch from `sys-firewall` to `sys-whonix`, you'll need a static IP network configuration, DHCP won't work for `sys-whonix`. Sometimes this may also happen if you keep using `sys-firewall`. In both cases, proceed as follows:
- Check the IP address allocated to the qube - either from GUI Manager, or via `qvm-ls -n WindowsNew` from a dom0 terminal (E.g. 10.137.0.x with gateway 10.138.y.z).
- In the Windows qube, open the Network manager and change the IPv4 configuration of the network interfacefrom "Automatic" to "Manual".
- Enter the Address: 10.137.0.x in our example.
- Enter the Netmask: 255.255.255.0
- Enter the Gateway: 10.138.y.z in our example.
- Enter DNS: 10.139.1.1,10.139.1.2 (the Virtual DNS addresses used by Qubes.
- Click "Apply". You should now see "Connected".
- Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'WindowsNew'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-WindowsNew.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-WindowsNew-dm.log
~~~
At that point you should have a functional and stable Windows VM, although without updates, Xen's PV drivers nor Qubes integration (see sections [Windows Update](/doc/templates/windows/windows-qubes-4-1/#windows-update) and [Xen PV drivers and Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1/#xen-pv-drivers-and-qubes-windows-tools)). It is a good time to clone the VM again.
**Installing Qubes Windows Tools**
To install Qubes Windows Tools, follow instructions in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1), but don’t forget to `qvm-clone` your qube before you install Qubes Windows Tools (QWT) in case something goes south.
**Post-install best practices**
Optimize resources for use in virtual machine as “vanilla” version of Windows are bloated; e.g.:
- set up Windows for best performance (this pc → advanced settings → …)
- think about Windows’ page file: is it needed ? should you set it with a fixed size ? maybe on the private volume ?
- disable services you don’t need
- disable networking stuff in the network adapter’s setting (eg. link discovery, file and print server, …)
- background: set a solid color
- …
For additional information on configuring a Windows qube, see the [Customizing Windows 7 templates](/doc/windows-template-customization/) page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - i.e. TemplateVM or StandaloneVM).
## Windows as a template
As described above Windows 7, 8.1, 10 and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the option `Move User Profiles` has to be selected on installation of Qubes Windows Tools. For Windows 7, before installing QWT, the private disk `D:` has to be renamed to `Q:`, see the QWT installation documentation in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1).
AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
~~~
qvm-create --class=AppVM --template=<VMname>
~~~
On starting the AppVM, sometimes a message is displayed that the Xen PV Network Class needs to restart the system. This message can be safely ignored and closed by selecting "No".
**Caution:** These AppVMs must not be started while the corresponding TemplateVM is running, because they share the TemplateVM's license data. Even if this could work sometimes, it would be a violation of the license terms.
Furthermore, if manual IP setup was used for the template, the IP address selected for the template will also be used for the AppVM, as it inherits this address from the template. Qubes, however, will have assigned a different address to the AppVM, which will have to changed to that of the template (e.g. 10.137.0.x) so that the AppVM can access the network, vis the CLI command in a dom0 terminal:
~~~
qvm-prefs WindowsNew ip 10.137.0.x
~~~
## Windows 10 and 11 Usage According to GDPR
If Windows 10 or 11 is used in the EU to process personal data, according to GDPR no automatic data transfer to countries outside the EU is allowed without explicit consent of the person(s) concerned, or other legal consent, as applicable. Since no reliable way is found to completely control the sending of telemetry from Windows 10 or 11, the system containing personal data must be completely shielded from the internet.
This can be achieved by installing Windows 10 or 11 in a TemplateVM with the user data directory moved to a separate drive (usually `Q:`). Personal data must not be stored within the TemplateVM, but only in AppVMs depending on this TemplateVM. Network access by these AppVMs must be restricted to the local network and perhaps additional selected servers within the EU. Any data exchange of the AppVMs must be restricted to file and clipboard operations to and from other VMs in the same Qubes system.
## Windows update
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn't specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. For Windows 7, you may find the necessary updates bundled at [WinFuture Windows 7 SP1 Update Pack 2.107 (Vollversion)](https://10gbit.winfuture.de/9Y6Lemoxl-I1_901xOu6Hg/1648348889/2671/Update%20Packs/2020_01/WinFuture_7SP1_x64_UpdatePack_2.107_Januar_2020-Vollversion.exe). At your own risk you may use such an installation image with bundled updates, but generally we do not recommend this way for security reasons - so, if you do it anyhow, check that you get this image from a source that you trust, which may be quite different from that one named here!
Note: if you already have Qubes Windows Tools installed the video adapter in Windows will be "Qubes video driver" and you won't be able to see the Windows Update process when the VM is being powered off because Qubes services would have been stopped by then. Depending on the size of the Windows update packs it may take a bit of time until the VM shutdowns by itself, leaving one wondering if the VM has crashed or still finalizing the updates (in dom0 a changing CPU usage - eg. shown with the domains widget in the task bar, or with `xentop` - usually indicates that the VM hasn't crashed).
To avoid guessing the VM's state enable debugging (`qvm-prefs -s WindowsNew debug true`) and in Windows' device manager (My computer -> Manage / Device manager / Display adapters) temporarily re-enable the standard VGA adapter and disable "Qubes video driver". You can disable debugging and revert to Qubes' display once the VM is updated.
## Troubleshooting
**Windows 7 - USB drives are not visible in your domain**
After Qubes Windows Tools have been installed on your Windows 7 system, please install the [Chipset_Driver_X2NF0_WN_2.1.39.0_A03.EXE driver](https://web.archive.org/web/20221007093126/https://dl.dell.com/FOLDER01557883M/3/Chipset_Driver_X2NF0_WN_2.1.39.0_A03.EXE). Then shut down your domain.
From now on you should be able to attach your USB drive by passing it from your *Qubes Devices* menu as a *USB device* rather than *Data (Block) Device*
This procedure has been tested on Windows 7 installed as a TemplateVM. Different combinations (such as StandaloneVM or different Windows versions) have not been tested.

19
user/templates/windows/windows.md Normal file
View file

@ -0,0 +1,19 @@
---
lang: en
layout: doc
permalink: /doc/templates/windows/
redirect_from:
- /doc/windows/
title: Windows qubes
---
Like any other unmodified OSes, Windows can be installed in Qubes as an [HVM](/doc/standalones-and-hvms/) domain.
Qubes Windows Tools (QWT) are then usually installed to provide integration with the rest of the Qubes system; they also include Xen's paravirtualized (PV) drivers to increase performance compared to qemu emulated devices. Alternatively, only Xen's PV drivers can be installed if integration with Qubes isn't required or if the tools aren't supported on a given version of Windows. In the latter case, one would have to [enable inter-VM networking](/doc/firewall/#enabling-networking-between-two-qubes) to be able to exchange files with HVMs.
For more information about Windows VMs in Qubes OS, please see the following external resources:
* [Installing and Using Windows-based VMs](/doc/templates/windows/windows-qubes-4-1/)
* [Installing and Using Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1/)
* [Create a Gaming HVM in Qubes](https://forum.qubes-os.org/t/create-a-gaming-hvm/19000)
* [Migrate backups of Windows VMs created under Qubes R4.0 to R4.1](/doc/templates/windows/migrate-to-4-1/)

2
user/templates/xfce-templates.md
View file

@ -13,7 +13,7 @@ title: Xfce templates
---
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](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/), or [Gentoo](/doc/templates/gentoo/).
## Installation

4
user/troubleshooting/updating-debian-and-whonix.md → user/troubleshooting/debian-and-whonix-update-troubleshooting.md
View file

@ -1,7 +1,9 @@
---
lang: en
layout: doc
permalink: /doc/troubleshooting/updating-debian-and-whonix/
permalink: /doc/debian-and-whonix-update-troubleshooting/
redirect_from:
- /doc/troubleshooting/updating-debian-and-whonix/
ref: 98
title: Updating Debian and Whonix
---

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

@ -121,5 +121,5 @@ Here are the steps to fix this. Note that this allows sys-net and sys-usb to tak
1. Change the virtualization mode of sys-net and sys-usb to "PV"
2. Add `qubes.enable_insecure_pv_passthrough` to `GRUB_CMDLINE_LINUX` in `/etc/default/grub`
3. Run `sudo grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg`
3. Run `sudo grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg`. If you are using a non-UEFI BIOS (where `/boot/efi/EFI` doesn't exist), use the command `sudo grub-mkconfig -o /boot/grub2/grub.cfg` instead.
4. Reboot

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

@ -133,7 +133,7 @@ Some laptops cannot read from an external boot device larger than 8GB. If you en
## Installation completes successfully but then boot loops or hangs on black screen
There is a [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
There is a [common bug in UEFI implementation](https://xen.markmail.org/message/f6lx2ab4o2fch35r) affecting mostly Lenovo systems, but probably some others too.
While some systems need `mapbs` and/or `noexitboot` disabled to boot, others require them enabled at all times.
Although these are enabled by default in the installer, they are disabled after the first stage of a successful install.
You can re-enable them either as part of the install process:
@ -177,7 +177,7 @@ Or if you have already rebooted after the first stage install and have encounter
## Installation completes successfully but then system crash/restarts on next boot
Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76).
Some Dell systems and probably others have [another bug in UEFI firmware](https://markmail.org/message/amw5336otwhdxi76).
These systems need `efi=attr=uc` enabled at all times.
Although this is enabled by default in the installer, it is disabled after the first stage of a successful install.
You can re-enable it either as part of the install process: