Git-Mirrors
/
qubes-doc
mirror of https://github.com/QubesOS/qubes-doc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into pr-1334

This commit is contained in:
Andrew David Wong 2023-12-20 10:28:06 -08:00
parent f6db6fc2da 8f923e30fb
commit d2791f2296
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
36 changed files with 1936 additions and 940 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_dev/conf.py
View File

@ -186,7 +186,7 @@ htmlhelp_basename = 'QubesOSdev'
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
'python': ('https://docs.python.org/', None),
# 'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
}

2
developer/building/development-workflow.md
View File

@ -15,7 +15,7 @@ A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
assumes you're using qubes-builder to build Qubes.
# Repositories and committing Code
## Repositories and committing Code
Qubes is split into a bunch of git repos. These are all contained in the
`qubes-src` directory under qubes-builder. Subdirectories there are separate

98
developer/debugging/profiling.md
View File

@ -1,98 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/profiling/
redirect_from:
- /en/doc/profiling/
- /doc/Profiling/
- /wiki/Profiling/
ref: 48
title: Python profiling
---
This is a python profiling primer.
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
## Requirements
~~~
yum install gprof2dot graphviz
git clone http://git.woju.eu/qubes/profiling.git
~~~
If you profile something in dom0, move `Upload.sh` from the repository to dom0:
~~~
mkdir -p ~/profiling
qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
~~~
- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
## Workflow
### Identify function responsible for some slow action
You have to select the area in which you suspect less than optimal performance. If you do not narrow the area, graphs may be unreadable.
### Replace suspect function with probe
Replace
```python
def foo(self, bar):
# function content
```
with
```python
def foo(self, *args, **kwargs):
profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
def real_foo(self, bar):
# function content
```
### Run application
Beware that some functions may be called often. For example `qubesmanager/main.py:update_table` gets run once per second. This will produce one pstat file per second.
Remember to revert your changes to the application afterwards.
### Upload statistics
If you are in dom0:
~~~
cd ~/profiling
./Upload.sh
~~~
### Analyse
~~~
make
~~~
For every `${basename}.pstats` this will produce `${basename}.txt` and `${basename}.svg`. SVG files contain call graphs. Text files contain lists of all functions, sorted by cumulative execution time. You may also try `make all-png`.
~~~
make index.html
~~~
This creates `index.html` with all SVG graphics linked to TXT files, ready for upload.
~~~
make REMOTE=example.com:public_html/qubes/profiling/ upload
~~~
## Example
This example is from `qubes-manager` (`qubesmanager/main.py`).
!["update\_table-20140424-170010.svg"](//attachment/doc/update_table-20140424-170010.svg)
It is apparent that the problem is around `get_disk_usage`, which calls something via `subprocess.call`. It does this 15 times, probably once per VM.

6
developer/debugging/windows-debugging.md
View File

@ -47,7 +47,7 @@ socat $tty1,raw $tty2,raw
...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- Reboot the *target* VM.
- Run the above shell script in dom0.
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
@ -57,7 +57,7 @@ socat $tty1,raw $tty2,raw
Waiting to reconnect...
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
Kernel Debugger connection established.
Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
Executable search path is:
... Retry sending the same data packet for 64 times.
The transport connection between host kernel debugger and target Windows seems lost.
@ -206,7 +206,7 @@ parse:
> Waiting to reconnect...
> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
> Kernel Debugger connection established.
> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
> Symbol search path is: srv*c:\symbols*https://msdl.microsoft.com/download/symbols
> Executable search path is:
> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532

4
developer/general/devel-books.md
View File

@ -26,6 +26,6 @@ Below is a list of various books that might be useful in learning some basics ne
- _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
- Useful books about Python:
- _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
- _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
- _[Programming in Python 3](https://www.qtrac.eu/py3book.html)_, by Mark Summerfield
- _[Rapid GUI Programming with Python and Qt](https://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
(Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

102
developer/general/developing-gui-applications.md Normal file
View File

@ -0,0 +1,102 @@
---
lang: en
layout: doc
permalink: /doc/developing-gui-applications/
ref: 333
title: Developing Qubes OS GUI tools
---
In order to avoid installing Qubes OS frontend tools you are working on in your own `dom0` or just to test them with less problems, you can use the mock Qubes object from the `qubesadmin` package.
## Running programs using mock Qubes object
Where you would normally provide the Qubes object, use the `qubesadmin.tests.mock_app` package and one of the mock Qubes objects from it.
For example, the following code can be used to run the `qui-domains` tool using the mock Qubes object (this code would replace the initial part of the main function):
```python
def main():
''' main function '''
# qapp = qubesadmin.Qubes()
# dispatcher = qubesadmin.events.EventsDispatcher(qapp)
# stats_dispatcher = qubesadmin.events.EventsDispatcher(qapp, api_method='admin.vm.Stats')
import qubesadmin.tests.mock_app as mock_app
qapp = mock_app.MockQubesComplete()
dispatcher = mock_app.MockDispatcher(qapp)
stats_dispatcher = mock_app.MockDispatcher(
qapp, api_method='admin.vm.Stats')
# continue as normal
```
To run a mocked program without installing it in a qube, remember to extend PYTHONPATH appropriately, for example:
```bash
~/qubes-sources/manager $ PYTHONPATH=../core-admin-client:. python3 qui/tray/domains.py
```
The mock object does not provide events (yet).
Note: in order to see all qubes-relevant icons (like VM icons), install the `qubes-artwork` package.
## How does it actually work
The mock Qubes object has a collection of expected Qubes RPC calls and the responses that a real system would provide. Writing these calls manually is a bit tedious, given that most frontend tools query a lot of qube properties. For example, on a medium-sized system, initializing Qube Manager involves about 300 separate RPC calls.
If you need more calls, you can add them to the mock object using the following syntax (the following example adds listing available vm kernels):
```python
mock_app.expected_calls[('dom0', 'admin.pool.volume.List', 'linux-kernel', None)] = \
b'0\x006.1.57-1.fc37\n6.1.43-1.fc37\ncustom_kernel\n'
```
If error should be thrown, you need to provide the error code and name, for example:
```python
mock_app.expected_calls[("vmname", "admin.vm.property.Get", "property_name", None)] = \
b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00'
```
For details of particular calls, you can use [Extending the mock Qubes object].
## Available mocks
Three mocks are available in the `mock_app` file:
* MockQubes, an extremely bare-bones Qubes testing instance, with just dom0, sys-net, and one template (fedora-36).
* MockQubesComplete, a more complex setup [![Qubes Manager running MockQubesComplete](/attachment/doc/doc-mock-app-ex1.png)](/attachment/doc/doc-mock-app-ex1.png)
* MockQubesWhonix, the setup above extended with several Whonix-related qubes
## Extending the mock Qubes object
To collect information to modify this script, you can use the wrapper function to wrap and output all qubesd calls used by a program running on a live qubes instance.
```python
qapp = qubesadmin.Qubes()
import qubesadmin.tests.mock_app as mock_app
qapp.qubesd_call = mock_app.wrapper(qapp.qubesd_call)
qapp._parse_qubesd_response = mock_app.wrapper(qapp._parse_qubesd_response)
```
## Writing tests
The same mock Qubes can also be used to write tests. You can use the wrappers above to check which calls are made when certain actions are performed, and add them to the mock objects in the following way:
```python
# this is an excerpt from tests for Qubes Global Config tool
clockvm_combo.set_active_id('test-blue')
mock_qapp.expected_calls[('dom0', 'admin.property.Set',
'clockvm', b'test-blue')] = b'0\x00'
basics_handler.save()
```
If the call is made correctly, the test will continue successfully; if an unexpected call is made, the test will fail.
Caution: the mock Qubes object does not react to changes like a normal Qubes object does. Further queries to the test object will continue to return initial values.

2
developer/general/gsoc.md
View File

@ -259,7 +259,7 @@ REMOVED as of January 2020: work is being done on this
**Project**: Unikernel based firewallvm with Qubes firewall settings support
**Brief explanation**: [blog post](http://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
**Brief explanation**: [blog post](https://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
**Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first.

63
developer/releases/4_2/release-notes.md
View File

@ -1,43 +1,54 @@
---
layout: doc
title: Qubes OS 4.2 release notes
title: Qubes OS 4.2.0 release notes
permalink: /doc/releases/4.2/release-notes/
---
_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
## New features and improvements since Qubes 4.1
- dom0 updated to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982))
- Xen updated to 4.17
- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982))
- Xen upgraded to version 4.17
- Default Debian template upgraded to Debian 12
- Default Fedora and Debian templates use Xfce instead of GNOME ([#7784](https://github.com/QubesOS/qubes-issues/issues/7784))
- SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239))
- several GUI applications rewritten, including:
- applications menu (available as preview in R4.1 too) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677))
- global settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898))
- new qube dialog
- system updater ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
- grub.cfg stored in /boot/grub2/grub.cfg in UEFI boot to ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985))
- pipewire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358))
- fwupd integration to allow firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855))
- optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415))
- official packages built using rewritten qubes-builder (qubes-builderv2) ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486))
- Split GPG and Split SSH management in Qubes Global Settings
- Several GUI applications rewritten (screenshots below), including:
- Applications Menu (also available as preview in R4.1) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677))
- Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898))
- Create New Qube
- Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985))
- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358))
- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855))
- Optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415))
- Official packages built using Qubes Builder v2 ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486))
- Split GPG management in Qubes Global Settings
- Qrexec services use new qrexec policy format by default (but old format is still supported) ([#8000](https://github.com/QubesOS/qubes-issues/issues/8000))
- Improved keyboard layout switching
For a full list, including more detailed descriptions, please see
[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed).
For a full list, including more detailed descriptions, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed). Below are some screenshots of the new and improved Qubes GUI tools.
The new Qubes OS Update tool:
[![Screenshot of the Qubes OS Update tool](/attachment/site/4-2_update.png)](/attachment/site/4-2_update.png)
The new Qubes OS Global Config tool:
[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_1.png)](/attachment/site/4-2_global-config_1.png)
[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_2.png)](/attachment/site/4-2_global-config_2.png)
The new Qubes OS Policy Editor tool:
[![Screenshot of the Qubes OS Policy Editor tool](/attachment/site/4-2_policy-editor.png)](/attachment/site/4-2_policy-editor.png)
## Known issues
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062))
For a full list of known 4.2 issues with open bug reports, please see
[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+4.2%22+label%3A%22T%3A+bug%22).
We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately
after installation in order to apply any and all available bug fixes.
For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes.
## Download
See [downloads](/downloads/).
All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page.
## Installation instructions
@ -45,8 +56,4 @@ See the [installation guide](/doc/installation-guide/).
## Upgrading
The in-place upgrade procedure is not ready yet ([#7832](https://github.com/QubesOS/qubes-issues/issues/7832)). Currently, R4.2 can be tested by performing a clean installation.
```
TODO: Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/).
```
Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/).

4
developer/releases/4_2/schedule.md
View File

@ -15,4 +15,6 @@ policy](/doc/version-scheme/#release-schedule).
| Date | Stage |
| ----------:| ----------------------------------------- |
| 2023-06-02 | 4.2.0-rc1 release |
| TODO | current-testing freeze before 4.2.0-rc2 |
| 2023-08-28 | 4.2.0-rc2 release |
| 2023-09-03 | 4.2.0-rc3 release |
| 2023-10-13 | 4.2.0-rc4 release |

70
developer/releases/version-scheme.md
View File

@ -27,6 +27,13 @@ notable exception, as upstream OSes almost always have their own release
schedules.) Bug fixes are allowed in all releases, and backward-compatible
changes are allowed in all major and minor releases.
Qubes OS minor releases generally include new features, new templates, and
occasionally new defaults, but they are still backward-compatible in the sense
that qubes and features that worked in the previous release still function,
though the UI may be different in some cases. In general, deprecated features
are removed only in major releases, and in-place upgrades between major versions
are not guaranteed.
Following standard practice, **version** refers to any build that has been
assigned a version name or number, e.g., `3.2-rc2`, `4.0.4`, `4.1-beta1`. By
contrast, **release** refers to any version that is intended for consumption by
@ -52,47 +59,48 @@ Qubes OS. Another remix may have its own version series.
## Release versioning
Qubes OS as a whole is released from time to time. When preparing a new
release, we decide on the `<major>.<minor>` numbers (e.g., `3.0`). We then
publish the first release candidate, `3.0-rc1`. When we feel that enough
progress has been made, we'll release `3.0-rc2` and so on. All these versions
(not yet releases) are considered unstable and not for production use. You are
welcome to [help us test](/doc/testing/) these versions.
Qubes OS as a whole is released from time to time. When preparing a new release,
we decide on the `<major>.<minor>` numbers (e.g., `3.0`, which is short for
`3.0.0`). We then publish the first release candidate, e.g., `3.0.0-rc1`. When
we feel that enough progress has been made, we'll release `3.0.0-rc2` and so on.
All these versions (which are not yet releases) are considered unstable and are
not intended for production use. You are welcome to [help us
test](/doc/testing/) these versions.
When enough progress has been made, we announce the first stable release, e.g.
`3.0.0`. This not only a version but an actual release. It is considered stable
and we commit to supporting it according to our [support
`3.0.0`. This is not only a version but an actual release. It is considered
stable, and we commit to supporting it according to our [support
schedule](/doc/supported-releases/). Core components are branched at this
moment and bug fixes are backported from the master branch. Please see [help,
moment, and bug fixes are backported from the master branch. Please see [help,
support, mailing lists, and forum](/support/) for places to ask questions about
stable releases. No major features and interface incompatibilities are to be
stable releases. No major features or interface incompatibilities are to be
included in this release. We release bug fixes as patch releases (`3.0.1`,
`3.0.2`, and so on), while backward-compatible enhancements and new features
are introduced in the next minor release (e.g., `3.1`). Any
backward-incompatible changes are introduced in the next major release (e.g.,
`4.0`).
Issues in our [issue tracker](/doc/issue-tracking/) are sorted by release
[milestones](/doc/issue-tracking/#milestones).
Please see [issue tracking](/doc/issue-tracking/) for information about how
releases are handled in the issue tracker.
## Release schedule
There is no specific schedule for releases other that more general roadmap.
When time comes, Supreme Committee declares feature freeze and tags `-rc1` and
releases ISO image. From this time on, no new features are accepted. Also a
strict time schedule kicks in.
There is no specific schedule for releases other than a general roadmap.
When the time comes, we declare a feature freeze, tag `-rc1`, and
release an ISO. From this point on, no new features are accepted, and our
schedule begins.
Each release candidate period is as follows. For the first two weeks we accept
and assign bug reports to be fixed before next release candidate. For the next
two weeks we generally focus on fixing assigned bug reports, so issues
discovered during this time may be postponed until later RC. Finally after that
there is one week of current-testing freeze, during which time no new packages
are released, in hope that they will be installed by wider user base and
tested.
Each release candidate period is as follows: For the first two weeks, we accept
and assign bug reports to be fixed before the next release candidate. For the
next two weeks, we generally focus on fixing assigned bug reports, so issues
discovered during this period may be postponed until a later RC. Finally,
there is a one week current-testing freeze, during which time no new packages
are released, in the hope that they will be installed and tested by wider user
base.
The next RC is released five weeks after the former. All packets are published
in `current` repository and the cycle starts over. There should always be at
least one release candidate before the final release.
The next RC is released five weeks after the former. All packages are published
in the `current` repository, and the cycle starts over. There should always be
at least one release candidate before the final release.
| Stage | Duration |
| ------------------------ | --------- |
@ -100,11 +108,11 @@ least one release candidate before the final release.
| bug fixing | two weeks |
| `current-testing` freeze | one week |
Starting with second cycle (that is, after `-rc1`) two weeks into the cycle
(after primary bug-reporting period) the Supreme Committee decides whether
there should be another RC. If, based on remaining issues, the Committee
decides to release final, then the Committee agrees upon the release date,
which should be no later than a week after.
Starting with the second cycle (that is, after `-rc1`), two weeks into the cycle
(after the primary bug-reporting period), we decide whether there should be
another RC. If, based on the bugs that have been reported, we decide that the
latest RC will be designated as the stable release, then we decide on its
release date, which should be no more than one week later.
[![Release cycle](/attachment/doc/release-cycle.svg)](/attachment/doc/release-cycle.svg)

70
developer/services/qrexec.md
View File

@ -86,25 +86,27 @@ Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is
### Policy files
The dom0 directory `/etc/qubes-rpc/policy/` contains a file for each available RPC action that a VM might call.
Together the contents of these files make up the RPC access policy database.
The dom0 directory `/etc/qubes/policy.d/` contains files that set policy for each available RPC action that a VM might call.
For example, `/etc/qubes/policy.d/90-default.policy` contains the default policy settings.
When making changes to existing policies it is recommended that you create a *new* policy file starting with a lower number, like `/etc/qubes/policy.d/30-user.policy`.
You may keep your custom policies in one file like `/etc/qubes/policy.d/30-user.policy`, or you may choose to have multiple files, like `/etc/qubes/policy.d/10-copy.policy`, `/etc/qubes/policy.d/10-open.policy`.
Together the contents of these files make up the RPC access policy database: the files are merged, with policies in lower number files overriding policies in higher numbered files.
Policies are defined in lines with the following format:
```
srcvm destvm (allow|deny|ask[,default_target=default_target_VM])[,user=user_to_run_as][,target=VM_to_redirect_to]
service-name|* +argument|* source destination action [options]
```
You can specify srcvm and destvm by name or by one of the reserved keywords such as `@anyvm`, `@dispvm`, or `dom0`.
(Of these three, only `@anyvm` keyword makes sense in the srcvm field.
You can specify the source and destination by name or by one of the reserved keywords such as `*`, `@dispvm`, or `dom0`.
(Of these three, only `*` keyword makes sense in the source field.
Service calls from dom0 are currently always allowed, and `@dispvm` means "new VM created for this particular request," so it is never a source of request.)
Other methods using *tags* and *types* are also available (and discussed below).
Whenever a RPC request for an action is received, the domain checks the first matching line of the relevant file in `/etc/qubes-rpc/policy/` to determine access:
Whenever a RPC request for an action is received, the domain checks the first matching line of the files in `/etc/qubes/policy.d/` to determine access:
whether to allow the request, what VM to redirect the execution to, and what user account the program should run under.
Note that if the request is redirected (`target=` parameter), policy action remains the same -- even if there is another rule which would otherwise deny such request.
If no policy rule is matched, the action is denied.
If the policy file does not exist, the user is prompted to create one.
If there is still no policy file after prompting, the action is denied.
In the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself -- in which case it must have executable permission set (`chmod +x`):
- `/etc/qubes-rpc/RPC_ACTION_NAME` when you make it in the template qube;
@ -145,14 +147,14 @@ For DisposableVMs, `@dispvm:DISP_VM` is very similar to `@dispvm` but forces usi
For example:
```
anon-whonix @dispvm:anon-whonix-dvm allow
* * anon-whonix @dispvm:anon-whonix-dvm allow
```
Adding such policy itself will not force usage of this particular `DISP_VM` - it will only allow it when specified by the caller.
But `@dispvm:DISP_VM` can also be used as target in request redirection, so _it is possible_ to force particular `DISP_VM` usage, when caller didn't specify it:
```
anon-whonix @dispvm allow,target=@dispvm:anon-whonix-dvm
* * anon-whonix @dispvm allow target=@dispvm:anon-whonix-dvm
```
Note that without redirection, this rule would allow using default Disposable VM (`default_dispvm` VM property, which itself defaults to global `default_dispvm` property).
@ -166,15 +168,15 @@ By default no VM is selected, even if the caller provided some, but policy can s
For example:
```
work-mail work-archive allow
work-mail @tag:work ask,default_target=work-files
work-mail @default ask,default_target=work-files
* * work-mail work-archive allow
* * work-mail @tag:work ask default_target=work-files
* * work-mail @default ask default_target=work-files
```
The first rule allow call from `work-mail` to `work-archive`, without any confirmation.
The first rule allows calls from `work-mail` to `work-archive`, without any confirmation.
The second rule will ask the user about calls from `work-mail` VM to any VM with tag `work`.
And the confirmation dialog will have `work-files` VM chosen by default, regardless of the VM specified by the caller (`work-mail` VM).
The third rule allow the caller to not specify target VM at all and let the user choose, still - from VMs with tag `work` (and `work-archive`, regardless of tag), and with `work-files` as default.
The third rule allows the caller to not specify target VM at all and let the user choose, still - from VMs with tag `work` (and `work-archive`, regardless of tag), and with `work-files` as default.
### RPC services and security
@ -213,9 +215,16 @@ With arguments, it is easier to write more precise policies using the "allow" an
(Writing too many "ask" policies offloads additional decisions to the user.
Generally, the fewer choices the user must make, the lower the chance to make a mistake.)
Each specific argument that we want to use needs its own policy in dom0 at a path like `/etc/qubes-rpc/policy/RPC_ACTION_NAME+ARGUMENT`.
So for instance, we might have policies called `test.Device`, `test.Device+device1` and `test.Device+device2`.
If the policy for the specific argument is not set (that is, if no file exists for `RPC_ACTION_NAME+ARGUMENT`), then dom0 uses the default policy with no argument for this service.
The argument is specified in the second column of the policy line, as +ARGUMENT.
If the policy uses "\*" as an argument, then it will match any argument (including no argument).
As rules are processed in order, any lines with a specific argument below the line with the wildcard argument will be ignored.
So for instance, we might have policies which are different depending on the argument:
```
Device +device1 * * allow
Device +device2 * * deny
Device * * * ask
```
When calling a service that takes an argument, just add the argument to the service name separated with `+`.
@ -265,10 +274,10 @@ ln -s /usr/bin/our_test_add_server /etc/qubes-rpc/test.Add
```
The administrative domain will direct traffic based on the current RPC policies.
In dom0, create a file at `/etc/qubes-rpc/policy/test.Add` containing the following:
In dom0, create a file at `/etc/qubes/policy.d/30-test.policy` containing the following:
```
@anyvm @anyvm ask
test.Add * * * ask
```
This will allow our client and server to communicate.
@ -312,17 +321,15 @@ Make sure the file is executable!
(The service argument is already sanitized by qrexec framework.
It is guaranteed to not contain any spaces or slashes, so there should be no need for additional path sanitization.)
Now we create three policy files in dom0.
See the table below for details.
Now we create the policy file in dom0, at `/etc/qubes/policy.d/30-test.policy`.
The contents of the file are below.
Replace "source_vm1" and others with the names of your own chosen domains.
|------------------------------------------------------------------------|
| Path to file in dom0 | Policy contents |
|-------------------------------------------+----------------------------|
| /etc/qubes-rpc/policy/test.File | @anyvm @anyvm deny |
| /etc/qubes-rpc/policy/test.File+testfile1 | source_vm1 target_vm allow |
| /etc/qubes-rpc/policy/test.File+testfile2 | source_vm2 target_vm allow |
|------------------------------------------------------------------------|
```
test.File +testfile1 source_vm1 target_vm allow
test.File +testfile2 source_vm2 target_vm allow
test.File * * * deny
```
With this done, we can run some tests.
Invoke RPC from `source_vm1` via
@ -332,11 +339,12 @@ Invoke RPC from `source_vm1` via
```
We should get the contents of `/home/user/testfile1` printed to the terminal.
Invoking the service from `source_vm2` should work the same, and `testfile2` should also work.
Invoking the service from `source_vm2` should result in a denial, but `testfile2` should work.
```
[user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile1
Request refused
[user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile2
```
But when invoked with other arguments or from a different VM, it should be denied.
And when invoked with other arguments or from a different VM, it should also be denied.

18
developer/system/template-implementation.md
View File

@ -10,6 +10,8 @@ ref: 58
title: Template implementation
---
## Block devices of a VM
Every VM has 4 block devices connected:
- **xvda** – base root device (/) – details described below
@ -17,7 +19,7 @@ Every VM has 4 block devices connected:
- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware
## private.img (xvdb)
### private.img (xvdb)
This is mounted as /rw and here is placed all VM private data. This includes:
@ -27,7 +29,7 @@ This is mounted as /rw and here is placed all VM private data. This includes:
**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM [are *not* copied to the child TemplateBasedVM's `/home`](/doc/templates/#inheritance-and-persistence). The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
## modules.img (xvdd)
### modules.img (xvdd)
As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
@ -39,7 +41,7 @@ Normally kernel "package" is common for many VMs (can be set using qvm-prefs). O
There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device.
# Qubes TemplateVM implementation
## Qubes TemplateVM implementation
TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
@ -50,7 +52,7 @@ There are two layers of the device-mapper snapshot device; the first one enables
![TemplateSharing2.png](/attachment/doc/TemplateSharing2.png)
## Snapshot device in Dom0
### Snapshot device in Dom0
This device consists of:
@ -61,7 +63,7 @@ The above is achieved through creating device-mapper snapshots for each version
When an AppVM is stopped the xen hotplug script checks whether the device is still in use – if it is not, the script removes the snapshot and frees the loop device.
### Changes to template filesystem
#### Changes to template filesystem
In order for the full potential of the snapshot device to be realized, every change in root.img must save the original version of the modified block in root-cow.img. This is achieved by a snapshot-origin device.
@ -69,7 +71,7 @@ When TemplateVM is started, it receives the snapshot-origin device connected as
When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.old and creates a new one (using the `qvm-template-commit` tool). The snapshot device will remain untouched due to the loop device, which uses an actual file on the disk (by inode, not by name). Linux kernel frees the old root-cow.img files as soon as they are unused by all snapshot devices (to be exact, loop devices). The new root-cow.img file will get a new inode number, and so new AppVMs will get new snapshot devices (with different names).
### Rollback template changes
#### Rollback template changes
There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch".
@ -85,7 +87,7 @@ Steps performed by **qvm-revert-template-changes**:
6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
## Snapshot device in AppVM
### Snapshot device in AppVM
Root device is exposed to AppVM in read-only mode. AppVM can write only in:
@ -99,7 +101,7 @@ volatile.img is divided into two partitions:
Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
## StandaloneVM
### StandaloneVM
Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.

18
external/os-guides/windows/windows-tools.md vendored
View File

@ -1,18 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /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/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md
ref: 86
title: Qubes Windows tools
---

9
external/os-guides/windows/windows-vm.md vendored
View File

@ -1,9 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /doc/windows-vm/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md
ref: 85
title: Installing a Windows qube
---

9
external/os-guides/windows/windows.md vendored
View File

@ -1,9 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /doc/windows/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md
ref: 129
title: Windows qubes
---

319
introduction/issue-tracking.md
View File

@ -16,11 +16,7 @@ ref: 121
title: Issue tracking
---
We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue
tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All
issues pertaining to the Qubes OS Project (including auxiliary infrastructure
such as this website) are tracked in
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
We use [GitHub Issues](https://docs.github.com/en/issues) as our [issue tracking system](https://en.wikipedia.org/wiki/Issue_tracking_system). All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as this website) are tracked in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
## How to open a new issue
@ -28,314 +24,157 @@ First, let's make sure the issue tracker is the right place.
### I need help, have a question, or want to discuss something.
We're happy to help, answer questions, and have discussions, but the issue
tracker is not the right place for these activities. Instead, please see [Help,
Support, Mailing Lists, and Forum](/support/).
We're happy to help, answer questions, and have discussions, but the issue tracker is not the right place for these activities. Instead, please see [Help, Support, Mailing Lists, and Forum](/support/).
### I see something that should be changed in the documentation.
We encourage you to submit the change yourself! Please see the [how to edit the
documentation](/doc/how-to-edit-the-documentation/) for instructions on how to
do so. If it's something you can't do yourself, please proceed to open an issue.
We encourage you to submit the change yourself! Please see the [how to edit the documentation](/doc/how-to-edit-the-documentation/) for instructions on how to do so. If it's something you can't do yourself, please proceed to open an issue.
### I would like to report a security vulnerability.
Thank you! If the vulnerability is confidential, please do not report it in our
public issue tracker. Instead, please see [Reporting Security Issues in Qubes
OS](/security/#reporting-security-issues-in-qubes-os).
Thank you! If the vulnerability is confidential, please do not report it in our public issue tracker. Instead, please see [Reporting Security Issues in Qubes OS](/security/#reporting-security-issues-in-qubes-os).
### I still want to open an issue.
Great! Thank you for taking the time and effort to help improve Qubes! To
ensure the process is efficient and productive for everyone involved, please
follow these steps:
Great! Thank you for taking the time and effort to help improve Qubes! To ensure the process is efficient and productive for everyone involved, please follow these steps:
1. Carefully read our issue tracking [guidelines](#guidelines). If your issue
would violate any of the guidelines, **stop**. Please do not submit it.
2. [Search through the existing issues](#search-tips), both open and closed,
to see if your issue already exists. If it does, **stop**. [Do not open a
duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues)
Instead, comment on the existing issue.
1. Carefully read our issue tracking [guidelines](#guidelines). If your issue would violate any of the guidelines, **stop**. Please do not submit it.
2. [Search through the existing issues](#search-tips), both open and closed, to see if your issue already exists. If it does, **stop**. [Do not open a duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) Instead, comment on the existing issue.
3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose).
4. Select the [type](#type) of issue you want to open.
5. Enter a descriptive title.
6. Do not delete the provided issue template. Fill out every applicable
section.
7. Make sure to mention any relevant documentation and other issues you've
already seen. We don't know what you've seen unless you tell us. If you
don't list it, we'll assume you haven't seen it.
8. If any sections of the issue template are *truly* not applicable, you may
remove them.
6. Do not delete the provided issue template. Fill out every applicable section.
7. Make sure to mention any relevant documentation and other issues you've already seen. We don't know what you've seen unless you tell us. If you don't list it, we'll assume you haven't seen it.
8. If any sections of the issue template are *truly* not applicable, you may remove them.
9. Submit your issue.
10. Respond to any questions the official team asks. For example, you may be
asked to provide specific logs or other additional information.
10. Respond to any questions the official team asks. For example, you may be asked to provide specific logs or other additional information.
Eventually, your issue may be closed. See [how issues get
closed](/doc/issue-tracking/#how-issues-get-closed) for details about when,
why, and how this occurs.
Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs.
## Labels, milestones, and projects
## Labels and projects
Labels, milestones, and projects are features of GitHub's issue tracking system
that we use to keep
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
Labels and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
### Labels
When an issue is first created, certain labels may automatically be applied to
it based on the type of issue the reporter selected. For example, if someone
selects the "Bug report" template, then the `T: bug` label will automatically
be applied to that issue. After that, only Qubes team members have permission
to modify [labels](https://github.com/QubesOS/qubes-issues/labels) and
[milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels
and milestones have descriptions on them that can be viewed either in their
respective lists or by hovering over them. Let's go over some of the most
important ones.
When an issue is first created, certain [labels](https://github.com/QubesOS/qubes-issues/labels) may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones.
#### Type
There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`.
- `T: bug` --- Type: bug report. A problem or defect resulting in unintended
behavior in something that exists.
- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist
**or** improvement of existing functionality.
- `T: task` --- Type: task. An action item that is neither a bug nor an
enhancement.
- `T: bug` --- Type: bug report. A problem or defect resulting in unintended behavior in something that exists.
- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality.
- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement.
Every open issue should have **exactly one** type. An open issue should not
have more than one type, and it should not lack a type entirely. Bug reports
are for problems in things that already exist. If something doesn't exist yet,
but you think it ought to exist, then use `T: enhancement` instead. If
something already exists, but you think it could be improved in some way, you
should again use `T: enhancement`. `T: task` is for issues that fall under
under neither `T: bug` nor `T: enhancement`.
Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`.
#### Priority
There are several issue **priority** levels ranging from `P: minor` to `P:
blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for
the full list). Every open issue should have **exactly one** priority. An open
issue should not have more than one priority, and it should not lack a priority
entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how
the developers use these priorities.
There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have **exactly one** priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities.
#### Component
There are many **component** labels, each beginning with `C:` (see
[here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the
full list). Every open issue should have **at least one** component. An open
issue may have more than one component, but it should not lack a component
entirely. When no other component applies, use `C: other`.
There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
#### Affected release
A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects
the corresponding Qubes OS release. An issue can have more than one of these
labels if it affects multiple releases.
### Milestones
The issue tracker has several
[milestones](https://github.com/QubesOS/qubes-issues/milestones). Individual
issues can be assigned to milestones. The issue tracker does not allow an issue
to be assigned to more than one milestone. If an issue is already assigned to a
milestone, assigning it to a different one will *replace* the existing
milestone assignment. Each milestone has a progress indicator showing how close
that milestone is to completion.
Most milestones correspond to specific Qubes OS releases. The Qubes developers
decide which issues will be assigned to specific milestones. The general idea
is that each milestone's progress indicator should provide a rough idea of how
much progress has been made on that milestone and how much work remains until
the milestone is complete. Most issues will not be assigned to any milestone at
all until a Qubes developer manually assigns it to one. While anyone is free to
open an issue, this does not create an obligation on the Qubes developers to
act on that issue. Every open issue should be understood to be merely "under
consideration" unless or until a Qubes developer decides to assign it to a
milestone. Issues that are assigned to a milestone are issues that either the
Qubes developers or another contributor plans to complete *for* that milestone.
The Qubes developers reserve the right to modify or remove milestones at any
time at their discretion.
A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases.
### Projects
The issue tracker has several
[projects](https://github.com/QubesOS/qubes-issues/projects). A project is a
way to create a group of multiple related issues. This is the preferred method
of grouping issues, whereas trying to use normal issues as "meta-issues" or
"epics" is discouraged.
The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). A project is a way to create a group of multiple related issues. This is the preferred method of grouping issues, whereas trying to use normal issues as "meta-issues" or "epics" is discouraged.
## Search tips
[Search both open and closed
issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue)
For example, you may be experiencing a bug that was just fixed, in which case
the report for that bug is probably closed. In this case, it would be useful to
view [all bug reports, both open and closed, with the most recently updated
sorted to the
top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
- [Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3A%22T%3A+bug%22+sort%3Aupdated-desc).
[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For
example, you can search issues by priority
([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker),
[critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical),
[major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and
by component
([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22),
[manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+),
[Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22),
etc.).
- [Search with labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
You can also try searching by
[milestone](https://github.com/QubesOS/qubes-issues/milestones) and by
[project](https://github.com/QubesOS/qubes-issues/projects).
- Search by closure reason: [`reason:complete`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3Acompleted) and [`reason:"not planned"`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3A%22not+planned%22).
- [Search by project](https://github.com/QubesOS/qubes-issues/projects).
## Guidelines
### The issue tracker is not a discussion forum
The issue tracker is a tool to help the developers be more productive and
efficient in their work. It is not a place for discussion. If you wish to
discuss something in the issue tracker, please do so on the forum or mailing
lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can
simply link to the relevant issue in your discussion post.
The issue tracker is a tool to help the developers be more productive and efficient in their work. It is not a place for discussion. If you wish to discuss something in the issue tracker, please do so on the forum or mailing lists (see [Help, Support, Mailing Lists, and Forum](/support/)). You can simply link to the relevant issue in your discussion post.
This guideline is important for keeping issues focused on *actionable
information*, which helps the developers to stay focused on their work. When
developers come back to an issue to work on it, we do not want them to have to
sift through a large number of unnecessary comments before they can get
started. In many cases, an issue that gets "too big" essentially becomes more
trouble than it's worth, and no developer will touch it (also see [every issue
must be about a single, actionable
thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases,
we sometimes have to close the issue and open a new one. This is a waste of
energy for everyone involved, so we ask that everyone help to avoid repeating
this pattern.
This guideline is important for keeping issues focused on *actionable information*, which helps the developers to stay focused on their work. When developers come back to an issue to work on it, we do not want them to have to sift through a large number of unnecessary comments before they can get started. In many cases, an issue that gets "too big" essentially becomes more trouble than it's worth, and no developer will touch it (also see [every issue must be about a single, actionable thing](#every-issue-must-be-about-a-single-actionable-thing)). In these cases, we sometimes have to close the issue and open a new one. This is a waste of energy for everyone involved, so we ask that everyone help to avoid repeating this pattern.
### Do not submit questions
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place
to ask questions. This includes, but is not limited to, troubleshooting
questions and questions about how to do things with Qubes. Instead, see [Help,
Support, Mailing Lists, and Forum](/support/) for appropriate place to ask
questions. By contrast,
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for
tracking more general bugs, enhancements, and tasks that affect a broad range
of Qubes users.
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes. Instead, see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate place to ask questions. By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
### Use the issue template
When you open a new issue, an issue template is provided for you. Please use
it. Do not delete it. The issue template is carefully designed to elicit
important information. Without this information, the issue is likely to be
incomplete. (If certain sections are not applicable, you may remove them, but
please do so only sparingly and only if they are *truly* not applicable.)
When you open a new issue, an issue template is provided for you. Please use it. Do not delete it. The issue template is carefully designed to elicit important information. Without this information, the issue is likely to be incomplete. (If certain sections are not applicable, you may remove them, but please do so only sparingly and only if they are *truly* not applicable.)
It is also important to note the placement and content of the HTML comments in
the issue template. These help us to have issues with a consistent format.
It is also important to note the placement and content of the HTML comments in the issue template. These help us to have issues with a consistent format.
### Every issue must be about a single, actionable thing
If your issue is not actionable, please see [Help, Support, Mailing Lists, and
Forum](/support/) for the appropriate place to post it. If your issue would be
about more than one thing, file them as separate issues instead. This means we
should generally not try to use a single issue as a "meta" or "epic" issue that
exists only to group, contain, or track other issues. Instead, when there is a
need to group multiple related issues together, use
[projects](https://github.com/QubesOS/qubes-issues/projects).
If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to post it. If your issue would be about more than one thing, file them as separate issues instead. This means we should generally not try to use a single issue as a "meta" or "epic" issue that exists only to group, contain, or track other issues. Instead, when there is a need to group multiple related issues together, use [projects](https://github.com/QubesOS/qubes-issues/projects).
This guideline is extremely important for making the issue tracker a useful
tool for the developers. When an issue is too big and composite, it becomes
intractable and drastically increases the likelihood that nothing will get
done. Such issues also tend to encourage an excessive amount of general
discussion that is simply not appropriate for a technical issue tracker (see
[the issue tracker is not a discussion
forum](#the-issue-tracker-is-not-a-discussion-forum)).
This guideline is extremely important for making the issue tracker a useful tool for the developers. When an issue is too big and composite, it becomes intractable and drastically increases the likelihood that nothing will get done. Such issues also tend to encourage an excessive amount of general discussion that is simply not appropriate for a technical issue tracker (see [the issue tracker is not a discussion forum](#the-issue-tracker-is-not-a-discussion-forum)).
### New issues should not be duplicates of existing issues
Before you submit an issue, check to see whether it has already been reported.
Search through the existing issues -- both open and closed -- by typing your
key words in the **Filters** box. If you find an issue that seems to be similar
to yours, read through it. If you find an issue that is the same as or subsumes
yours, leave a comment on the existing issue rather than filing a new one, even
if the existing issue is closed. If an issue affects more than one Qubes
version, we usually keep only one issue for all versions. The Qubes team will
see your comment and reopen the issue, if appropriate. For example, you can
leave a comment with additional information to help the maintainer debug it.
Adding a comment will subscribe you to email notifications, which can be
helpful in getting important updates regarding the issue. If you don't have
anything to add but still want to receive email updates, you can click the
"Subscribe" button at the side or bottom of the comments.
Before you submit an issue, check to see whether it has already been reported. Search through the existing issues -- both open and closed -- by typing your key words in the **Filters** box. If you find an issue that seems to be similar to yours, read through it. If you find an issue that is the same as or subsumes yours, leave a comment on the existing issue rather than filing a new one, even if the existing issue is closed. If an issue affects more than one Qubes version, we usually keep only one issue for all versions. The Qubes team will see your comment and reopen the issue, if appropriate. For example, you can leave a comment with additional information to help the maintainer debug it. Adding a comment will subscribe you to email notifications, which can be helpful in getting important updates regarding the issue. If you don't have anything to add but still want to receive email updates, you can click the "Subscribe" button at the side or bottom of the comments.
### Every issue must be of a single type
Every issue must be exactly one of the following types: a bug report (`bug`), a
feature or improvement request (`enhancement`), or a task (`task`). Do not file
multi-typed issues. Instead, file multiple issues of distinct types. The Qubes
team will classify your issue according to its type.
Every issue must be exactly one of the following types: a bug report (`bug`), a feature or improvement request (`enhancement`), or a task (`task`). Do not file multi-typed issues. Instead, file multiple issues of distinct types. The Qubes team will classify your issue according to its type.
### New issues should include all relevant information
When you file a new issue, you should be sure to include the version of Qubes
you're using, as well as versions of related software packages ([how to copy
information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is
related to hardware, provide as many details as possible about the hardware. A
great way to do this is by [generating and submitting a Hardware Compatibility
List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports),
then linking to it in your issue. You may also need to use command-line tools
such as `lspci`. If you're reporting a bug in a package that is in a
[testing](/doc/testing/) repository, please reference the appropriate issue in
the [updates-status](https://github.com/QubesOS/updates-status/issues)
repository. Project maintainers really appreciate thorough explanations. It
usually helps them address the problem more quickly, so everyone wins!
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0](/doc/how-to-copy-from-dom0/)). If your issue is related to hardware, provide as many details as possible about the hardware. A great way to do this is by [generating and submitting a Hardware Compatibility List (HCL) report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then linking to it in your issue. You may also need to use command-line tools such as `lspci`. If you're reporting a bug in a package that is in a [testing](/doc/testing/) repository, please reference the appropriate issue in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository. Project maintainers really appreciate thorough explanations. It usually helps them address the problem more quickly, so everyone wins!
### There are no guarantees that your issue will be addressed
Keep in mind that
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue
tracker, not a support system. Creating a new issue is simply a way for you to
submit an item for the Qubes team's consideration. It is up to the Qubes team
to decide whether or how to address your issue, which may include closing the
issue without taking any action on it. Even if your issue is kept open,
however, you should not expect it to be addressed within any particular time
frame, or at all. At the time of this writing, there are well over one thousand
open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues).
The Qubes team has its own roadmap and priorities, which will govern the manner
and order in which open issues are addressed.
Keep in mind that [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is an issue tracker, not a support system. Creating a new issue is simply a way for you to submit an item for the Qubes team's consideration. It is up to the Qubes team to decide whether or how to address your issue, which may include closing the issue without taking any action on it. Even if your issue is kept open, however, you should not expect it to be addressed within any particular time frame, or at all. At the time of this writing, there are well over one thousand open issues in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues). The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
### Issues and comments must be written in English
If English is not your native language, you may post a machine translation. If you wish, you may also include the original non-English text in a [collapsible section](#use-collapsible-sections-for-long-nonessential-content).
### Use collapsible sections for long, nonessential content
On GitHub, create collapsible sections in Markdown like so:
```
<details>
<summary>Summary goes here. This line is optional.</summary>
Long, nonessential content goes here. You can put a code block here, but make sure to leave empty lines before and after the fence lines (```).
</details>
```
**Tip:** Use the "Preview" tab to make sure it renders correctly before posting.
## How issues get closed
If the Qubes developers make a code change that resolves an issue, then the
issue will typically be [closed from the relevant commit or merged pull request
(PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue).
If the Qubes developers make a code change that resolves an issue, then the issue will typically be [closed from the relevant commit or merged pull request (PR)](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue).
### Bug reports
In the case of bugs, the package containing the change will move to the
appropriate [testing](/doc/testing/) repository, then to the appropriate stable
repository. If you so choose, you can test the fix while it's in the
[testing](/doc/testing/) repository, or you can wait for it to land in the
stable repository. If, after testing the fix, you find that it does not really
fix the reported bug, please leave a comment on the issue explaining the
situation. When you do, we will receive a notification and respond on the issue
or reopen it (or both). Please **do not** create a duplicate issue or attempt
to contact the developers individually about a problem.
In the case of bugs, the package containing the change will move to the appropriate [testing](/doc/testing/) repository, then to the appropriate stable repository. If you so choose, you can test the fix while it's in the [testing](/doc/testing/) repository, or you can wait for it to land in the stable repository. If, after testing the fix, you find that it does not really fix the reported bug, please leave a comment on the issue explaining the situation. When you do, we will receive a notification and respond on the issue or reopen it (or both). Please **do not** create a duplicate issue or attempt to contact the developers individually about a problem.
### Resolution
In other cases, an issue may be closed with a specific resolution, such as `R:
invalid`, `R: duplicate`, or `R: won't fix`. Each of these labels has a
description that explains the label. We'll also leave a comment explaining why
we're closing the issue with one of these specific resolutions. If the issue is
closed without one of these specific resolutions, then it means, by default,
that the reported bug was fixed or the requested enhancement was implemented.
In GitHub, an issue can be [closed as either `completed` or `not planned`](https://github.blog/changelog/2022-03-10-the-new-github-issues-march-10th-update/#%F0%9F%95%B5%F0%9F%8F%BD%E2%99%80%EF%B8%8F-issue-closed-reasons).
Being closed as `completed` means that the issue has been fixed (in the case of bugs) or done (in the case of enhancements and tasks). More precisely, it means that a commit containing the relevant work has been pushed. It takes time for this work to make its way into a package, which must then go through the [testing](/doc/testing/) process before finally landing in the relevant stable repository. Automated comments on the issue will announce when key events in this process occur.
Being closed as `not planned` means that the issue will *not* be fixed (in the case of bugs) or done (in the case of enhancements and tasks). When an issue is closed as `not planned`, we add a **resolution** label starting with `R:` that specifies the reason for the closure, such as `R: duplicate` or `R: cannot reproduce`. Each of these labels has a description that briefly explains the label. We also leave a comment containing a longer explanation for why the issue is being closed along with general information.
While issues that are closed as `not planned` get a more specific resolution label, issues that are closed as `completed` do not always get one, since the linked PRs, commits, automated messages, and the `completed` reason itself are often sufficient to convey all relevant information. For information about using closure reasons in searches, see [Search tips](#search-tips).
### Backports
Issues in GitHub can only be open or closed, but, when it comes to bugs that
affect multiple versions of Qubes OS, there are several possible states:
Issues in GitHub can only be open or closed, but when it comes to bugs that affect multiple versions of Qubes OS, there are several possible states:
1. Not fixed yet
2. Fix developed but not yet committed (PR open)
@ -345,20 +184,12 @@ affect multiple versions of Qubes OS, there are several possible states:
6. Update backported to stable version(s) and pushed to the testing repo
7. Update pushed to stable repo of stable version(s)
We close issues at step 3. Then, as updates are released, the issue
automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and
`stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to
select issues waiting for step 6 (see [issues by
release](https://github.com/QubesOS/qubes-issues#issues-by-release)).
We close issues at step 3. Then, as updates are released, the issue automatically gets the appropriate `current-testing` (`rX.Y-*-cur-test`) and `stable` (`rX.Y-*-stable`) labels. Based on these labels, it's possible to select issues waiting for step 6 (see [issues by release](https://github.com/QubesOS/qubes-issues#issues-by-release)).
Therefore, if you see that an issue is closed, but the fix is not yet available
to you, be aware that it may be at an intermediate stage of this process
between issue closure and the update being available in whichever repos you
have enabled in whichever version of Qubes you're using.
Therefore, if you see that an issue is closed, but the fix is not yet available to you, be aware that it may be at an intermediate stage of this process between issue closure and the update being available in whichever repos you have enabled in whichever version of Qubes you're using.
In order to assist with this, we have a label called [backport
pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending),
which means, "The fix has been released for the testing release but is pending
backport to the stable release." Our infrastructure will attempt to apply this
label automatically, when appropriate, but it is not perfect, and the
developers may be need to adjust it manually.
In order to assist with this, we have a label called [backport pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may be need to adjust it manually.
### Understanding open and closed issues
Every issue is always in one of two states: open or closed, with open being the default. The **open** and **closed** states mean that, according to our available information at present, the issue in question either **is** or **is not** (respectively) actionable for the Qubes team. The open and closed states do not mean anything more than this, and it's important not to read anything else into them. It's also important to understand that closing an issue is, in effect, nothing more than changing a virtual tag on an issue. Closing an issue is never "final" in any sense, and it does not affect the issue itself in any other way. Issues can be opened and closed instantly with a single button press an unlimited number of times at no cost. In fact, since the open and closed states reflect our available information at present, one should expect these states to change back and forth as new information becomes available. Closed issues are fully searchable, just like open issues, and we explicitly instruct all users of the issue tracker to search *both* open *and* closed issues, which GitHub makes easy.

4
introduction/support.md
View File

@ -176,7 +176,7 @@ information in your message. A great way to provide your hardware details is by
[generating and submitting a Hardware Compatibility List (HCL)
report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then
linking to it in your message. [Ask questions the smart
way.](http://www.catb.org/esr/faqs/smart-questions.html)
way.](https://www.catb.org/esr/faqs/smart-questions.html)
### Be patient
@ -309,7 +309,7 @@ account is in no way required, expected, or encouraged. Many discussants
[mailing lists](https://en.wikipedia.org/wiki/Electronic_mailing_list),
interacting with them solely through plain text email with
[MUAs](https://en.wikipedia.org/wiki/Email_client) like
[Thunderbird](https://www.thunderbird.net/) and [Mutt](http://www.mutt.org/).
[Thunderbird](https://www.thunderbird.net/) and [Mutt](https://www.mutt.org/).
The Google Groups service is just free infrastructure, and we [distrust the
infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure). This
is why, for example, we encourage discussants to use [Split

77
project-security/verifying-signatures.md
View File

@ -171,26 +171,61 @@ Fedora, `dnf install distribution-gpg-keys` will get you the QMSK along with
several other Qubes keys. On Debian, your keyring may already contain the
necessary keys.
Perhaps the most common route is to rely on the key's fingerprint. Every PGP
key has a fingerprint that uniquely identifies it among all PGP keys (viewable
with `gpg2 --fingerprint <KEY_ID>`). Therefore, if you know the genuine QMSK
Perhaps the most common route is to rely on the key's fingerprint, which is a
string of 40 alphanumeric characters, like this:
```
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
```
Every PGP key has one of these fingerprints, which uniquely identifies it among
all PGP keys. (On the command line, you can view a key's fingerprint with the
`gpg2 --fingerprint <KEY_ID>` command.) Therefore, if you know the genuine QMSK
fingerprint, then you always have an easy way to confirm whether any purported
copy of it is authentic, simply by comparing the fingerprints.
For example, here is the QMSK fingerprint:
```shell_session
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
```
But how do you know that this is the real fingerprint? After all, [this website
But how do you know which fingerprint is the real one? After all, [this website
could be compromised](/faq/#should-i-trust-this-website), so the fingerprint
you see here may not be genuine. That's why we strongly suggest obtaining the
fingerprint from *multiple independent sources in several different ways*.
fingerprint from *multiple independent sources in several different ways*, then
comparing the strings of letters and numbers to make sure they match.
Here are some ideas for how to do that:
When it comes to PGP fingerprints, spaces and capitalization don't matter. In
other words, all of these fingerprints are considered the same:
```
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
427f 11fd 0faa 4b08 0123 f01c ddfa 1a3e 3687 9494
427F11FD0FAA4B080123F01CDDFA1A3E36879494
427f11fd0faa4b080123f01cddfa1a3e36879494
```
Instead, what matters is that *all* the characters are present in *exactly* the
same order. If even one character is different, the fingerprints do not match.
Even if two fingerprints have all the same characters, if any of those
characters are in a different order, sequence, or position, then the
fingerprints do not match.
You may also sometimes see the entire fingerprint prefixed with `0x`, as in:
```
0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
0x427f11fd0faa4b080123f01cddfa1a3e36879494
```
The `0x` prefix is sometimes used to indicate that the string following it is a
hexadecimal value, and some PGP-related tools may require this prefix. For the
purpose of comparing fingerprints as described here, you may safely ignore the
`0x` prefix, as it is not part of the fingerprint. As long as the 40-character
string after the `0x` matches exactly, the fingerprint is the same.
The general idea of "comparing fingerprints" is to go out into the world
(whether digitally, physically, or both) and find other 40-character strings
purporting to be the QMSK fingerprint, then compare them to your own purported
QMSK fingerprint to ensure that the sequence of alphanumeric characters is
exactly the same (again, regardless of spaces or capitalization). If any of the
characters do not match or are not in the same order, then at least one of the
fingerprints is a forgery. Here are some ideas to get you started:
- Check the fingerprint on various websites (e.g., [mailing
lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ),
@ -204,10 +239,10 @@ Here are some ideas for how to do that:
talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a
[T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or
in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes
Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat
rooms.
- Download old Qubes ISOs from different sources and check the included Qubes
Master Signing Key.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
@ -215,11 +250,11 @@ Here are some ideas for how to do that:
confirm the fingerprint.
- Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough
different ways that you feel confident that you know the genuine fingerprint,
keep it in a safe place. Every time you need to check whether a key claiming to
be the QMSK is authentic, compare that key's fingerprint to your trusted copy
and confirm they match.
Once you've observed enough matching fingerprints from enough independent
sources in enough different ways that you feel confident that you have the
genuine fingerprint, keep it in a safe place. Every time you need to check
whether a key claiming to be the QMSK is authentic, compare that key's
fingerprint to your trusted copy and confirm they match.
Now that you've imported the authentic QMSK, set its trust level to "ultimate"
so that it can be used to automatically verify all the keys signed by the QMSK

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' )

53
user/downloading-installing-upgrading/supported-releases.md
View File

@ -19,17 +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 | Unsupported |
| Release 4.1 | 2022-02-04 | TBA | Supported |
| Release 4.2 | TBA | TBA | [In testing](https://github.com/QubesOS/qubes-issues/milestone/26) |
| Release 4.3 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/milestone/28) |
| 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
@ -91,10 +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.1 | 37, 38 | 10 (Buster), 11 (Bullseye) | 16 |
| Release 4.2 | 37, 38 | 11 (Bullseye) | 17 |
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ------ | ------ |
| Release 4.1 | 38 | 11, 12 | 16 |
| Release 4.2 | 38 | 12 | 17 |
### Note on Debian support
@ -108,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.

88
user/downloading-installing-upgrading/testing.md
View File

@ -7,102 +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.
* 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).)
* (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:
```
qvm-template --enablerepo=qubes-templates-itl-testing list --available
qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
```
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`.
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).

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/)

187
user/hardware/certified-hardware.md
View File

@ -10,211 +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 computers
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.
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.
The current Qubes-certified models are listed below in chronological order of certification.
### Insurgo PrivacyBeast X230
[![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/)
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.
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
[![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) 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.
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
[![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)
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.
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
[![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/)
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.
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.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://configurelaptop.eu/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://configurelaptop.eu/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.
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:
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.
- 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
**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).
**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.
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.
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.
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.
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.
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).
While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).
Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth
devices to be mandatory. Users who plan on using Qubes in an air-gap scenario
would do best if they manually remove all such devices persistently (as well as
the builtin [speakers](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.
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.
We hope these hardware requirements will encourage the development of more
secure and trustworthy devices.
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).

2
user/how-to-guides/how-to-organize-your-qubes.md
View File

@ -317,7 +317,7 @@ her setup looks like this:
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 attach each other or her qube (As long as
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

114
user/how-to-guides/how-to-update.md
View File

@ -8,14 +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/).*
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.
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:
@ -25,124 +20,69 @@ Fully updating your Qubes OS system means updating:
## Security updates
Security updates are an extremely important part of keeping your Qubes
installation secure. When there is an important security incident, we will issue
a [Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security
Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new
QSB and follow any user instructions it contains. Most of the time, simply
updating your system normally, as described below, will be sufficient to obtain
security updates. However, in some cases, special action may be required on
your part, which will be explained in the QSB.
Security updates are an extremely important part of keeping your Qubes installation secure. When there is an important security incident, we will issue a [Qubes Security Bulletin (QSB)](/security/qsb/) via the [Qubes Security Pack (`qubes-secpack`)](/security/pack/). It is very important to read each new QSB and follow any user instructions it contains. Most of the time, simply updating your system normally, as described below, will be sufficient to obtain security updates. However, in some cases, special action may be required on your part, which will be explained in the QSB.
## Checking for updates
By default, the **Qubes Update** tool will appear as an icon in the Notification
Area when updates are available.
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 "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."
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>.
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.
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).)
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.
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:
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 any **Xen** or **kernel** updates.
- After updating a template, first shut down the template, then restart all
running qubes based on that template.
- 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 with direct commands such as
<code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt
update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS
update security measures. Instead, we strongly recommend using the <b>Qubes
Update</b> tool or its command-line equivalents, as described below. (By
contrast, <a href="/doc/how-to-install-software/">installing</a> packages
using direct package manager commands is fine.)
<b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
</div>
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.**
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.**
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
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.
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/).
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
releases](/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 template releases](/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).

80
user/security-in-qubes/vm-sudo.md
View File

@ -104,86 +104,14 @@ Replacing passwordless root access with Dom0 user prompt
--------------------------------------------------------
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 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.
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
[root@dom0 /]# chmod +x /etc/qubes-rpc/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.

9
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

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

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