Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-25 07:19:33 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'QubesOS:main' into patch-7

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

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

1
developer/building/qubes-builder.md
View File

@ -24,6 +24,7 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou
- git
- createrepo
- rpm-build
- dnf-plugins-core
- make
- wget
- rpmdevtools

41
developer/building/qubes-iso-building.md
View File

@ -15,17 +15,27 @@ title: Qubes ISO building
Build Environment
-----------------
Fedora 32 has been successfully used to build Qubes R4.0 with the below steps.
Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below steps.
Other rpm-based operating systems may also work.
Travis-CI uses Ubuntu 18.04 to perform test builds, except it can not test the `./setup` script.
In `dom0`, install the Fedora 32 template if you don't already have it.
**Notes:** On modern Fedora system (like Fedora 37) SeLinux is enforced by
default and is blocking the build system. You would get error like
"can't create transaction lock on /.../rpm/.rpm.lock (Permission denied)".
You can set SeLinux to permissive mode with
~~~
sudo qubes-dom0-update qubes-template-fedora-32
~~~bash
sudo setenforce 0
~~~
Create a standalone AppVM from the Fedora 32 template.
In `dom0`, install the Fedora 36 (or 37) template if you don't already have it.
~~~
sudo qubes-dom0-update qubes-template-fedora-36
~~~
Create a standalone AppVM from the Fedora template.
Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional.
It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build.
Likewise, more memory (up to 16 GB) can help.
@ -46,7 +56,7 @@ gpg --edit-key 36879494
fpr
# Verify fingerprint! See Note below!
# Once verified, set trust to *ultimate*
# (Typical sequence is trust, 5, q)
# (Typical sequence is trust, 5, Y, q)
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
~~~
@ -77,12 +87,12 @@ cd ~/qubes-builder
./setup
# Select Yes to add Qubes Master Signing Key
# Select Yes to add Qubes OS Signing Key
# Select 4.0 for version
# Select 4.1 for version
# Stable
# Select Yes for fast Git cloning
# Select Current (if you want the option to use pre-built packages)
# Select No (we want a full build)
# Select fc30 and buster (for the currently shipping templates)
# Select fc36 and bullseye (for the currently shipping templates)
# Select builder-rpm, builder-debian, template-whonix, mgmt-salt
# Select Yes to add adrelanos's third party key
# Select Yes (to download)
@ -93,7 +103,7 @@ Once it completes downloading, re-run `setup` to add the Whonix templates:
~~~
./setup
# Choose the same options as above, except at templates select:
# fc30, buster, whonix-gateway-15, whonix-workstation-15
# fc36, bullseye, whonix-gateway-16, whonix-workstation-16
~~~
Continue the build process with:
@ -144,12 +154,15 @@ gpg --fingerprint 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA
It should look something like this:
~~~
pub 4096R/2EEACCDA 2014-01-16 [expires: 2021-04-17]
pub rsa4096 2014-01-16 [SC] [expires: 2026-01-23]
Key fingerprint = 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA
uid Patrick Schleizer <adrelanos@riseup.net>
sub 4096R/CE998547 2014-01-16 [expires: 2021-04-17]
sub 4096R/119B3FD6 2014-01-16 [expires: 2021-04-17]
sub 4096R/77BB3C48 2014-01-16 [expires: 2021-04-17]
uid [ unknown] Patrick Schleizer <adrelanos@kicksecure.com>
uid [ unknown] Patrick Schleizer <adrelanos@riseup.net>
uid [ unknown] Patrick Schleizer <adrelanos@whonix.org>
sub rsa4096 2014-01-16 [E] [expires: 2026-01-23]
sub rsa4096 2014-01-16 [A] [expires: 2026-01-23]
sub rsa4096 2014-01-16 [S] [expires: 2026-01-23]
~~~
Next, prepare the Git keyring directory and copy them in:

4
developer/code/coding-style.md
View File

@ -123,7 +123,7 @@ Source Code management (Git) guidelines
- Use git to maintain all code for Qubes project.
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it.
- Qubes code is divided into many git repositories. There are several reasons for that:
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
@ -169,7 +169,7 @@ Security coding guidelines
Python-specific guidelines
--------------------------
- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
- Please follow the guidelines [here](https://peps.python.org/pep-0008/), unless they were in conflict with what is written on this page.
C and C++ specific guidelines
-----------------------------

3
developer/code/license.md
View File

@ -12,7 +12,8 @@ title: Software license
Qubes OS is a compilation of software packages, each under its own license. The
compilation is made available under the GNU General Public License version 2
(GPLv2).
(GPLv2). However, the license for this compilation does not supersede the
license of any package included in the compilation.
The source code of Qubes OS is contained in repositories under the
[@QubesOS](https://github.com/QubesOS) account on GitHub. This source code is

4
developer/debugging/automated-tests.md
View File

@ -121,7 +121,7 @@ Tests are also compatible with nose2 test runner, so you can use this instead:
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
```
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](http://open.qa/).
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](https://open.qa/).
### Unit testing inside a VM
@ -248,7 +248,7 @@ class SomeTestCase(unittest.TestCase):
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
Manually testing Qubes OS and its installation is a time-consuming process.
We use [OpenQA](http://open.qa/) to automate this process.
We use [OpenQA](https://open.qa/) to automate this process.
It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses.
Then, it checks the output to see whether various tests were passed, e.g. by comparing the virtual screen output to screenshots of a successful installation.

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.

2
developer/debugging/vm-interface.md
View File

@ -34,7 +34,7 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-ip` - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)

2
developer/general/continuous-integration.md
View File

@ -23,6 +23,8 @@ containing only the command.
can be useful if CI incorrectly uses a stale branch instead of testing the PR
as if it were merged into `master`.
- `PipelineRetryFailed`: Retry just failed CI jobs. Do not update the branch.
- `PipelineRefresh`: Like `PipelineRetry`, except it only fetches the job status
from GitLab. It doesn't schedule a new build.

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.

410
developer/general/documentation-style-guide.md
View File

@ -13,88 +13,52 @@ title: Documentation style guide
_Also see [how to edit the documentation](/doc/how-to-edit-the-documentation/)._
Qubes OS documentation pages are stored as plain text Markdown files in the
[qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and
regularly pulling from this repo, users can maintain their own up-to-date
offline copy of all Qubes documentation rather than relying solely on the web.
Qubes OS documentation pages are stored as plain text Markdown files in the [qubes-doc](https://github.com/QubesOS/qubes-doc) repository. By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
The documentation is a volunteer community effort. People like you are
constantly working to make it better. If you notice something that can be fixed
or improved, please [edit the
documentation](/doc/how-to-edit-the-documentation/)!
The documentation is a volunteer community effort. People like you are constantly working to make it better. If you notice something that can be fixed or improved, please [edit the documentation](/doc/how-to-edit-the-documentation/)!
This page explains the standards we follow for writing, formatting, and
organizing the documentation. Please follow these guidelines and conventions
when editing the documentation. For the standards governing the website as a
whole, please see the [website style guide](/doc/website-style-guide).
This page explains the standards we follow for writing, formatting, and organizing the documentation. Please follow these guidelines and conventions when editing the documentation. For the standards governing the website as a whole, please see the [website style guide](/doc/website-style-guide).
## Markdown conventions
All the documentation is written in Markdown for maximum accessibility. When
making contributions, please observe the following style conventions. If you're
not familiar with Markdown syntax,
[this](https://daringfireball.net/projects/markdown/) is a great resource.
All the documentation is written in Markdown for maximum accessibility. When making contributions, please observe the following style conventions. If you're not familiar with Markdown syntax, [this](https://daringfireball.net/projects/markdown/) is a great resource.
### Hyperlink syntax
Use non-reference-style links like `[website](https://example.com/)`. Do *not*
use reference-style links like `[website][example]`, `[website][]` or
`[website]`. This facilitates the localization process.
Use non-reference-style links like `[website](https://example.com/)`. Do *not* use reference-style links like `[website][example]`, `[website][]` or `[website]`. This facilitates the localization process.
### Relative vs. absolute links
Always use relative rather than absolute paths for internal website links. For
example, use `/doc/documentation-style-guide/` instead of
`https://www.qubes-os.org/doc/documentation-style-guide/`.
Always use relative rather than absolute paths for internal website links. For example, use `/doc/documentation-style-guide/` instead of `https://www.qubes-os.org/doc/documentation-style-guide/`.
You may use absolute URLs in the following cases:
- External links
- URLs that appear inside code blocks (e.g., in comments and document
templates, and the plain text reproductions of [QSBs](/security/qsb/) and
[Canaries](/security/canary/)), since they're not hyperlinks
- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part
of the website itself but rather of the auxiliary infrastructure supporting
the website
- URLs that appear inside code blocks (e.g., in comments and document templates, and the plain text reproductions of [QSBs](/security/qsb/) and [Canaries](/security/canary/)), since they're not hyperlinks
- Git repo files like `README.md` and `CONTRIBUTING.md`, since they're not part of the website itself but rather of the auxiliary infrastructure supporting the website
This rule is important because using absolute URLs for internal website links
breaks:
This rule is important because using absolute URLs for internal website links breaks:
- Serving the website offline
- Website localization
- Generating offline documentation
- Automatically redirecting Tor Browser visitors to the correct page on the
onion service mirror
- Automatically redirecting Tor Browser visitors to the correct page on the onion service mirror
### Image linking
See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images)
for the required syntax. This will make the image a hyperlink to the image
file, allowing the reader to click on the image in order to view the full image
by itself. This is important. Following best practices, our website has a
responsive design, which allows the website to render appropriately across all
screen sizes. When viewing this page on a smaller screen, such as on a mobile
device, the image will automatically shrink down to fit the screen. If visitors
cannot click on the image to view it in full size, then, depending on their
device, they may have no way see the details in the image clearly.
See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images) for the required syntax. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the full image by itself. This is important. Following best practices, our website has a responsive design, which allows the website to render appropriately across all screen sizes. When viewing this page on a smaller screen, such as on a mobile device, the image will automatically shrink down to fit the screen. If visitors cannot click on the image to view it in full size, then, depending on their device, they may have no way see the details in the image clearly.
In addition, make sure to link only to images in the
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do
not attempt to link to images hosted on other websites.
In addition, make sure to link only to images in the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do not attempt to link to images hosted on other websites.
### HTML and CSS
Do not write HTML inside Markdown documents (except in rare, unavoidable cases,
such as alerts). In particular, never include HTML or CSS for styling,
formatting, or white space control. That belongs in the (S)CSS files instead.
Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as [alerts](#alerts)). In particular, never include HTML or CSS for styling, formatting, or white space control. That belongs in the (S)CSS files instead.
### Headings
Do not use `h1` headings (single `#` or `======` underline). These are
automatically generated from the `title:` line in the YAML front matter.
Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML front matter.
Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use
underlining syntax (`-----`).
Use Atx-style syntax for headings: `##h2`, `### h3`, etc. Do not use underlining syntax (`-----`).
### Indentation
@ -102,49 +66,131 @@ Use spaces instead of tabs. Use hanging indentations where appropriate.
### Lists
If appropriate, make numerals in numbered lists match between Markdown source
and HTML output. Some users read the Markdown source directly, and this makes
numbered lists easier to follow.
If appropriate, make numerals in numbered lists match between Markdown source and HTML output. Some users read the Markdown source directly, and this makes numbered lists easier to follow.
### Code blocks
When writing code blocks, use [syntax
highlighting](https://github.github.com/gfm/#info-string) where possible (see
[here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers)
for a list of supported languages). Use `[...]` for anything omitted.
When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where possible (see [here](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) for a list of supported languages). Use `[...]` for anything omitted.
### Line wrapping
Hard wrap Markdown lines at 80 characters, unless the line can't be broken
(e.g., code or a URL).
Do not hard wrap text, except where necessary (e.g., inside code blocks).
### Do not use Markdown syntax for styling
For example, there is a common temptation to use block quotations (created by beginning lines with the `>` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.:
```
> Note: This is an important note!
```
This renders as:
> Note: This is an important note!
There are two problems with this:
1. It is a violation of the [separation of content and presentation](https://en.wikipedia.org/wiki/Separation_of_content_and_presentation), since it abuses markup syntax in order to achieve unintended stylistic results. The Markdown (and HTML, if any) should embody the *content* of the documentation, while the *presentation* is handled by (S)CSS.
2. It is an abuse of quotation syntax for text that is not actually a quotation. (You are not quoting anyone here. You're just telling the reader to note something and trying to draw their attention to your note visually.)
Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using [alerts](#alerts). Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,:
```
**Note:** This is an important note.
```
This renders as:
**Note:** This is an important note.
### Alerts
Alerts are sections of HTML used to draw the reader's attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause [alert fatigue](https://en.wikipedia.org/wiki/Alarm_fatigue) and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons:
```
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
even load any networking drivers, so there is no possibility of
internet-based data leaks or attacks during the installation process.
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> Using Rufus to create the installation medium means that you <a
href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
to choose the "Test this media and install Qubes OS" option mentioned in the
example below. Instead, choose the "Install Qubes OS" option.
</div>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
as a guest hypervisor. In other words, <b>nested virtualization</b> is not
supported. In order for a strict compartmentalization to be enforced, Qubes
OS needs to be able to manage the hardware directly.
</div>
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Qubes has no control over what happens on your computer
before you install it. No software can provide security if it is installed on
compromised hardware. Do not install Qubes on a computer you don't trust. See
<a href="/doc/install-security/">installation security</a> for more
information.
</div>
```
These render as:
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
<b>Did you know?</b> The Qubes OS installer is completely offline. It doesn't
even load any networking drivers, so there is no possibility of
internet-based data leaks or attacks during the installation process.
</div>
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> Using Rufus to create the installation medium means that you <a
href="https://github.com/QubesOS/qubes-issues/issues/2051">won't be able</a>
to choose the "Test this media and install Qubes OS" option mentioned in the
example below. Instead, choose the "Install Qubes OS" option.
</div>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> Qubes OS is not meant to be installed inside a virtual machine
as a guest hypervisor. In other words, <b>nested virtualization</b> is not
supported. In order for a strict compartmentalization to be enforced, Qubes
OS needs to be able to manage the hardware directly.
</div>
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Qubes has no control over what happens on your computer
before you install it. No software can provide security if it is installed on
compromised hardware. Do not install Qubes on a computer you don't trust. See
<a href="/doc/install-security/">installation security</a> for more
information.
</div>
## Writing guidelines
### Correct use of terminology
Familiarize yourself with the terms defined in the [glossary](/doc/glossary/).
Use these terms consistently and accurately throughout your writing.
Familiarize yourself with the terms defined in the [glossary](/doc/glossary/). Use these terms consistently and accurately throughout your writing.
### Sentence case in headings
Use sentence case (rather than title case) in headings for the reasons
explained
[here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/).
In particular, since the authorship of the Qubes documentation is decentralized
and widely distributed among users from around the world, many contributors
come from regions with different conventions for implementing title case, not
to mention that there are often differing style guide recommendations even
within a single region. It is much easier for all of us to implement sentence
case consistently across our growing body of pages, which is very important for
managing the ongoing maintenance burden and sustainability of the
documentation.
Use sentence case (rather than title case) in headings for the reasons explained [here](https://www.sallybagshaw.com.au/articles/sentence-case-v-title-case/). In particular, since the authorship of the Qubes documentation is decentralized and widely distributed among users from around the world, many contributors come from regions with different conventions for implementing title case, not to mention that there are often differing style guide recommendations even within a single region. It is much easier for all of us to implement sentence case consistently across our growing body of pages, which is very important for managing the ongoing maintenance burden and sustainability of the documentation.
### Writing command-line examples
When providing command-line examples:
- Tell the reader where to open a terminal (dom0 or a specific domU), and show
the command along with its output (if any) in a code block, e.g.:
- Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown
Open a terminal in dom0 and run:
@ -155,12 +201,9 @@ When providing command-line examples:
```
~~~
- Precede each command with the appropriate command prompt: At a minimum, the
prompt should contain a trailing `#` (for the user `root`) or `$` (for other
users) on Linux systems and `>` on Windows systems, respectively.
- Precede each command with the appropriate command prompt: At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
- Don't try to add comments inside the code block. For example, *don't* do
this:
- Don't try to add comments inside the code block. For example, *don't* do this:
~~~markdown
Open a terminal in dom0 and run:
@ -173,14 +216,11 @@ When providing command-line examples:
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command
prompt. Instead, put your comments *outside* of the code block in normal
prose.
The `#` symbol preceding each comment is ambiguous with a root command prompt. Instead, put your comments *outside* of the code block in normal prose.
### Variable names in commands
Syntactically distinguish variables in commands. For example, this is
ambiguous:
Syntactically distinguish variables in commands. For example, this is ambiguous:
$ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm
@ -194,135 +234,53 @@ Note that we syntactically distinguish variables in three ways:
2. Using underscores (`_`) instead of spaces between words
3. Using all capital letters
We have observed that many novices make the mistake of typing the surrounding
angled brackets (`< >`) on the command line, even after substituting the
desired real value between them. Therefore, in documentation aimed at novices,
we also recommend clarifying that the angled brackets should not be typed. This
can be accomplished in one of several ways:
We have observed that many novices make the mistake of typing the surrounding angled brackets (`< >`) on the command line, even after substituting the desired real value between them. Therefore, in documentation aimed at novices, we also recommend clarifying that the angled brackets should not be typed. This can be accomplished in one of several ways:
- Explicitly say something like "without the angled brackets."
- Provide an example command using real values that excludes the angled
brackets.
- If you know that almost all users will want to use (or should use) a specific
command containing all real values and no variables, you might consider
providing exactly that command and forgoing the version with variables.
Novices may not realize which parts of the command they can substitute with
different values, but if you've correctly judged that they should use the
command you've provided as is, then this shouldn't matter.
- Provide an example command using real values that excludes the angled brackets.
- If you know that almost all users will want to use (or should use) a specific command containing all real values and no variables, you might consider providing exactly that command and forgoing the version with variables. Novices may not realize which parts of the command they can substitute with different values, but if you've correctly judged that they should use the command you've provided as is, then this shouldn't matter.
### Capitalization of "qube"
We introduced the term ["qube"](/doc/glossary/#qube) as a user-friendly alternative to the term ["virtual machine" ("VM")](/doc/glossary/#vm) in the context of Qubes OS. Nonetheless, "qube" is a common noun like the words "compartment" and "container." Therefore, in English, "qube" follows the standard capitalization rules for common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Like other common nouns, "qube" should still be capitalized at the beginnings of sentences, the beginnings of sentence-case headings, and in title-case headings. Note, however, that starting a sentence with the plural of "qube" (e.g., "Qubes can be shut down...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes, [Qubes OS](/doc/glossary/#qubes-os), or even the Qubes OS Project itself. Hence, it is generally a good idea to rephrase such sentences in order to avoid this ambiguity.
Many people feel a strong temptation to capitalize the word "qube" all the time, like a proper noun, perhaps because it's a new and unfamiliar term that's closely associated with a particular piece of software (namely, Qubes OS). However, these factors are not relevant to the capitalization rules of English. In fact, it's not unusual for new common nouns to be introduced into English, especially in the context of technology. For example, "blockchain" is a relatively recent technical term that's a common noun. Why is it a common noun rather than a proper noun? Because proper nouns refer to *particular* people, places, things, and ideas. There are many different blockchains. However, even when there was just one, the word still denoted a collection of things rather than a particular thing. It happened to be the case that there was only one member in that collection at the time. For example, if there happened to be only one tree in the world, that wouldn't change the way we capitalize sentences like, "John sat under a tree." Intuitively, it makes sense that the addition and removal of objects from the world shouldn't cause published books to become orthographicallly incorrect while sitting on their shelves.
Accordingly, the reason "qube" is a common noun rather than a proper noun is because it doesn't refer to any one specific thing (in this case, any one specific virtual machine). Rather, it's the term for any virtual machine in a Qubes OS installation. (Technically, while qubes are currently implemented as virtual machines, Qubes OS is independent of its underlying compartmentalization technology. Virtual machines could be replaced with a different technology, and qubes would still be called "qubes.")
I have several qubes in my Qubes OS installation, and you have several in yours. Every Qubes OS user has their own set of qubes, just as each of us lives in some neighborhood on some street. Yet we aren't tempted to treat words like "neighborhood" or "street" as proper nouns (unless, of course, they're part of a name, like "Acorn Street"). Again, while this might seem odd because "qube" is a new word that we invented, that doesn't change how English works. After all, *every* word was a new word that someone invented at some point (otherwise we wouldn't have any words at all). We treat "telephone," "computer," "network," "program," and so on as common nouns, even though those were all new technological inventions in the not-too-distant past (on a historical scale, at least). So, we shouldn't allow ourselves to be confused by irrelevant factors, like the fact that the inventors happened to be *us* or that the invention was *recent* or is not in widespread use among humanity.
### English language conventions
For the sake of consistency and uniformity, the Qubes documentation aims to follow the conventions of American English, where applicable. (Please note that this is an arbitrary convention for the sake consistency and not a value judgment about the relative merits of British versus American English.)
## Organizational guidelines
### Do not duplicate documentation
Duplicating documentation is almost always a bad idea. There are many reasons
for this. The main one is that almost all documentation has to be updated as
some point. When similar documentation appears in more than one place, it is
very easy for it to get updated in one place but not the others (perhaps
because the person updating it doesn't realize it's in more than once place).
When this happens, the documentation as a whole is now inconsistent, and the
outdated documentation becomes a trap, especially for novice users. Such traps
are often more harmful than if the documentation never existed in the first
place. The solution is to **link** to existing documentation rather than
duplicating it. There are some exceptions to this policy (e.g., information
that is certain not to change for a very long time), but they are rare.
Duplicating documentation is almost always a bad idea. There are many reasons for this. The main one is that almost all documentation has to be updated as some point. When similar documentation appears in more than one place, it is very easy for it to get updated in one place but not the others (perhaps because the person updating it doesn't realize it's in more than once place). When this happens, the documentation as a whole is now inconsistent, and the outdated documentation becomes a trap, especially for novice users. Such traps are often more harmful than if the documentation never existed in the first place. The solution is to **link** to existing documentation rather than duplicating it. There are some exceptions to this policy (e.g., information that is certain not to change for a very long time), but they are rare.
### Core vs. external documentation
Core documentation resides in the [Qubes OS Project's official
repositories](https://github.com/QubesOS/), mainly in
[qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can
be anywhere else (such as forums, community websites, and blogs), but there is
an especially large collection in the [Qubes
Community](https://github.com/Qubes-Community) project. External documentation
should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc).
If you've written a piece of documentation that is not appropriate for
[qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit
it to the [Qubes Community](https://github.com/Qubes-Community) project
instead. However, *linking* to external documentation from
[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed,
the maintainers of the [Qubes Community](https://github.com/Qubes-Community)
project should regularly submit PRs against the documentation index (see [How
to edit the documentation
index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index))
to add and update Qubes Community links in the ["External
documentation"](/doc/#external-documentation) section of the documentation
table of contents.
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project. External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Community](https://github.com/Qubes-Community) project should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents.
The main difference between **core** (or **official**) and **external** (or
**community** or **unofficial**) documentation is whether it documents software
that is officially written and maintained by the Qubes OS Project. The purpose
of this distinction is to keep the core docs maintainable and high-quality by
limiting them to the software output by the Qubes OS Project. In other words,
we take responsibility for documenting all of the software we put out into the
world, but it doesn't make sense for us to take on the responsibility of
documenting or maintaining documentation for anything else. For example, Qubes
OS may use a popular Linux distribution for an official
[TemplateVM](/doc/templates/). However, it would not make sense for a
comparatively small project like ours, with modest funding and a lean
workforce, to attempt to document software belonging to a large, richly-funded
project with an army of paid and volunteer contributors, especially when they
probably already have documentation of their own. This is particularly true
when it comes to Linux in general. Although many users who are new to Qubes are
also new to Linux, it makes absolutely no sense for our comparatively tiny
project to try to document Linux in general when there is already a plethora of
documentation out there.
The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.
Many contributors do not realize that there is a significant amount of work
involved in *maintaining* documentation after it has been written. They may
wish to write documentation and submit it to the core docs, but they see only
their own writing process and fail to consider that it will have to be kept
up-to-date and consistent with the rest of the docs for years afterward.
Submissions to the core docs also have to [undergo a review
process](/doc/how-to-edit-the-documentation#security) to ensure accuracy before
being merged, which takes up valuable time from the team. We aim to maintain
high quality standards for the core docs (style and mechanics, formatting),
which also takes up a lot of time. If the documentation involves anything
external to the Qubes OS Project (such as a website, platform, program,
protocol, framework, practice, or even a reference to a version number), the
documentation is likely to become outdated when that external thing changes.
It's also important to periodically review and update this documentation,
especially when a new Qubes release comes out. Periodically, there may be
technical or policy changes that affect all the core documentation. The more
documentation there is relative to maintainers, the harder all of this will be.
Since there are many more people who are willing to write documentation than to
maintain it, these individually small incremental additions amount to a
significant maintenance burden for the project.
Many contributors do not realize that there is a significant amount of work involved in *maintaining* documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to [undergo a review process](/doc/how-to-edit-the-documentation/#security) to ensure accuracy before being merged, which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It's also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.
On the positive side, we consider the existence of community documentation to
be a sign of a healthy ecosystem, and this is quite common in the software
world. The community is better positioned to write and maintain documentation
that applies, combines, and simplifies the official documentation, e.g.,
tutorials that explain how to install and use various programs in Qubes, how to
create custom VM setups, and introductory tutorials that teach basic Linux
concepts and commands in the context of Qubes. In addition, just because the
Qubes OS Project has officially written and maintains some flexible framework,
such as `qrexec`, it does not make sense to include every tutorial that says
"here's how to do something cool with `qrexec`" in the core docs. Such
tutorials generally also belong in the community documentation.
On the positive side, we consider the existence of community documentation to be a sign of a healthy ecosystem, and this is quite common in the software world. The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes. In addition, just because the Qubes OS Project has officially written and maintains some flexible framework, such as `qrexec`, it does not make sense to include every tutorial that says "here's how to do something cool with `qrexec`" in the core docs. Such tutorials generally also belong in the community documentation.
See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more
background information.
See [#4693](https://github.com/QubesOS/qubes-issues/issues/4693) for more background information.
### Release-specific documentation
*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending
changes to this policy.*
*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for pending changes to this policy.*
We maintain only one set of documentation for Qubes OS. We do not maintain a
different set of documentation for each release of Qubes. Our single set of
Qubes OS documentation is updated on a continual, rolling basis. Our first
priority is to document all **current, stable releases** of Qubes. Our second
priority is to document the next, upcoming release (if any) that is currently
in the beta or release candidate stage.
We maintain only one set of documentation for Qubes OS. We do not maintain a different set of documentation for each release of Qubes. Our single set of Qubes OS documentation is updated on a continual, rolling basis. Our first priority is to document all **current, stable releases** of Qubes. Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
In cases where a documentation page covers functionality that differs
considerably between Qubes OS releases, the page should be subdivided into
clearly-labeled sections that cover the different functionality in different
releases (examples below).
In cases where a documentation page covers functionality that differs considerably between Qubes OS releases, the page should be subdivided into clearly-labeled sections that cover the different functionality in different releases (examples below).
In general, avoid mentioning specific Qubes versions in the body text of
documentation, as these references rapidly go out of date and become misleading
to readers.
In general, avoid mentioning specific Qubes versions in the body text of documentation, as these references rapidly go out of date and become misleading to readers.
#### Incorrect Example
@ -381,65 +339,17 @@ general `qubes-baz` command:
Once you foo, make sure to close the baz before fooing the next bar.
```
Subdividing the page into clearly-labeled sections for each release has several
benefits:
Subdividing the page into clearly-labeled sections for each release has several benefits:
- It preserves good content for older (but still supported) releases. Many
documentation contributors are also people who prefer to use the latest
release. Many of them are tempted to *replace* existing content that applies
to an older, supported release with content that applies only to the latest
release. This is somewhat understandable. Since they only use the latest
release, they may be focused on their own experience, and they may even
regard the older release as deprecated, even when it's actually still
supported. However, allowing this replacement of content would do a great
disservice to those who still rely on the older, supported release. In many
cases, these users value the stability and reliability of the older,
supported release. With the older, supported release, there has been more
time to fix bugs and make improvements in both the software and the
documentation. Consequently, much of the documentation content for this
release may have gone through several rounds of editing, review, and
revision. It would be a tragedy for this content to vanish while the very set
of users who most prize stability and reliability are depending on it.
- It's easy for readers to quickly find the information they're looking for,
since they can go directly to the section that applies to their release.
- It's hard for readers to miss information they need, since it's all in one
place. In the incorrect example, information that the reader needs could be
in any paragraph in the entire document, and there's no way to tell without
reading the entire page. In the correct example, the reader can simply skim
the headings in order to know which parts of the page need to be read and
which can be safely ignored. The fact that some content is repeated in the
two release-specific sections is not a problem, since no reader has to read
the same thing twice. Moreover, as one release gets updated, it's likely that
the documentation for that release will also be updated. Therefore, content
that is initially duplicated between release-specific sections will not
necessarily stay that way, and this is a good thing: We want the
documentation for a release that *doesn't* change to stay the same, and we
want the documentation for a release that *does* change to change along with
the software.
- It's easy for documentation contributors and maintainers to know which file
to edit and update, since there's only one page for all Qubes OS releases.
Initially creating the new headings and duplicating content that applies to
both is only a one-time cost for each page, and many pages don't even require
this treatment, since they apply to all currently-supported Qubes OS
releases.
- It preserves good content for older (but still supported) releases. Many documentation contributors are also people who prefer to use the latest release. Many of them are tempted to *replace* existing content that applies to an older, supported release with content that applies only to the latest release. This is somewhat understandable. Since they only use the latest release, they may be focused on their own experience, and they may even regard the older release as deprecated, even when it's actually still supported. However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported release. In many cases, these users value the stability and reliability of the older, supported release. With the older, supported release, there has been more time to fix bugs and make improvements in both the software and the documentation. Consequently, much of the documentation content for this release may have gone through several rounds of editing, review, and revision. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
- It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their release.
- It's hard for readers to miss information they need, since it's all in one place. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. The fact that some content is repeated in the two release-specific sections is not a problem, since no reader has to read the same thing twice. Moreover, as one release gets updated, it's likely that the documentation for that release will also be updated. Therefore, content that is initially duplicated between release-specific sections will not necessarily stay that way, and this is a good thing: We want the documentation for a release that *doesn't* change to stay the same, and we want the documentation for a release that *does* change to change along with the software.
- It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS releases. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS releases.
By contrast, an alternative approach, such as segregating the documentation
into two different branches, would mean that contributions that apply to both
Qubes releases would only end up in one branch, unless someone remembered to
manually submit the same thing to the other branch and actually made the effort
to do so. Most of the time, this wouldn't happen. When it did, it would mean a
second pull request that would have to be reviewed. Over time, the different
branches would diverge in non-release-specific content. Good general content
that was submitted only to one branch would effectively disappear once that
release was deprecated. (Even if it were still on the website, no one would
look at it, since it would explicitly be in the subdirectory of a deprecated
release, and there would be a motivation to remove it from the website so that
search results wouldn't be populated with out-of-date information.)
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes releases would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. Most of the time, this wouldn't happen. When it did, it would mean a second pull request that would have to be reviewed. Over time, the different branches would diverge in non-release-specific content. Good general content that was submitted only to one branch would effectively disappear once that release was deprecated. (Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated release, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.)
For further discussion about release-specific documentation in Qubes, see
[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
For further discussion about release-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
## Git conventions
Please follow our [Git commit message
guidelines](/doc/coding-style/#commit-message-guidelines).
Please follow our [Git commit message guidelines](/doc/coding-style/#commit-message-guidelines).

123
developer/general/gsod.md
View File

@ -6,78 +6,95 @@ ref: 242
title: Google Season of Docs (GSoD)
---
Thank you for your interest in participating in the [2021 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
Thank you for your interest in participating in the [2023 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2023 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
## 2021 Project Idea
## Instructional video series -- Qubes OS
### Qubes OS on Virtual Machines and Disposable VMs documentation - Qubes OS
### About the Qubes OS Project
#### About your organization
Qubes OS is a security-focused operating system that allows you to organize your digital life into compartments called "qubes." If one qube is compromised, the others remain safe, so a single cyberattack can no longer take down your entire digital life in one fell swoop. You can think of using Qubes OS as having many different computers on your desk for different activities but with the convenience of a single physical machine, a single unified desktop environment, and a set of tools for using qubes together securely as parts of a unified system.
Qubes OS is a free and open source operating system uniquely designed to protect the security and privacy of the user. Its architecture is built to enable a user to define different security environments ("qubes") on their computer and visually manage their interaction with each other and the world.
Qubes OS was launched in 2011 and has [received praise from security experts and organizations](/endorsements/) like Edward Snowden, the Freedom of the Press Foundation, Micah Lee, and Let's Encrypt. Qubes has [over 40,000 active users](/statistics/). From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done safely.
Qubes OS was launched in 2011 and has [received praise from security experts](https://www.qubes-os.org/endorsements/) like Edward Snowden, Bill Buddington (EFF), Isis Lovecruft (Tor Project), and Kenn White (Open Crypto Audit), and has over [30,000 active users](https://www.qubes-os.org/statistics/).
### The project's problem
From network-level to software-level protections, as well as protections against firmware and hardware attacks, Qubes OS is trying to protect the user from the most significant attacks they encounter so that they can get their work done, safely.
There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with.
#### The Project
### The project's scope
The goal of the project is to improve the documentation related to Disposable VMs and installing Qubes OS on Virtual Machines.
This project consists of creating a series of instructional videos that satisfy the following criteria:
The current Disposable VMs documentation is scarce, inconsistent in places and is scattered across multiple pages, sometimes hard to find. This project involves consolidating it into one or few easy to find pages, covering all related subjects. It should be written in way easy to follow and understand, clearly separating basic use cases, advanced ones and internal details. The terminology should also be used consistently.
- Prospective users who are not yet familiar with Linux or Qubes OS can easily understand and follow the videos.
- The videos make a good effort to catch and keep the attention of their target audience.
- Users can follow the videos step-by-step to install Qubes OS and accomplish various tasks.
- The videos show the actual software being used (i.e., Qubes OS and any relevant software running inside of it).
- The videos are technically accurate, include security warnings where appropriate, and use terminology in a way that is consistent with the rest of the documentation (also see the [glossary](/doc/glossary/)).
- The video series is comprehensive enough that users do not need to consult the documentation or ask questions (e.g., on the forum) in order to accomplish the most popular tasks and activities.
- The videos include voice narration. (Showing the speaker is optional.)
- The quality of the videos is consistent with current standards regarding things like editing, transitions, animations, lighting, and audio quality.
- The videos are in high definition (minimum 1080p, preferably 4k).
- The videos are separated into a series, where each video is an appropriate length and is appropriately connected to the other videos in the series.
- The videos are suitable for upload and sharing on popular video-sharing and social-media platforms, such as YouTube and Twitter. (The account or channel under which the videos are uploaded is open to discussion on platforms where the Qubes OS Project does not already have a significant established presence, such as YouTube.)
- The videos are suitable for embedding in appropriate places in the Qubes documentation. (E.g., a video on how to update Qubes OS should be appropriate for appearing on the [how to update](/doc/how-to-update/) page.)
- Where possible, the videos should strive to be version-independent. (For example, a video explaining the template system should still be relevant many releases from now if the template system has not changed.)
Additionally, Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial existing installation guide for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine. This project also involves writing an installation guide that details how to install Qubes on virtual machines, and how to troubleshoot any issues that may arise.
Below is an example of the content (which is already [documented](/doc/)) that the video series is likely to cover. The precise scope of content is to be determined in consultation with the video creator.
#### Project’s scope
- Introduction to Qubes
- Selecting appropriate hardware
- How to install Qubes OS
- First steps after installing
- How to organize your qubes
- How to update
- How to back up, restore, and migrate
- How to copy and paste text (including dom0)
- How to copy and move files (including dom0)
- How to install software
- How to use and customize disposables
- How to enter fullscreen mode
- How to use devices (including block storage, USB, PCI, and optical)
- Templates: understanding, installing, uninstalling, reinstalling, etc.
- Common troubleshooting (preferably included in previous videos at appropriate points)
- The Qubes firewall
- Passwordless root
- Anti Evil Maid
- Split GPG
- U2F proxy
- YubiKey
- Whonix
- How to install and use a VPN in Qubes
- How to install and use Windows in Qubes
- Other popular topics, as time permits
The technical writer will:
The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, and Marek Marczykowski-Górecki, will supervise and support the creator.
* Review existing Disposable VM documentation
### Measuring the project's success
* Propose new documentation layout, including split between pages
We will consider the project successful if, after publication of the video series:
* Propose updated and clarified content
- Actual prospective users with no prior familiarity with Linux or Qubes OS are able to successfully install and use Qubes OS as intended by following along with the videos.
- The reception to the videos is generally positive and complaints about quality and accuracy are minimal.
- Appropriate analytics (e.g., YouTube metrics) are average or better for videos of this type (to be determined in consultation with the creator).
* Provide a new option of installation guide for users working on virtual machines.
### Timeline
* Review existing problems and provide solutions to them.
| Dates | Action items |
| -------------- | --------------------------------------- |
| March | Orientation |
| April--October | Create Qubes OS video series |
| November | Final project evaluation and case study |
* Giving a warning for using outdated versions of Qubes.
Knowledge prerequisites:
### Project budget
* Basic Qubes OS knowledge - intro, getting started.
| Expense | Amount |
| --------------------------------------- | ------- |
| Video creator (20 hours/week, 6 months) | $12,000 |
| TOTAL | $12,000 |
* Markdown.
### Additional information
* Experience in virtual boxes and machines.
* Basic knowledge about Fedora Linux architecture.
The project is estimated to need around 6 months, with a part-time (20hr/week) workload. Qubes OS team members focused on documentation (Michael Carbone, Andrew David Wong, Marek Marczykowski-Górecki) have committed to supporting the project.
#### Measuring the project’s success
We will consider the project successful if, after publication of the new documentation:
* The Disposable VM documentation is consilidated into a few pages and easier to find.
* Disposable VM terminology is consistent across all pages
* There is a new installation guide detailing how to install Qubes on virtual machines (VirtualBox), complete with screenshots and troubleshooting steps where necessary.
* There is a decrease (by ~20%) in the number of issues and questions raised for topics covered in the documentation, whether in the official Github issues tracker, the Qubes mailing list, or the Qubes community forum.
#### Budget
| Budget item | Amount | Running total | Note / Justification |
|-|-|-|-|
| Technical writer audit, update, and write new documentation | $12000 | $12000 | based on a 20hr/week for 6 months at 25$/hr |
| TOTAL | | $12000 | |
#### Additional information
Qubes OS regularly participates in the Google Summer of Code and Google Season of Docs. This is our third time in a row participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes and both projects were completed
within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers, and has helped us to understand the benefits of technical writers can to our project
Qubes OS regularly participates in Google Summer of Code and Google Season of Docs. This is our third time participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes, and both projects were completed within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers and have helped us to understand the benefits that technical writers can bring to our project. While our experience in working with video creators is more limited, we are keenly aware of the benefits of high-quality video content, as well as the significant time, resources, and talent required to create it.
## Past Projects
@ -110,7 +127,7 @@ This could be helped by writing a consolidated guide with a clear list of sympto
**Project**: Improve Getting Started page
**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide.
**Brief explanation**: The [Getting Started page](/doc/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](https://github.com/QubesOS/qubes-issues/issues/1019) or the firstboot guide.
**Expected results**:
@ -128,14 +145,14 @@ This could be helped by writing a consolidated guide with a clear list of sympto
**Project**: Rewrite qrexec documentation
**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important informations are hidden within a wall of text.
**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important information is hidden within a wall of text.
Some parts are split into multiple sections, for example version specific to avoid duplication, but it doesn't help reading it.
Additionally, protocol documentation describes only few specific use cases, instead of being clear and precise protocol specification.
Fixing this last point may require very close cooperation with developers, as the current documentation doesn't multiple corner cases (that's one of the issue with its current shape).
**Expected results**:
- Review existing [qrexec documentation](https://www.qubes-os.org/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392)
- Review existing [qrexec documentation](/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392)
- Propose updated, consolidated admin documentation (policy writing, adding services)
- Propose consolidated protocol specification, based on the current documentation, and cooperation with developers

11
developer/general/join.md
View File

@ -1,11 +0,0 @@
---
lang: en
layout: doc
permalink: /join/
ref: 26
title: Join
---
The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

14
developer/general/usability-ux.md
View File

@ -206,14 +206,14 @@ Clearly, cutting out something as simple as navigating through the file system c
## GNOME, KDE, and Xfce
The desktop GUIs that QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
The desktop GUIs that QubesOS versions 1 - 4.1 offer are [KDE](https://kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
This change means you should use [GTK](https://www.gtk.org/) rather than Qt for new GUIs.
This change means you should use [GTK](https://gtk.org/) rather than Qt for new GUIs.
All three of these mentioned desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines), and we suggest you familiarize yourself with the platform you developing for.
- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/)
- [KDE HIG](https://techbase.kde.org/Projects/Usability/HIG)
- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/)
- [KDE HIG](https://hig.kde.org/)
- [Xfce UI Guidlines](https://wiki.xfce.org/dev/hig/general)
---
@ -222,9 +222,9 @@ All three of these mentioned desktop environments have their own [human interfac
Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources:
- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum
- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
- [Learn Design Principles](https://web.archive.org/web/20180101172357/http://learndesignprinciples.com/) by Melissa Mandelbaum
- [Usability in Free Software](https://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
- [Superheroes & Villains in Design](https://vimeo.com/70030549) by Aral Balkan
- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen
- [First Rule of Usability? Don’t Listen to Users](https://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by Jakob Nielsen
- [10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/) by Jakob Nielsen
- [Hack Design](https://hackdesign.org/) - online learning program

1
developer/releases/4_1/release-notes.md
View File

@ -68,6 +68,7 @@ permalink: /doc/releases/4.1/release-notes/
`/etc/qubes/guid.conf` file is no longer used
- `qvm-run` tool got `--no-shell` option to run a single command without using
a shell inside the qube
- MAC Randomization for iwlwifi (see [#938](https://github.com/QubesOS/qubes-issues/issues/938))
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.1%22+label%3A%22release+notes%22+is%3Aclosed).

59
developer/releases/4_2/release-notes.md Normal file
View File

@ -0,0 +1,59 @@
---
layout: doc
title: Qubes OS 4.2.0 release notes
permalink: /doc/releases/4.2/release-notes/
---
## New features and improvements since Qubes 4.1
- 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 (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). 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 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
All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page.
## Installation instructions
See the [installation guide](/doc/installation-guide/).
## Upgrading
Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/).

20
developer/releases/4_2/schedule.md Normal file
View File

@ -0,0 +1,20 @@
---
lang: en
layout: doc
permalink: /doc/releases/4.2/schedule/
redirect_from:
- /en/doc/releases/4.2/schedule/
title: Qubes R4.2 release schedule
---
_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
The table below is based on our [release schedule
policy](/doc/version-scheme/#release-schedule).
| Date | Stage |
| ----------:| ----------------------------------------- |
| 2023-06-02 | 4.2.0-rc1 release |
| 2023-08-28 | 4.2.0-rc2 release |
| 2023-09-03 | 4.2.0-rc3 release |
| 2023-10-13 | 4.2.0-rc4 release |

15
developer/releases/notes.md
View File

@ -6,10 +6,11 @@ ref: 13
title: Release notes
---
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
* [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/)
- [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
- [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
- [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
- [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
- [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
- [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
- [Qubes R4.1 release notes](/doc/releases/4.1/release-notes/)
- [Qubes R4.2 release notes](/doc/releases/4.2/release-notes/)

11
developer/releases/schedules.md
View File

@ -6,8 +6,9 @@ ref: 15
title: Release schedules
---
* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
* [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/)
- [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
- [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
- [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
- [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)
- [Qubes R4.1 release schedule](/doc/releases/4.1/schedule/)
- [Qubes R4.2 release schedule](/doc/releases/4.2/schedule/)

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

@ -12,8 +12,11 @@ title: Version scheme
The Qubes OS Project uses the [semantic versioning](https://semver.org/)
standard. Version numbers are written as `<major>.<minor>.<patch>`. When
`<patch>` is zero, it is often omitted as a matter of convention, e.g., `4.1` is
short for `4.1.0`.
`<patch>` is omitted (e.g., `4.1`), it is usually either because `<patch>` is
zero (as in `4.1.0`) or because we are referring to a specific minor release
irrespective of any particular patch release within it. Similarly, the major
release number alone (e.g., `R4`) is sometimes used to refer to an entire
release series inclusive of all minor and patch releases within it.
In general, patch releases are for backward-compatible bug fixes, minor
releases are for backward-compatible enhancements and new features, and major
@ -24,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
@ -49,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 be no less than
1 and no more than 3 release candidates before 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 |
| ------------------------ | --------- |
@ -97,11 +108,11 @@ in `current` repository and the cycle starts over. There should be no less than
| 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)

11
developer/services/admin-api-table.md
View File

@ -1,11 +0,0 @@
---
lang: en
layout: fullscreen
permalink: /doc/admin-api/table/
ref: 249
title: Admin API table
---
This page displays the fullscreen table from [Admin API](/doc/admin-api/).
{% include admin-api-table.md %}

94
developer/services/admin-api.md
View File

@ -8,6 +8,7 @@ redirect_from:
- /doc/mgmt1/
- /doc/mgmt-architecture/
- /doc/admin-api-architecture/
- /doc/admin-api/table/
ref: 36
title: Admin API
---
@ -61,11 +62,94 @@ yet documented.
The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism.
[View this table on a fullscreen page.](/doc/admin-api/table/)
{% include admin-api-table.md %}
[View this table on a fullscreen page.](/doc/admin-api/table/)
| call | dest | argument | inside | return | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
| `admin.vm.Remove` | vm | - | - | - |
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
| `admin.label.Remove` | `dom0` | label | - | - |
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
| `admin.property.Get` | `dom0` | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.GetAll` | `dom0` | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.property.GetDefault` | `dom0` | property | - | `type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.Help` | `dom0` | property | - | `help` |
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
| `admin.property.Reset` | `dom0` | property | - | - |
| `admin.property.Set` | `dom0` | property | value | - |
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
| `admin.vm.property.Get` | vm | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.GetAll` | vm | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.vm.property.GetDefault` | vm | property | - | `type={str|int|bool|vm|label|type} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.Help` | vm | property | - | `help` |
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
| `admin.vm.property.Reset` | vm | property | - | - |
| `admin.vm.property.Set` | vm | property | value | - |
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
| `admin.vm.feature.Get` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature | - | value |
| `admin.vm.feature.Remove` | vm | feature | - | - |
| `admin.vm.feature.Set` | vm | feature | value | - |
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
| `admin.vm.tag.Remove` | vm | tag | - | - |
| `admin.vm.tag.Set` | vm | tag | - | - |
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.Set.persistent`| vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=True` for "persistently" attached devices (default is temporary)
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
| `admin.pool.Remove` | `dom0` | pool | - | - |
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
| `admin.pool.volume.Set.revisions_to_keep`| `dom0` | pool | `<vid> <value>` | - |
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
| `admin.vm.volume.Set.revisions_to_keep`| vm | volume | value | - |
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
| `admin.vm.Start` | vm | - | - | - |
| `admin.vm.Shutdown` | vm | - | - | - |
| `admin.vm.Pause` | vm | - | - | - |
| `admin.vm.Unpause` | vm | - | - | - |
| `admin.vm.Kill` | vm | - | - | - |
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
| `admin.Events` | `dom0|vm` | - | - | events |
| `admin.vm.Stats` | `dom0|vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
Volume properties:

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.

2
developer/system/security-critical-code.md
View File

@ -15,7 +15,7 @@ Below is a list of security-critical (i.e., trusted) code components in Qubes OS
A successful attack against any of these components could compromise the system's security.
This code can be thought of as the Trusted Computing Base (TCB) of Qubes OS.
One of the main goals of the project is to keep the TCB to an absolute minimum.
The size of the current TCB is on the order order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes.
The size of the current TCB is on the order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes.
(In Windows, Linux, and Mac OSes, the amount of trusted code is typically on the order of tens of *millions* of lines of C code.)
For more information, see [Qubes Security Goals](/security/goals/).

51
developer/system/storage-pools.md
View File

@ -1,51 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/storage-pools/
ref: 57
title: Storage pools
---
Qubes OS R3.2 introduced the concept of storage drivers and pools. This feature
was a first step towards a saner storage API, which is heavily rewritten in R4.
See [here](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-storage.html)
for documentation on storage pools in R4.
A storage driver provides a way to store VM images in a Qubes OS system.
Currently, the default driver is `xen` which is the default way of storing
volume images as files in a directory tree like `/var/lib/qubes/`.
A storage pool driver can be identified either by the driver name with the
`driver` key or by the class name like this:
`class=qubes.storage.xen.XenStorage`. Because R3.2 doesn't use Python
`setup_hooks`, to actually use a short driver name for a custom storage driver,
you have to patch `qubes-core-admin`. You can use the `class` config key
instead, when your class is accessible by `import` in Python.
A pool (in R3.2) is configuration information which can be referenced when
creating a new VM. Each pool is saved in `storage.conf`. It has a name, a
storage driver and some driver specific configuration attached.
When installed, the system has, as you can see from the contents of
`/etc/qubes/storage.conf`, a pool named `default`. It uses the driver `xen`. The
default pool is special in R3.2. It will add `dir_path=/var/lib/qubes`
configuration value from `defaults[pool_config]`, if not overwritten.
Currently the only supported driver out of the box is `xen`. The benefit of
pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2
is that you can store your domains in multiple places.
You can add a pool to `storage.conf` like this:
```
[foo]
driver=xen
dir_path=/opt/qubes-vm
```
Now, when creating a new VM on the command-line, you may pass the `-Pfoo`
argument to `qvm-create` to have the VM images stored in pool `foo`. See also
`qvm-create --help`.
While the current API is not as clean and beautiful as the R4 API, it allows
you to write your own storage drivers e.g. for Btrfs today.

22
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:
@ -25,9 +27,9 @@ This is mounted as /rw and here is placed all VM private data. This includes:
- */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
**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`. 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.
**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:
@ -37,9 +39,9 @@ As the kernel is chosen in dom0, there must be some way to provide matching kern
Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
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. FIXME: "none" should be renamed to "custom".
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
---

4
introduction/contributing.md
View File

@ -48,10 +48,10 @@ interest and experience. For example, here are some common issue labels:
* [Help wanted](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
* [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22)
* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows-tools%22)
* [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22)
* [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20)
* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22)
* [Debian/Ubuntu](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%2FUbuntu%22)
Before you engage in an activity that will take you a significant amount of
time, like implementing a new feature, it's always good to contact us first,

71
introduction/faq.md
View File

@ -19,12 +19,23 @@ title: Frequently asked questions (FAQ)
### What is Qubes OS?
Qubes OS is a security-oriented operating system (OS).
The OS is the software that runs all the other programs on a computer.
Some examples of popular OSes are Windows, macOS, Android, and iOS.
Qubes is free and open-source software (FOSS).
This means that everyone is free to use, copy, and change the software in any way.
It also means that the source code is openly available so others can contribute to and audit it.
Qubes OS is a security-focused operating system that allows you to organize your digital life into compartments called "qubes." If one qube is compromised, the others remain safe, so a single cyberattack can no longer take down your entire digital life in one fell swoop. You can think of using Qubes OS as having many different computers on your desk for different activities but with the convenience of a single physical machine, a single unified desktop environment, and a set of tools for using qubes together securely as parts of a unified system.
### Is Qubes OS free and open-source software?
There are two distinct senses of the word "free" when it comes to free software. The difference in commonly expressed by the phrases "free as in beer" and "free as in speech."
The first senses is straightforward. Qubes OS is "free as in beer," meaning that it is provided at no cost (_gratis_), though [donations](/donate/) are greatly appreciated.
The second sense is more complicated. Qubes OS is *mostly* "free as in speech," but not entirely. All the software created by the Qubes OS Project *itself* is [free (or "libre")](https://www.gnu.org/philosophy/free-sw) and [open-source](https://opensource.org/docs/definition.html) software ([FOSS or FLOSS](https://www.gnu.org/philosophy/floss-and-foss.en.html)).
This means that everyone is allowed to use, copy, study, and change the software in accordance with its [license](/doc/license/).
It also means that the [source code](/doc/source-code/) is [publicly available](https://github.com/QubesOS/) so everyone can audit and contribute to it.
However, since Qubes OS is a security-focused operating system, it includes some non-free firmware that was not created by the Qubes OS Project (such as CPU microcode), which is necessary in order to protect against known security vulnerabilities.
Moreover, the [architecture](/doc/architecture/) of Qubes OS as a meta-operating system means that it incorporates other software (including entire operating systems) from various upstream projects, some of which may include non-free software of their own.
In order to make the installation process easier for a wide range of users across many different devices, standard Qubes [templates](/doc/templates/) also include some non-free firmware and drivers.
Also see: [Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?](#will-qubes-seek-to-get-certified-under-the-gnu-free-system-distribution-guidelines-gnu-fsdg)
### Why is OS security important?
@ -83,10 +94,6 @@ The main way Qubes OS [provides privacy](#how-does-qubes-os-provide-privacy) is
Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-Whonix qubes.
This includes [disposables](/doc/how-to-use-disposables/).
For example, a standard [Fedora](/doc/templates/fedora/) qube is expected to have basically the same privacy properties as that upstream Fedora distribution, enhanced to some degree by the control Qubes provides over that qube.
For most users, this level of privacy may be good enough for many common activities.
However, users seeking more advanced privacy features should use Whonix qubes.
Privacy is far more difficult than is commonly understood.
In addition to the [web browser](https://www.torproject.org/projects/torbrowser/design/), there is also [VM fingerprinting](https://www.whonix.org/wiki/VM_Fingerprinting) and [advanced deanonymization attacks](https://www.whonix.org/wiki/Advanced_Deanonymization_Attacks) that most users have never considered (and this is just to mention a few examples).
The [Whonix Project](https://www.whonix.org/) specializes in [protecting against these risks](https://www.whonix.org/wiki/Protocol-Leak-Protection_and_Fingerprinting-Protection).
@ -179,10 +186,7 @@ We believe that this is currently the only practically viable approach to implem
### Does Qubes use full disk encryption (FDE)?
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt).
You can even [manually configure your encryption parameters](/doc/custom-install/) if you like!
By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) to encrypt everything except the `/boot` partition.
### What do all these terms mean?
@ -273,7 +277,13 @@ tracking](/doc/issue-tracking).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
We wish we could, but the unfortunate reality right now is that an operating system *cannot be secure* without a certain minimum number of proprietary closed-source "blobs" (e.g., CPU microcode updates). A 100% free operating system that excludes all such blobs is vulnerable to known exploits and is therefore unsuitable for any use case where security matters.
Instead, Qubes aims to be as free as possible *without sacrificing security*. All of the code created by the Qubes OS Project itself is 100% free. However, in order for users to actually run that code securely on their hardware, we must pair it with a small number of non-free blobs, which disqualifies Qubes, [along with the vast majority of open-source Linux distributions](https://www.gnu.org/distros/common-distros.html), from GNU FSDG certification.
The [four essential freedoms](https://www.gnu.org/philosophy/free-sw.html) are part of the core of our philosophy, but so is security. Together, they inform our decisions and motivate our actions. Qubes aims to maximize both security and software freedom to the extent that they are compatible in the world today.
Also see [Is Qubes OS free and open-source software?](#is-qubes-os-free-and-open-source-software) and the Qubes OS [software license](/doc/license/).
### Should I trust this website?
@ -318,6 +328,16 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
If it seems like a feature that we can and should enable, please [let us know](/doc/issue-tracking/)!
### Why do the mailing lists require a Google account?
They don't. This is a common misconception. The mailing lists have never required a Google account. It has always been possible to use them purely via email (see the [mailing lists](/support/#mailing-lists) section for instructions).
A lot of people probably see that the mailing lists use Google Groups and just assume that a Google account must be required, but it's not true. Google Groups is simply used for the infrastructure. Of course, you *can* use the web interface with a Google account, but there are many people in the Qubes community who participate on the mailing lists without one.
### Why do you use Google Groups for the mailing lists?
For the same general reasons as listed in [FAQ: Why do you use GitHub?](/faq/#why-do-you-use-github)
## Users
### Can I watch YouTube videos in qubes?
@ -416,6 +436,10 @@ Some users have been able to do this, but it is neither recommended nor supporte
Qubes should be installed bare-metal.
(After all, it uses its own bare-metal hypervisor!)
### How many qubes should I have? What's a good way to organize them?
[How to organize your qubes](/doc/how-to-organize-your-qubes/) walks through several examples of how different types of users can set up their Qubes OS system to support their unique use cases.
### What is a terminal?
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator), nowadays often referred to as just a *terminal*, is a program which provides a text window.
@ -610,13 +634,14 @@ Qubes is slower when reading from the disk because of the VM overhead, which is
### Could you please make my preference the default?
Wouldn't it be great if Qubes were configured just the way you like it by default with all of your favorite programs and settings?
Then you could just install Qubes without having to install any programs in it or adjust any settings!
You might even think that if a particular program or setting works so well for *you*, it would work well for *everyone*, so you'd actually be doing everyone a favor!
It would be great if Qubes were configured just the way we like it by default with all of our favorite programs and settings.
Then, we could just install Qubes without having to install any programs in it or adjust any settings.
We might even think that if a particular program or setting works so well for *us*, it would work well for *everyone*, so we'd actually be doing everyone a favor!
The problem is that Qubes has [tens of thousands of different users](/statistics/) with radically different needs and purposes.
There is no particular configuration that will be ideal for everyone (despite how much you might feel that your preference would be better for everyone), so the best we can do is to put power in the hands of users to configure their Qubes installations the way they like (subject to security constraints, of course).
Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference.
This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
There is no particular configuration that will be ideal for everyone (despite how much we might feel that our preference would be better for everyone), so the best we can do is to put power in the hands of users to configure their Qubes installations the way they like (subject to security constraints, of course).
For this reason, we generally do not grant requests for people's favorite programs to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches the requester's preference.
See also: [What is Qubes’ attitude toward changing guest distros?](#what-is-qubes-attitude-toward-changing-guest-distros)
### Software installed in a qube is gone after restarting. Why?
@ -661,7 +686,7 @@ See the [Qubes Source Code Repositories](/doc/source-code/) article.
### What is Qubes' attitude toward changing guest distros?
We try to respect each distro's culture, where possible.
In general, we try to respect each distro's culture, but we reserve the right to make modifications that we deem appropriate.
See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example.
The policy is there mostly to ease maintenance, on several levels:
@ -769,7 +794,7 @@ UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very
Arguably secure boot reliance on UEFI integrity is not the best design.
The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](https://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
### What is the canonical way to detect Qubes VM?

12
introduction/getting-started.md
View File

@ -13,7 +13,8 @@ title: Getting started
---
After [downloading](/downloads/) and [installing](/doc/installation-guide/)
Qubes OS, it's time to dive in and get to work!
Qubes OS, it's time to dive in and get to work! (Already know your way around?
Dive right in to [organizing your qubes](/doc/how-to-organize-your-qubes/).)
## The Basics
@ -199,10 +200,10 @@ you want to partition some part of your life, you can easily create a new qube
for it. You'll also be able to easily [copy any
files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
Still not sure? You might find it helpful to read [this
article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html),
which describes how one of the Qubes OS architects partitioned her digital life
into security domains.
Want to see some examples? Check out our in-depth guide on [how to organize your
qubes](/doc/how-to-organize-your-qubes/), which walks through several common use
cases based on our user research and years of experience from veteran Qubes
users.
## Secure Habits
@ -221,6 +222,7 @@ Here are some basic tasks you're likely to want to perform often that are
unique to Qubes as a multi-environment system. A full list is available in the
[How-To Guides](/doc/#how-to-guides) section in the docs.
- [How to organize your qubes](/doc/how-to-organize-your-qubes/)
- [How to Update](/doc/how-to-update/)
- [How to Back Up, Restore, and Migrate](/doc/how-to-back-up-restore-and-migrate/)
- [How to Copy and Paste Text](/doc/how-to-copy-and-paste-text/)

2
introduction/intro.md
View File

@ -248,6 +248,8 @@ title: Introduction
own mistakes. It's a place where you can click on links, open attachments,
plug in devices, and install software free from worry. It's a place where
<em>you</em> have control over your software, not the other way around.
(See some <a href="/doc/how-to-organize-your-qubes/">examples of how
different types of users organize their qubes</a>.)
</p>
<p>
Qubes is also powerful. Organizations like the <a

315
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,306 +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
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 **types**: `T: bug`, `T: enhancement`, and `T: task`.
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 things that already exist. If something doesn't exist yet, but you
think it should exist, then `T: enhancement`. If something already exists and
could be improved in some way, `T: enhancement` is appropriate. `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 **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`.
### Milestones
#### Affected release
The issue tracker has several
[milestones](https://github.com/QubesOS/qubes-issues/milestones). Every issue
should be assigned to **exactly one** milestone. The issue tracker does not
allow assigning an issue 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. No open issue should lack a milestone
assignment.
Most milestones correspond to specific Qubes OS releases. A bug report assigned
to a release milestone indicates an alleged bug *in* that Qubes OS release. A
task or enhancement assigned to a release milestone indicates that the goal is
to implement or do that thing *in* or *for* that Qubes OS release.
The `Release TBD` (To Be Determined) milestone is for enhancements or tasks
that will be specific to a Qubes OS release but have yet to be assigned to a
specific release milestone. Bug reports should never be assigned to this
milestone, because every bug is a problem or defect in something that already
exists.
The `Non-release` milestone is for issues that are independent of the Qubes OS
release cycle, including (but not limited to) website, documentation, and
project management issues. These are issues that will never be assigned to a
specific Qubes OS release milestone.
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%3Abug+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)
@ -337,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.

25
introduction/support.md
View File

@ -328,8 +328,8 @@ required for any of these mailing lists.
This is a read-only list for those who wish to receive only very important,
infrequent messages. Only the core Qubes team can post to this list. Only
[Qubes Security Bulletins (QSBs)](/security/qsb/), new stable releases,
and end-of-life notices are announced here.
[Qubes Security Bulletins (QSBs)](/security/qsb/), new stable Qubes OS releases,
and Qubes OS release end-of-life notices are announced here.
To subscribe, send a blank email to
`qubes-announce+subscribe@googlegroups.com`. (Note: A Google account is **not**
@ -499,10 +499,11 @@ too](https://forum.qubes-os.org/t/using-the-forum-via-email/533)!)
The Qubes OS Project has a presence on the following social media platforms:
* [Twitter](https://twitter.com/QubesOS)
* [Reddit](https://www.reddit.com/r/Qubes/)
* [Facebook](https://www.facebook.com/QubesOS/)
* [LinkedIn](https://www.linkedin.com/company/qubes-os/)
- <a rel="me" href="https://twitter.com/QubesOS">Twitter</a>
- <a rel="me" href="https://mastodon.social/@QubesOS">Mastodon</a>
- <a rel="me" href="https://www.reddit.com/r/Qubes/">Reddit</a>
- <a rel="me" href="https://www.facebook.com/QubesOS/">Facebook</a>
- <a rel="me" href="https://www.linkedin.com/company/qubes-os/">LinkedIn</a>
Generally speaking, these are not intended to be primary support venues. (Those
would be [qubes-users](#qubes-users) and the [forum](#forum).) Rather, these
@ -511,6 +512,11 @@ on the [news](/news/) page. If you use one of these platforms, you may find it
convenient to follow the Qubes OS Project there as a way of receiving Qubes
news.
## Chat
If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix
bridge: `#qubes:libera.chat`).
## Unofficial venues
If you find another venue on the Internet that is not listed above, it is
@ -521,10 +527,3 @@ moderate it. Please be especially careful in unofficial venues.
should not be taken as a commitment to monitor or moderate the venue. It still
remains unofficial. Also, please make sure someone claiming to be a Qubes team
member really is one. It could be an impostor!)
For example, here are some **unofficial** chat channels we know about that are
maintained by the community:
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
* Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
* `#qubes` channel on libera.chat via traditional IRC clients

16
introduction/video-tours.md
View File

@ -6,6 +6,20 @@ ref: 226
title: Video tours
---
## Qubes OS Summit 2022
Watch all the talks from Qubes OS Summit 2022, which took place September 9-11, 2022 in Berlin, Germany.
<div class="video more-bottom">
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://www.youtube-nocookie.com/embed/hkWWz3xGqS8"></iframe>
</div>
<div class="video more-bottom">
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://www.youtube-nocookie.com/embed/A9GrlQsQc7Q"></iframe>
</div>
<div class="video more-bottom">
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://www.youtube-nocookie.com/embed/gnWHjv-9_YM"></iframe>
</div>
## Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"
[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-) at the [Circle of HOPE](https://www.hope.net/index.html) conference, which took place July 20-22, 2018 in New York City.
@ -16,6 +30,6 @@ title: Video tours
## Explaining Computers presents "Qubes OS: Security Oriented Operating System"
<div class="video more-top">
<div class="video">
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://www.youtube-nocookie.com/embed/hWDvS_Mp6gc"></iframe>
</div>

24
project-security/canary-checklist.md
View File

@ -1,24 +0,0 @@
---
lang: en
layout: doc
permalink: /security/canary/checklist/
redirect_from:
- /security/canaries/checklist/
ref: 216
title: Qubes canary checklist
---
## Preparation
* Draft canary and push to private repository
* Finalize canary, sign, and add signed tags
## Announcement
* Push canary to public repository
* Publish a [news post](/news/) using the [Canary
Template](/security/canary/template/)
* Send the content of the news post to the appropriate [mailing
lists](/support/)
* Share link to news post on social media
* Set a reminder for the next canary

12
project-security/canary-template.md
View File

@ -1,12 +0,0 @@
---
lang: en
layout: doc
permalink: /security/canary/template/
redirect_from:
- /security/canaries/template/
- /doc/canaries/template/
redirect_to:
- https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-template.txt
ref: 212
title: Qubes canary template
---

29
project-security/canary.md
View File

@ -1,29 +0,0 @@
---
lang: en
layout: doc
permalink: /security/canary/
redirect_from:
- /security/canaries/
- /doc/canaries/
ref: 208
title: Qubes canaries
---
A **Qubes canary** is a security announcement periodically issued by the [Qubes
security team](/security/#qubes-security-team) through the [Qubes security
pack](/security/pack/) consisting of several statements to the effect that the
signers of the canary have not been compromised. The idea is that, as long as
signed canaries including such statements continue to be published, all is
well. However, if the canaries should suddenly cease, if one or more signers
begin declining to sign them, or if the included statements change
significantly without plausible explanation, then this may indicate that
something has gone wrong.
The name originates from the practice in which miners would bring caged
canaries into coal mines. If the level of methane gas in the mine reached a
dangerous level, the canary would die, indicating to miners that they should
evacuate. See [Wikipedia: warrant
canary](https://en.wikipedia.org/wiki/Warrant_canary) for more information, but
bear in mind that Qubes Canaries are not strictly limited to legal warrants.
## Full list

8
project-security/pgp-keys.md
View File

@ -1,8 +0,0 @@
---
lang: en
layout: doc
permalink: /security/pgp-keys/
redirect_to: https://keys.qubes-os.org/keys/
ref: 250
title: PGP keys
---

26
project-security/qsb-checklist.md
View File

@ -1,26 +0,0 @@
---
lang: en
layout: doc
permalink: /security/qsb/checklist/
redirect_from:
- /security/bulletins/checklist/
- /doc/security-bulletins/checklist/
ref: 215
title: Qubes security bulletin (QSB) checklist
---
## Preparation
* Draft QSB and push to private repository
* Build fixed packages
* Finalize QSB, sign, and add signed tags
## Announcement
* Upload packages to `security-testing` and `current-testing` repositories
* Push QSB to public repository
* Publish a [news post](/news/) using the [QSB
Template](/security/qsb/template/)
* Send the content of the news post to the appropriate [mailing
lists](/support/)
* Share link to news post on social media

12
project-security/qsb-template.md
View File

@ -1,12 +0,0 @@
---
lang: en
layout: doc
permalink: /security/qsb/template/
redirect_from:
- /security/bulletins/template/
- /doc/security-bulletins/template/
redirect_to:
- https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-template.txt
ref: 209
title: Qubes security bulletin (QSB) template
---

22
project-security/qsb.md
View File

@ -1,22 +0,0 @@
---
lang: en
layout: doc
permalink: /security/qsb/
redirect_from:
- /security/bulletins/
- /doc/security-bulletins/
- /en/doc/security-bulletins/
- /doc/SecurityBulletins/
- /wiki/SecurityBulletins/
- /trac/wiki/SecurityBulletins/
ref: 218
title: Qubes security bulletins (QSBs)
---
A **Qubes security bulletin (QSB)** is a security announcement issued by the
[Qubes security team](/security/#qubes-security-team) through the [Qubes
security pack](/security/pack/). A QSB typically provides a summary and impact
analysis of one or more recently-discovered software vulnerabilities, including
details about patching to address them.
## Full list

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

@ -108,7 +108,8 @@ never leave this isolated machine.
Before we proceed, you must first complete the prerequisite step of [installing
OpenPGP software](#openpgp-software).
Now, there are several ways to get the QMSK.
Once you have appropriate OpenPGP software installed, there are several ways to
get the QMSK.
- If you're on Qubes OS, it's available in every
qube ([except dom0](https://github.com/QubesOS/qubes-issues/issues/2544)):
@ -170,31 +171,66 @@ 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),
[discussion
forums](https://forum.qubes-os.org/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw),
forums](https://forum.qubes-os.org/t/1441/9),
[social](https://twitter.com/rootkovska/status/496976187491876864)
[media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/),
[personal websites](https://andrewdavidwong.com/fingerprints.txt)).
@ -203,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.).
@ -214,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
@ -292,12 +328,11 @@ Before we proceed, you must first complete the following prerequisite steps:
1. [Install OpenPGP software.](#openpgp-software)
2. [Import and authenticate the QMSK.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
The first step is to obtain the correct RSK. The filename of the RSK for your
Qubes OS release is usually `qubes-release-X-signing-key.asc`, where `X` is the
[major version number](https://semver.org/) of your Qubes release. For example,
if you were installing release `1.2.3`, you would replace `X` with `1`,
resulting in `qubes-release-1-signing-key.asc`. There are several ways to get
the RSK for your Qubes release.
After you have completed these two prerequisite steps, the next step is to
obtain the correct RSK. The filename pattern for RSKs is
`qubes-release-X-signing-key.asc`, where `X` is either a major or minor Qubes
release number, such as `4` or `4.2`. There are several ways to get the RSK for
your Qubes release.
- If you have access to an existing Qubes installation, the release keys are
available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`. These can be
@ -550,6 +585,138 @@ If you don't see a good signature here, go back and follow the instructions in
this section carefully, and consult the [troubleshooting
FAQ](#troubleshooting-faq) below.
## How to re-verify installation media after writing
_This is an optional section intended for advanced users._
After you have authenticated your Qubes ISO and written it onto your desired
medium (such as a USB drive or optical disc), you can re-verify the data that
has been written to your medium. Why would you want to do this when you've
already verified the original ISO? Well, it's conceivable that a sufficiently
sophisticated adversary might allow your initial ISO verification to succeed
(so as not to alert you that your machine has been compromised, for example),
then surreptitiously modify the data as it is being written onto your
installation medium, resulting in a compromised Qubes installer. This might
increase the odds that the attack goes undetected. One way to mitigate this
risk is to re-verify the installer after writing it onto an installation medium
that cannot be altered, such as a USB drive with a properly-implemented
physical write-protect switch and firmware that is either unflashable or
cryptographically-signed (or both), as discussed in our [installation security
considerations](/doc/install-security/).
This section will walk through an example of re-verifying the installer on such
a device. We begin by assuming that you have just [written your desired Qubes
ISO onto the USB
drive](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium).
First, unplug your USB drive and flip the write protect switch so that the data
on the drive can no longer be altered. If you have a different computer from
the one you used to create the installation medium, consider using that
computer. If not, try to at least use a fresh VM (e.g., if it's a Qubes
system). The idea is that the original machine may have been compromised, and
using a different one for re-verification forces your hypothetical adversary to
compromise an additional machine in order to succeed.
Now, our goal is to perform the same verification steps as we did with the
original ISO, except, this time, we'll be reading the installer data directly
from the write-protected USB drive instead of from the original ISO file.
First, let's compute the SHA-256 hash value of the data on the drive. (This
assumes you're already familiar with [how to verify the cryptographic hash
values of Qubes
ISOs](#how-to-verify-the-cryptographic-hash-values-of-qubes-isos).) In order to
do this, we have to know the exact size, in bytes, of the original ISO. There
are two ways to get this information: from the ISO itself and from the Qubes
website. Here's an example of the first way:
```shell_session
$ dd if=/dev/sdX bs=1M count=$(stat -c %s /path/to/iso) iflag=count_bytes | sha256sum
```
(Where `/dev/sdX` is your USB drive and `/path/to/iso` is the path to your Qubes
ISO.)
This command reads exactly the number of bytes of your Qubes ISO (obtained with
`stat -c %s /path/to/iso`) from the USB drive and pipes them into `sha256sum`.
The output should look something like this:
```shell_session
0e68dd3347b68618d9e5f3ddb580bf7ecdd2166747630859b3582803f1ca8801 -
5523+0 records in
5523+0 records out
5791285248 bytes (5.8 GB, 5.4 GiB) copied, 76.3369 s, 75.9 MB/s
```
Note that your actual SHA-256 hash value and byte number will depend on which
Qubes ISO you're using. This is just an example. Your SHA-256 hash value should
match the hash value of your genuine original Qubes ISO.
Now, reading the number of bytes directly from the ISO is fine, but you may be
concerned that a sufficiently sophisticated adversary may have compromised the
machine on which you're performing this re-verification and may therefore be
capable of feeding you a false success result. After all, if your adversary
knows the answer you're looking for --- namely, a match to the genuine ISO ---
and has access to that very ISO in the same re-verification environment, then
there is little to prevent him from simply hashing the original ISO and feeding
you that result (perhaps while also reading from the USB drive and piping it
into `/dev/null` so that you see the light on the USB drive blinking to support
the illusion that the data is being read from the USB drive).
Therefore, in order to make things a bit more difficult for your hypothetical
adversary, you may instead wish to perform the re-verification in an
environment that has never seen the original ISO, e.g., a separate offline
computer or a fresh VM the storage space of which is too small to hold the ISO.
(Note: If you're doing this in Qubes, you can attach the block device from
sys-usb to a separate new qube. You don't have to perform the re-verification
directly in sys-usb.) In that case, you'll have to obtain the size of the ISO
in bytes and enter it into the above command manually. You can, of course,
obtain the size by simply using the `stat -c %s /path/to/iso` command from
above on the machine that has the ISO. You can also obtain it from the Qubes
website by hovering over any ISO download button on the [downloads
page](/downloads/). (You can also view these values directly in the downloads
page's [source
data](https://github.com/QubesOS/qubesos.github.io/blob/master/_data/downloads.yml).)
Once you have the exact size of the ISO in bytes, simply insert it into the
same command, for example:
```shell_session
$ dd if=/dev/sdX bs=1M count=5791285248 iflag=count_bytes | sha256sum
```
If you wish to compute the values of other hash functions, you can replace
`sha256sum`, e.g., with `md5sum`, `sha1sum`, or `sha512sum`.
In addition to checking hash values, you can also use GnuPG to verify the
detached PGP signature directly against the data on the USB drive. (This
assumes you're already familiar with [how to verify detached PGP signatures on
Qubes ISOs](#how-to-verify-detached-pgp-signatures-on-qubes-isos).)
```shell_session
$ dd if=/dev/sdX bs=1M count=<ISO_SIZE> iflag=count_bytes | gpg -v --verify Qubes-RX-x86_64.iso.asc -
gpg: Signature made Thu 14 Jul 2022 08:49:38 PM PDT
gpg: using RSA key 5817A43B283DE5A9181A522E1848792F9E2795E9
gpg: using pgp trust model
gpg: Good signature from "Qubes OS Release X Signing Key" [full]
gpg: binary signature, digest algorithm SHA256, key algorithm rsa4096
5523+0 records in
5523+0 records out
5791285248 bytes (5.8 GB, 5.4 GiB) copied, 76.6013 s, 75.6 MB/s
```
(Where `/dev/sdX` is your USB drive, `<ISO_SIZE>` is the size of the original
ISO in bytes, and `Qubes-RX-x86_64.iso.asc` is the detached signature file of
the original ISO.)
This command reads the exact number of bytes from your USB drive as the size of
the original ISO and pipes them into `gpg`. The usual form of a `gpg`
verification command is `gpg --verify <SIGNATURE> <SIGNED_DATA>`. Our command
is using shell redirection in order to use data from your USB drive as the
`<SIGNED_DATA>`, which is why the `-` at the end of the command is required.
Remember that you still must have properly imported and trusted the
[QMSK](#how-to-import-and-authenticate-the-qubes-master-signing-key) and
appropriate [RSK](#how-to-import-and-authenticate-release-signing-keys) in
order for this to work. You should receive a `Good signature` message for the
appropriate RSK, which should be signed by a copy of the QMSK that you
previously confirmed to be genuine.
## How to verify signatures on Git repository tags and commits
Before we proceed, you must first complete the following prerequisite steps:

42
project-security/xsa.md
View File

@ -1,42 +0,0 @@
---
lang: en
layout: doc
permalink: /security/xsa/
ref: 214
title: Xen security advisory (XSA) tracker
---
This tracker shows whether Qubes OS is affected by any given [Xen security
advisory (XSA)](https://xenbits.xen.org/xsa/). Shortly after a new XSA is
published, we will add a new row to this tracker. Whenever Qubes is
significantly affected by an XSA, a [Qubes security bulletin
(QSB)](/security/qsb/) is published, and a link to that QSB is added to
the row for the associated XSA.
Under the "Is Qubes Affected?" column, there are two possible values: **Yes**
or **No**.
* **Yes** means that the *security* of Qubes OS *is* affected.
* **No** means that the *security* of Qubes OS is *not* affected.
## Important notes
* For the purpose of this tracker, we do *not* classify mere [denial-of-service
(DoS) attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack) as
affecting the *security* of Qubes OS. Therefore, if an XSA pertains *only* to
DoS attacks against Qubes, the value in the "Is Qubes Affected?" column will
be **No**.
* For simplicity, we use the present tense ("is affected") throughout this
page, but this does **not** necessarily mean that up-to-date Qubes
installations are *currently* affected by any particular XSA. In fact, it is
extremely unlikely that any up-to-date Qubes installations are vulnerable to
any XSAs on this page, since patches are almost always published concurrently
with QSBs. Please read the QSB (if any) for each XSA for patching details.
* Embargoed XSAs are excluded from this tracker until they are publicly
released, since the [Xen security
policy](https://www.xenproject.org/security-policy.html) does not permit us
to state whether Qubes is affected prior to the embargo date.
* Unused and withdrawn XSA numbers are included in the tracker for the sake of
completeness, but they are excluded from the [statistics](#statistics)
section for the sake of accuracy.
* All dates are in UTC.

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

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

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

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

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

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

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

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

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

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

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

@ -193,12 +193,12 @@ $ qubesctl --all state.highstate
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja](http://jinja.pocoo.org/).
This is most commonly done with [Jinja](https://palletsprojects.com/p/jinja/).
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
So you should take a look at the [Jinja API documentation](https://jinja.palletsprojects.com/templates/).
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation](https://docs.saltproject.io/en/getstarted/config/jinja.html#get-data-using-salt).
@ -605,6 +605,6 @@ install template and shutdown updateVM:
- [Salt states](https://docs.saltproject.io/en/latest/ref/states/all/) ([files](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.cmd.html),
[packages](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltproject.io/en/latest/ref/states/ordering.html))
- [Top files](https://docs.saltproject.io/en/latest/ref/states/top.html)
- [Jinja templates](http://jinja.pocoo.org/)
- [Jinja templates](https://palletsprojects.com/p/jinja/)
- [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
- [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)

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

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

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

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

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

@ -24,4 +24,4 @@ helpful in streamlining the process.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek](/team/#wojtek-porczyk) or [Marek](/team/#marek-marczykowski-górecki).
* For website updates and fixes, please contact [Andrew](/team/#andrew-david-wong).
* For website updates and fixes, please contact [unman](/team/#unman).

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

@ -18,7 +18,7 @@ No operating system, not even Qubes, can help you if you're installing it on har
This includes CPUs, GPUs, SSDs, HDDs, the motherboard, BIOS/EFI/UEFI, and all relevant firmware.
Unfortunately, in today's world of undetectable supply chain attacks, there are no easy solutions.
(Tools like [Anti Evil Maid (AEM)](/doc/anti-evil-maid/) can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](http://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](https://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
## Verifying the Qubes ISO

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

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

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

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

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

@ -7,101 +7,52 @@ ref: 147
title: Testing new releases and updates
---
Testing new Qubes OS releases and updates is one of the most helpful ways in
which you can [contribute](/doc/contributing/) to the Qubes OS Project. If
you're interested in helping with this, please [join the testing
team](https://forum.qubes-os.org/t/joining-the-testing-team/5190). There are
several different types of testing, which we'll cover below.
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute](/doc/contributing/) to the Qubes OS Project. If you're interested in helping with this, please [join the testing team](https://forum.qubes-os.org/t/joining-the-testing-team/5190). There are several different types of testing, which we'll cover below.
**Warning:** Software testing is intended for advanced users and developers.
You should only attempt to do this if you know what you're doing. Never rely on
code that is in testing for critical work!
**Warning:** Software testing is intended for advanced users and developers. You should only attempt to do this if you know what you're doing. Never rely on code that is in testing for critical work!
## Releases
How to test upcoming Qubes OS releases:
* Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
* Test the latest release candidate (RC), if one is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at
[Qubes OpenQA](https://openqa.qubes-os.org/).
- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself.
- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
See [Version Scheme](/doc/version-scheme/) for details about release versions
and schedules. See [Release Checklist](/doc/releases/todo/) for details about
the RC process.
See [Version scheme](/doc/version-scheme/) for details about release versions and schedules. See [Release checklist](/doc/releases/todo/) for details about the RC process.
## Updates
How to test updates:
* Enable [dom0 testing
repositories](/doc/how-to-install-software-in-dom0/#testing-repositories).
* Enable [template testing
repositories](/doc/how-to-install-software/#testing-repositories).
- Enable [dom0 testing repositories](/doc/how-to-install-software-in-dom0/#testing-repositories).
- Enable [template testing repositories](/doc/how-to-install-software/#testing-repositories).
Every new update is first uploaded to the `security-testing` repository if it
is a security update or `current-testing` if it is a normal update. The update
remains in `security-testing` or `current-testing` for a minimum of one week.
On occasion, an exception is made for a particularly critical security update,
which is immediately pushed to the `current` stable repository. In general,
however, security updates remain in `security-testing` for two weeks before
migrating to `current`. Normal updates generally remain in `current-testing`
until they have been sufficiently tested by the community, which can last weeks
or even months, depending on the amount of feedback received (see [Providing
feedback](#providing-feedback)).
Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update. The update remains in `security-testing` or `current-testing` for a minimum of one week. On occasion, an exception is made for a particularly critical security update, which is immediately pushed to the `current` stable repository. In general, however, security updates remain in `security-testing` for two weeks before migrating to `current`. Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can last weeks or even months, depending on the amount of feedback received (see [Providing feedback](#providing-feedback)).
"Sufficient testing" is, in practice, a fluid term that is up the developers'
judgment. In general, it means either that no negative feedback and at least
one piece of positive feedback has been received or that the package has been
in `current-testing` for long enough, depending on the component and the
complexity of the changes.
"Sufficient testing" is, in practice, a fluid term that is up the developers' judgment. In general, it means either that no negative feedback and at least one piece of positive feedback has been received or that the package has been in `current-testing` for long enough, depending on the component and the complexity of the changes.
A limitation of the current testing setup is that it is only possible to
migrate the *most recent version* of a package from `current-testing` to
`current`. This means that, if a newer version of a package is uploaded to
`current-testing`, it will no longer be possible to migrate any older versions
of that same package from `current-testing` to `current`, even if one of those
older versions has been deemed stable enough. While this limitation can be
inconvenient, the benefits outweigh the costs, since it greatly simplifies the
testing and reporting process.
A limitation of the current testing setup is that it is only possible to migrate the *most recent version* of a package from `current-testing` to `current`. This means that, if a newer version of a package is uploaded to `current-testing`, it will no longer be possible to migrate any older versions of that same package from `current-testing` to `current`, even if one of those older versions has been deemed stable enough. While this limitation can be inconvenient, the benefits outweigh the costs, since it greatly simplifies the testing and reporting process.
## Templates
How to test [templates](/doc/templates/):
* For official templates, enable the `qubes-templates-itl-testing` repository,
then [install](/doc/templates/#installing) the desired template.
* For community templates, enable the `qubes-templates-community-testing`
repository, then [install](/doc/templates/#installing) the desired template.
- For official templates, enable the `qubes-templates-itl-testing` repository, then [install](/doc/templates/#installing) the desired template.
- For community templates, enable the `qubes-templates-community-testing` repository, then [install](/doc/templates/#installing) the desired template.
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. Example commands:
```
sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing
sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing
qvm-template --enablerepo=qubes-templates-itl-testing list --available
qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
```
To enable or disable any of these repos permanently, change the corresponding
`enabled` value to `1` in `/etc/yum.repos.d/qubes-templates.repo`.
To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`. To disable any of these repos permanently, change the corresponding `enabled` value to `0`.
## Providing feedback
Since the whole point of testing software is to discover and fix bugs, your
feedback is an essential part of this process.
We use an [automated build
process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md).
For every package that is uploaded to a testing repository, a GitHub issue is
created in the
[updates-status](https://github.com/QubesOS/updates-status/issues) repository
for tracking purposes. We welcome any kind of feedback on any package in any
testing repository. Even a simple <span class="fa fa-thumbs-up" title="Thumbs
Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on
the package's associated issue would help us to decide whether the package is
ready to be migrated to a stable repository. If you [report a
bug](/doc/issue-tracking/) in a package that is in a testing repository, please
reference the appropriate issue in
[updates-status](https://github.com/QubesOS/updates-status/issues).
Since the whole point of testing software is to discover and fix bugs, your feedback is an essential part of this process. We use an [automated build process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md). For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository for tracking purposes. We welcome any kind of feedback on any package in any testing repository. Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> "thumbs up" or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> "thumbs down" reaction on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository. If you [report a bug](/doc/issue-tracking/) in a package that is in a testing repository, please reference the appropriate issue in [updates-status](https://github.com/QubesOS/updates-status/issues).

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

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

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

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

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

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

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

@ -10,175 +10,96 @@ ref: 144
title: Certified hardware
---
The Qubes OS Project aims to partner with a select few computer vendors to
ensure that Qubes users have reliable hardware purchasing options. We aim for
these vendors to be as diverse as possible in terms of geography, cost, and
availability.
The Qubes OS Project aims to partner with a select few computer vendors to ensure that Qubes users have reliable hardware purchasing options. We aim for these vendors to be as diverse as possible in terms of geography, cost, and availability.
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> The Qubes OS Project certifies only that a particular
hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is
available to purchase with Qubes OS preinstalled. We take no responsibility
for any vendor's manufacturing, shipping, payment, or other practices; nor
can we control whether physical hardware is modified (whether maliciously or
otherwise) <i>en route</i> to the user.
<b>Warning:</b> The Qubes OS Project certifies only that a particular hardware <em>configuration</em> is <em>supported</em> by Qubes OS and is available to purchase with Qubes OS preinstalled. We take no responsibility for any vendor's manufacturing, shipping, payment, or other practices; nor can we control whether physical hardware is modified (whether maliciously or otherwise) <i>en route</i> to the user.
</div>
You may also be interested in the [community-recommended
hardware](https://forum.qubes-os.org/t/5560) list and the [hardware
compatibility list (HCL)](/hcl/).
You may also be interested in the [community-recommended hardware](https://forum.qubes-os.org/t/5560) list and the [hardware compatibility list (HCL)](/hcl/).
## Qubes-certified Laptops
## Qubes-certified computers
Qubes-certified laptops are certified for a [major
release](/doc/version-scheme/) and regularly tested by the Qubes developers to
ensure compatibility with all of Qubes' features within that major release. The
developers test all new updates within that major release to ensure that no
regressions are introduced.
Qubes-certified computers are certified for a [major release](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major release. The developers test all new updates within that major release to ensure that no regressions are introduced.
The current Qubes-certified models are listed below in chronological order of certification.
### Insurgo PrivacyBeast X230
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast
X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
meets and exceeds our hardware certification requirements for Qubes 4. Read our
[announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) of
the certification for further details!
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) for details.
### NitroPad X230
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
satisfies all hardware certification requirements for Qubes 4, offering users
extensive hardware security options. Read our
[announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) of the
certification for further details!
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for details.
### NitroPad T430
[![nitropad-t-430.jpg](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
satisfies all hardware certification requirements for Qubes 4, offering users
extensive hardware security options. Read our
[announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) of the
certification for further details!
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for details.
### Dasharo FidelisGuard Z690
## Become Hardware Certified
[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
If you are a hardware vendor, you can have your hardware certified as
compatible with Qubes OS. The benefits of hardware certification include:
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) for details.
- Your customers can purchase with confidence, knowing that they can take full
advantage of Qubes OS on your hardware for a specific major version.
- We will continue testing your hardware to ensure compatibility with the
supported major version. In the course of this testing, we will also test
your hardware against upcoming versions, which can help with future planning.
- Your hardware will continue to be compatible with Qubes OS as it further
develops within that major version, and we will work with you toward
preserving compatibility and certification in future releases.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/)
The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for details.
### NitroPC Pro
[![Photo of the NitroPC Pro](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/product/nitropc-pro-523)
The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is a desktop based on the MSI PRO Z690-A DDR5 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/09/06/nitropc-pro-qubes-certified/) for details.
## Become hardware certified
If you are a hardware vendor, you can have your hardware certified as compatible with Qubes OS. The benefits of hardware certification include:
- Your customers can purchase with confidence, knowing that they can take full advantage of Qubes OS on your hardware for a specific major version.
- We will continue testing your hardware to ensure compatibility with the supported major version. In the course of this testing, we will also test your hardware against upcoming versions, which can help with future planning.
- Your hardware will continue to be compatible with Qubes OS as it further develops within that major version, and we will work with you toward preserving compatibility and certification in future releases.
- You can support the development of Qubes OS.
## Hardware Certification Requirements
## Hardware certification requirements
(Please note that these are the requirements for hardware *certification*,
*not* the requirements for *running* Qubes OS. For the latter, please see the
[system requirements](/doc/system-requirements/).)
**Note:** This section describes the requirements for hardware *certification*, *not* the requirements for *running* Qubes OS. For the latter, please see the [system requirements](/doc/system-requirements/). A brief list of the requirements described in this section is available [here](/doc/system-requirements/#qubes-certified-hardware).
A basic requirement is that all Qubes-certified devices must be be available
for purchase with Qubes OS preinstalled. Customers may be offered the option to
select from a list of various operating systems (or no operating system at all)
to be preinstalled, but Qubes OS must be on that list in order to maintain
Qubes hardware certification.
A basic requirement is that all Qubes-certified devices must be be available for purchase with Qubes OS preinstalled. Customers may be offered the option to select from a list of various operating systems (or no operating system at all) to be preinstalled, but Qubes OS must be on that list in order to maintain Qubes hardware certification.
One of the most important security improvements introduced with the release of
Qubes 4.0 was to replace paravirtualization (PV) technology with
**hardware-enforced memory virtualization**, which recent processors have made
possible thanks to so-called Second Level Address Translation
([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also
known as
[EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile)
in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization,
which originally was capable of only CPU virtualization but not memory
virtualization and hence required a complex Shadow Page Tables approach. We
hope that embracing SLAT-based memory virtualization will allow us to prevent
disastrous security bugs, such as the infamous
[XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many
other major Xen bugs --- regrettably did
[affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt)
Qubes OS. Consequently, we require SLAT support of all certified hardware
beginning with Qubes OS 4.0.
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance. SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach. We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS. Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
Another important requirement is that Qubes-certified hardware should run only
**open-source boot firmware** (aka "the BIOS"), such as
[coreboot](https://www.coreboot.org/). The only exception is the use of
(properly authenticated) CPU-vendor-provided blobs for silicon and memory
initialization (see [Intel
FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other
internal operations (see [Intel ME](https://www.apress.com/9781430265719)).
However, we specifically require all code used for and dealing with the System
Management Mode (SMM) to be open-source.
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot](https://www.coreboot.org/). The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other internal operations (see [Intel ME](https://www.apress.com/9781430265719)). However, we specifically require all code used for and dealing with the System Management Mode (SMM) to be open-source.
While we
[recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the
potential problems that proprietary CPU-vendor code can cause, we are also
pragmatic enough to realize that we need to take smaller steps first, before we
can implement even stronger countermeasures such as a [stateless
laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A
switch to open source boot firmware is one such important step. To be
compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and
SLAT functionality that the underlying hardware offers (and which we require).
Among other things, this implies **proper DMAR ACPI table** construction.
While we [recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf). A switch to open source boot firmware is one such important step. To be compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and SLAT functionality that the underlying hardware offers (and which we require). Among other things, this implies **proper DMAR ACPI table** construction.
Finally, we require that Qubes-certified hardware does not have any built-in
_USB-connected_ microphones (e.g. as part of a USB-connected built-in camera)
that cannot be easily physically disabled by the user, e.g. via a convenient
mechanical switch. Thankfully, the majority of laptops on the market that we
have seen already satisfy this condition out-of-the-box, because their built-in
microphones are typically connected to the internal audio device, which itself
is a type of PCIe device. This is important, because such PCIe audio devices
are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through
our carefully designed protocol only to select app qubes when the user
explicitly chooses to do so. The rest of the time, they should be outside the
reach of malware.
Most laptops use PS/2 connections internally for their input devices (i.e., keyboard and touchpad). On most desktops, however, USB-connected keyboards and mice have become standard. This presents a dilemma when the computer has only one USB controller. If that single USB controller is dedicated solely to the input devices, then no untrusted USB devices can be used. Conversely, if the sole USB controller is completely untrusted, then there is no way for the user to physically control the system in a secure way. In practice, Qubes users on such hardware systems are generally forced to use a single USB controller for both trusted and untrusted purposes --- [an unfortunate security trade-off](/doc/device-handling-security/#security-warning-on-usb-input-devices). For this reason, we require that every Qubes-certified non-laptop device **either** (1) supports non-USB input devices (e.g., via PS/2) **or** (2) has a separate USB controller that is only for input devices.
While we also recommend a physical kill switch on the built-in camera (or, if
possible, not to have a built-in camera), we also recognize this isn't a
critical requirement, because users who are concerned about it can easily cover
it a piece of tape (something that, regrettably, is far less effective on a
microphone).
Finally, we require that Qubes-certified hardware does not have any built-in _USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) that cannot be easily physically disabled by the user, e.g. via a convenient mechanical switch. Thankfully, the majority of laptops on the market that we have seen already satisfy this condition out-of-the-box, because their built-in microphones are typically connected to the internal audio device, which itself is a type of PCIe device. This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select app qubes when the user explicitly chooses to do so. The rest of the time, they should be outside the reach of malware.
Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth
devices to be mandatory. Users who plan on using Qubes in an air-gap scenario
would do best if they manually remove all such devices persistently (as well as
the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely
on easy-to-flip-by-mistake switches, while others should benefit from the Qubes
default sandboxing of all networking devices in dedicated VMs.
While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).
We hope these hardware requirements will encourage the development of more
secure and trustworthy devices.
Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth devices to be mandatory. Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
## Hardware Certification Process
We hope these hardware requirements will encourage the development of more secure and trustworthy devices.
## Hardware certification process
To have hardware certified, the vendor must:
1. Send the Qubes team two (2) units for testing (non-returnable) for each
configuration the vendor wishes to be offering.
2. Offer to customers the very same configuration (same motherboard, same
screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the
hardware vendor and the Qubes team.
1. Send the Qubes team two (2) units for testing (non-returnable) for each configuration the vendor wishes to be offering.
2. Offer to customers the very same configuration (same motherboard, same screen, same BIOS version, same Wi-Fi module, etc.) for at least one year.
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team.
It is the vendor's responsibility to ensure the hardware they wish to have
certified can run Qubes OS, at the very least the latest stable version. This
could be done by consulting the [Hardware Compatibility List](/hcl/) or trying
to install it themselves before shipping any units to us. While we are willing
to troubleshoot simple issues, we will need to charge a consulting fee for more
in-depth work.
It is the vendor's responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version. This could be done by consulting the [Hardware Compatibility List](/hcl/) or trying to install it themselves before shipping any units to us. While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
If you are interested in having your hardware certified, please [contact
us](mailto:business@qubes-os.org).
If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org).

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

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

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

@ -26,7 +26,9 @@ title: System requirements
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 6 GB RAM
- **Storage:** 32 GB free space
## Recommended
@ -34,19 +36,37 @@ title: System requirements
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 16 GB RAM
- **Storage:** 128 GB free space
- High-speed solid-state drive strongly recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant
[troubleshooting](/doc/install-nvidia-driver/)
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and
earlier) generally work well
- **Peripherals:** A non-USB keyboard or multiple USB controllers
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for
[Anti Evil Maid](/doc/anti-evil-maid/))
- **Other:** Satisfaction of all [hardware certification requirements for Qubes
4.x](/news/2016/07/21/new-hw-certification-for-q4/)
### Qubes-certified hardware
The following are *required* for [Qubes-certified hardware
devices](/doc/certified-hardware/) but *merely recommended* for *non-certified*
hardware (see the [hardware certification
requirements](/doc/certified-hardware/#hardware-certification-requirements) for
details).
- Open-source boot firmware (e.g., [coreboot](https://www.coreboot.org/))
- Hardware switches for all built-in USB-connected microphones (if any)
- Either support for non-USB input devices (e.g., via PS/2, which most laptops
already use internally) or a separate USB controller only for input devices
## Choosing Hardware

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

8
user/reference/glossary.md
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -52,7 +52,7 @@ There are two ways to upgrade your template to a new Debian release:
- **Recommended:** [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- **Advanced:** [Perform an in-place upgrade of an existing Debian template.](/doc/template/debian/upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
- **Advanced:** [Perform an in-place upgrade of an existing Debian template.](/doc/templates/debian/in-place-upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
## Release-specific notes

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

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

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

@ -44,4 +44,4 @@ There are two ways to upgrade your template to a new Fedora release:
- **Recommended:** [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
- **Advanced:** [Perform an in-place upgrade of an existing Fedora template.](/doc/template/fedora/upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
- **Advanced:** [Perform an in-place upgrade of an existing Fedora template.](/doc/templates/fedora/in-place-upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**

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

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

108
user/templates/templates.md
View File

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -13,7 +13,7 @@ title: Xfce templates
---
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/), or [Gentoo](/doc/templates/gentoo/).
## Installation

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

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

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

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

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

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