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

Update guide to 4.2 - Fix merge

This commit is contained in:
unman 2024-04-22 16:11:00 +00:00
parent 3042d62e55 a2c90e3313
commit 50b5e7fb4f
No known key found for this signature in database
GPG Key ID: BB52274595B71262
100 changed files with 2346 additions and 1273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_dev/conf.py
View File

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

6
developer/building/qubes-builder-details.md
View File

@ -10,6 +10,12 @@ ref: 65
title: Qubes builder details
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> This information concerns the old Qubes builder (v1). It supports
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.</div>
Components Makefile.builder file
--------------------------------

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

@ -10,6 +10,12 @@ ref: 64
title: Qubes builder
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
</div>
**Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**

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

@ -12,6 +12,12 @@ ref: 63
title: Qubes ISO building
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be be used for building Qubes R4.1 and later, and all related components.
</div>
Build Environment
-----------------

9
developer/code/code-signing.md
View File

@ -65,7 +65,9 @@ Currently, [these](https://github.com/marmarek/signature-checker/blob/master/che
In the example below, we will use `keyserver.ubuntu.com`.
Replace 6E2F4E7AF50A5827 with your key ID, which is the last 8 hex digits of the long number in the second line of the output above:
Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID**
which is the last 16 hex digits of the long number in the second line
of the output above:
```
pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
87975838063F97A968D503266E2F4E7AF50A5827
@ -76,11 +78,6 @@ $ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827
gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com
```
```
$ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827
gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com
```
## Using PGP with Git
If you're submitting a patch via GitHub (or a similar Git server), please sign

98
developer/debugging/profiling.md
View File

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

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

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

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

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

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

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

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

@ -262,7 +262,7 @@ Duplicating documentation is almost always a bad idea. There are many reasons fo
### 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 Forum](https://forum.qubes-os.org/docs). 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 Forum](https://forum.qubes-os.org/docs) instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) 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 Forum 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.

2
developer/general/gsoc.md
View File

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

90
developer/general/gsod.md
View File

@ -6,9 +6,9 @@ ref: 242
title: Google Season of Docs (GSoD)
---
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).
Thank you for your interest in participating in the [2024 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2024 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).
## Instructional video series -- Qubes OS
## Update and Expand How-To Guides -- Qubes OS
### About the Qubes OS Project
@ -18,10 +18,62 @@ Qubes OS was launched in 2011 and has [received praise from security experts and
### The project's problem
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.
- Some of the existing content is stale. It refers to previous Qubes releases and has not yet been updated to the cover the latest stable release.
- There are important topic areas that the current guides do not completely cover, such as "understanding Qubes OS," "using Qubes OS in practice," "Qubes OS workflow for coding," "printing," and "audio."
- The guides do not consistently address users of all skill and experience levels (beginner, intermediate, and expert).
- Some of the guides lack relevant illustrations and screenshots.
- When the developers update a software tool, they should update all the guides that mentions this tool. However, there is currently no way for the developers to know which guides mention which tools.
### The project's scope
The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, Marta Marczykowska-Górecka, and Marek Marczykowski-Górecki, will supervise and support the writer.
### Measuring the project's success
We will consider the project successful if:
- Existing guides are updated to describe currently supported Qubes OS version
- Missing common guides are identified
- 2-3 new guides are written
### Timeline
| Dates | Action items |
| --------------- | --------------------------------------- |
| May | Orientation |
| June - November | Update & extend how-to guides |
| December | Final project evaluation and case study |
### Project budget
| Expense | Amount |
| --------------------------------------- | ------- |
| writer (10 hours/week, 6 months) | $12,000 |
| TOTAL | $12,000 |
### Additional information
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, 2020, and 2023 were successes, and the 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.
## Past Projects
You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
You can view the results of the project we had in 2023 [here](https://www.youtube.com/playlist?list=PLjwSYc73nX6aHcpqub-6lzJbL0vhLleTB).
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
### Instructional video series
#### The project's problem
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's scope
This project consists of creating a series of instructional videos that satisfy the following criteria:
- Prospective users who are not yet familiar with Linux or Qubes OS can easily understand and follow the videos.
@ -59,7 +111,7 @@ Below is an example of the content (which is already [documented](/doc/)) that t
- Passwordless root
- Anti Evil Maid
- Split GPG
- U2F proxy
- CTAP proxy
- YubiKey
- Whonix
- How to install and use a VPN in Qubes
@ -68,7 +120,7 @@ Below is an example of the content (which is already [documented](/doc/)) that t
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.
### Measuring the project's success
#### Measuring the project's success
We will consider the project successful if, after publication of the video series:
@ -76,34 +128,6 @@ We will consider the project successful if, after publication of the video serie
- 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).
### Timeline
| Dates | Action items |
| -------------- | --------------------------------------- |
| March | Orientation |
| April--October | Create Qubes OS video series |
| November | Final project evaluation and case study |
### Project budget
| Expense | Amount |
| --------------------------------------- | ------- |
| Video creator (20 hours/week, 6 months) | $12,000 |
| TOTAL | $12,000 |
### Additional information
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
You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
You can also view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
### Consolidate troubleshooting guides
**Project**: Consolidate troubleshooting guides

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

@ -4,8 +4,6 @@ title: Qubes OS 4.2.0 release notes
permalink: /doc/releases/4.2/release-notes/
---
_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
## New features and improvements since Qubes 4.1
- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982))
@ -13,7 +11,7 @@ _**Please note:** This page is still an unfinished draft in progress. It is bein
- Default Debian template upgraded to Debian 12
- Default Fedora and Debian templates use Xfce instead of GNOME ([#7784](https://github.com/QubesOS/qubes-issues/issues/7784))
- SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239))
- Several GUI applications rewritten, including:
- 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
@ -23,17 +21,38 @@ _**Please note:** This page is still an unfinished draft in progress. It is bein
- 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 and Split SSH management in Qubes Global Settings
- Split GPG management in Qubes Global Settings
- Qrexec services use new qrexec policy format by default (but old format is still supported) ([#8000](https://github.com/QubesOS/qubes-issues/issues/8000))
- Improved keyboard layout switching
For a full list, including more detailed descriptions, please see
[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed).
For a full list, including more detailed descriptions, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed). Below are some screenshots of the new and improved Qubes GUI tools.
The new Qubes OS Update tool:
[![Screenshot of the Qubes OS Update tool](/attachment/site/4-2_update.png)](/attachment/site/4-2_update.png)
The new Qubes OS Global Config tool:
[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_1.png)](/attachment/site/4-2_global-config_1.png)
[![Screenshot of the Qubes OS Global Config tool](/attachment/site/4-2_global-config_2.png)](/attachment/site/4-2_global-config_2.png)
The new Qubes OS Policy Editor tool:
[![Screenshot of the Qubes OS Policy Editor tool](/attachment/site/4-2_policy-editor.png)](/attachment/site/4-2_policy-editor.png)
## Known issues
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062))
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. (For more information, see issues [#5031](https://github.com/QubesOS/qubes-issues/issues/5031) and [#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.
- Templates restored in 4.2 from a pre-4.2 backup continue to target their original Qubes OS release repos. If you are using fresh templates on a clean 4.2 installation, or if you performed an [in-place upgrade from 4.1 to 4.2](/doc/upgrade/4.2/#in-place-upgrade), then this does not affect you. (For more information, see issue [#8701](https://github.com/QubesOS/qubes-issues/issues/8701).)
Also see the [full list of open bug reports affecting Qubes 4.2](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 all available bug fixes.
## Notes
- Qubes 4.2 does not support Debian 11 templates (see [supported template releases](/doc/supported-releases/#templates)). Please [upgrade your Debian templates](/doc/templates/debian/#upgrading) to Debian 12.
## Download

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

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

102
developer/services/qrexec.md
View File

@ -22,14 +22,14 @@ However, the OS needs a mechanism to allow the administrative domain (dom0) to f
For instance, when a user selects an application from the KDE menu, it should start in the selected VM.
Also, it is often useful to be able to pass stdin/stdout/stderr from an application running in a VM to dom0 (and the other way around).
(For example, so that a VM can notify dom0 that there are updates available for it).
By default, Qubes allows VMs initiate such communications in specific circumstances.
The qrexec framework generalizes this process by providing a remote procedure call (RPC) protocol for the Qubes architecture.
By default, Qubes allows VMs to initiate such communications in specific circumstances.
The qrexec framework generalizes this process by providing a remote procedure call (RPC) for the Qubes architecture.
It allows users and developers to use and design secure inter-VM tools.
## Qrexec basics: architecture and examples
Qrexec is built on top of *vchan*, a Xen library providing data links between VMs.
During domain startup , a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
During domain startup, a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
They are connected over a **vchan** channel.
`qrexec-daemon` listens for connections from a dom0 utility named `qrexec-client`.
Let's say we want to start a process (call it `VMprocess`) in a VM (`someVM`).
@ -47,18 +47,18 @@ For example, the following command creates an empty file called `hello-world.txt
$ qrexec-client -e -d someVM user:'touch hello-world.txt'
```
The string before the colon specifies what user to run the command as.
The `-e` flag tells `qrexec-client` to exit immediately after sending the execution request and receiving a status code from `qrexec-agent` (whether the process creation succeeded).
The string before the colon specifies which user will run the command.
The `-e` flag tells `qrexec-client` to exit immediately after sending the execution request and receiving a status code from `qrexec-agent` (if the process creation succeeded).
With this option, no further data is passed between the domains.
By contrast, the following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
```
$ qrexec-client -d someVM user:bash
```
The `qvm-run` command is heavily based on `qrexec-client`.
It also takes care of additional activities, e.g. starting the domain if it is not up yet and starting the GUI daemon.
Thus, it is usually more convenient to use `qvm-run`.
It also handles additional activities, e.g. starting the domain if the domain is not up yet and starting the GUI daemon.
It is usually more convenient to use `qvm-run`.
There can be an almost arbitrary number of `qrexec-client` processes for a given domain.
The limiting factor is the number of available vchan channels, which depends on the underlying hypervisor, as well the domain's OS.
@ -70,41 +70,43 @@ For more details on the qrexec framework and protocol, see "[Qubes RPC internals
Some common tasks (like copying files between VMs) have an RPC-like structure: a process in one VM (say, the file sender) needs to invoke and send/receive data to some process in other VM (say, the file receiver).
The Qubes RPC framework was created to securely facilitate a range of such actions.
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
Therefore the design decision was made to pass all control communication via dom0, that can enforce proper authorization.
Then, it is natural to reuse the already-existing qrexec framework.
Inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
The design decision was made to pass all control communication via dom0 which can enforce proper authorization.
It is therefore natural to reuse the already-existing qrexec framework.
Also, note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
There are cases when VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
Thus, the framework allows dom0 to be the RPC target as well.
Note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
There are cases when a VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
This framework allows dom0 to be the RPC target as well.
Thanks to the framework, RPC programs are very simple -- both RPC client and server just use their stdin/stdout to pass data.
The framework does all the inner work to connect these processes to each other via `qrexec-daemon` and `qrexec-agent`.
Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to a normal domain, all one needs is to pass `@dispvm` as the remote domain name.
The framework does all the inner work to connect the processes to eachother via `qrexec-daemon` and `qrexec-agent`.
Disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to an AppVM or StandaloneVM: all one needs is to pass `@dispvm` as the remote domain name.
## Qubes RPC administration
### 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.

50
developer/system/vm-sudo.md Normal file
View File

@ -0,0 +1,50 @@
---
lang: en
layout: doc
permalink: /doc/vm-sudo-implementation/
redirect_from:
- /en/doc/vm-sudo-implementation/
- /doc/VMSudo-implementation/
ref: 341
title: Passwordless root access in qubes
---
The rationale behind passwordless root in qubes is set out [here](/doc/vm-sudo). Implementation is by the qubes-core-agent-passwordless-root package.
This page sets out the configuration changes made, with (not necessary complete) list of mechanisms depending on each of them:
1. sudo (`/etc/sudoers.d/qubes`):
```
Defaults !requiretty
%qubes ALL=(ALL) ROLE=unconfined_r TYPE=unconfined_t NOPASSWD: ALL
(...)
```
- Easy user -> root access (main option for the user).
- `qvm-usb` (not really working, as of R2).
2. PolicyKit (`/etc/polkit-1/rules.d/00-qubes-allow-all.rules`):
```
//allow any action, detailed reasoning in sudoers.d/qubes
polkit.addRule(function(action,subject) { if (subject.isInGroup("qubes")) return polkit.Result.YES; });
```
PAM (`/etc/pam.d/su.qubes` or `/usr/share/pam-configs/su.qubes`)
```
auth sufficient pam_succeed_if.so use_uid user ingroup qubes
```
- NetworkManager configuration from normal user (`nm-applet`).
- Updates installation (`gpk-update-viewer`).
- User can use pkexec just like sudo Note: above is needed mostly because Qubes user GUI session isn't treated by PolicyKit/logind as "local" session because of the way in which X server and session is started.
Perhaps we will address this issue in the future, but this is really low priority.
Patches welcomed anyway.
3. Empty root password:
- Used for access to 'root' account from text console (`qvm-console-dispvm`) - the only way to access the VM when GUI isn't working.
- Can be used for easy 'su -' from user to root.

2
external/building-guides/building-archlinux-template.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md
redirect_to: https://forum.qubes-os.org/t/19052
ref: 116
title: Building Arch Linux template
---

2
external/building-guides/building-non-fedora-template.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/building-non-fedora-template/
- /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md
redirect_to: https://forum.qubes-os.org/t/18972
ref: 117
title: Building non-Fedora template
---

2
external/building-guides/building-whonix-template.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/building-whonix-template/
- /en/doc/building-whonix-template/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-whonix-template.md
redirect_to: https://forum.qubes-os.org/t/18981
ref: 115
title: Building Whonix templates
---

2
external/configuration-guides/change-time-zone.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/change-time-zone/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md
redirect_to: https://forum.qubes-os.org/t/18983
ref: 109
title: Changing your time zone
---

2
external/configuration-guides/disk-trim.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/disk-trim/
- /doc/DiskTRIM/
- /wiki/DiskTRIM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/disk-trim.md
redirect_to: https://forum.qubes-os.org/t/19054
ref: 104
title: Disk TRIM
---

2
external/configuration-guides/external-audio.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/external-audio/
- /doc/ExternalAudio/
- /wiki/ExternalAudio/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md
redirect_to: https://forum.qubes-os.org/t/18984
ref: 100
title: External audio
---

2
external/configuration-guides/fetchmail.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/fetchmail/
- /doc/Fetchmail/
- /wiki/Fetchmail/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/fetchmail.md
redirect_to: https://forum.qubes-os.org/t/18985
ref: 114
title: Fetchmail
---

2
external/configuration-guides/install-nvidia-driver.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/install-nvidia-driver/
- /doc/InstallNvidiaDriver/
- /wiki/InstallNvidiaDriver/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md
redirect_to: https://forum.qubes-os.org/t/18987
ref: 96
title: How to install an Nvidia driver
---

2
external/configuration-guides/multiboot.md vendored
View File

@ -1,7 +1,7 @@
---
lang: en
layout: doc
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
redirect_to: https://forum.qubes-os.org/t/18988
ref: 112
title: Multibooting
---

2
external/configuration-guides/multimedia.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/multimedia/
- /doc/Multimedia/
- /wiki/Multimedia/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md
redirect_to: https://forum.qubes-os.org/t/19055
ref: 105
title: How to make a multimedia template
---

2
external/configuration-guides/mutt.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/mutt/
- /doc/Mutt/
- /wiki/Mutt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md
redirect_to: https://forum.qubes-os.org/t/18989
ref: 106
title: Mutt
---

2
external/configuration-guides/network-bridge-support.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/network-bridge-support/
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md
redirect_to: https://forum.qubes-os.org/t/18990
ref: 113
title: Network bridge support
---

2
external/configuration-guides/network-printer.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/network-printer/
- /doc/NetworkPrinter/
- /wiki/NetworkPrinter/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md
redirect_to: https://forum.qubes-os.org/t/19056
ref: 108
title: Network printer
---

2
external/configuration-guides/postfix.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/postfix/
- /doc/Postfix/
- /wiki/Postfix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/postfix.md
redirect_to: https://forum.qubes-os.org/t/18991
ref: 107
title: Postfix
---

2
external/configuration-guides/rxvt.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/rxvt/
- /doc/Rxvt/
- /wiki/Rxvt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/rxvt.md
redirect_to: https://forum.qubes-os.org/t/18992
ref: 103
title: Rxvt
---

9
external/configuration-guides/tips-and-tricks.md vendored
View File

@ -1,9 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /doc/tips-and-tricks/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/tips-and-tricks.md
ref: 110
title: Tips and tricks
---

2
external/configuration-guides/vpn.md vendored
View File

@ -7,7 +7,7 @@ redirect_from:
- /en/doc/vpn/
- /doc/VPN/
- /wiki/VPN/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md
redirect_to: https://forum.qubes-os.org/t/19061
ref: 102
title: VPN
---

2
external/configuration-guides/w3m.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/mutt/
- /doc/W3m/
- /wiki/W3m/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/w3m.md
redirect_to: https://forum.qubes-os.org/t/18993
ref: 101
title: Reducing the fingerprint of the text-based web browser w3m
---

2
external/configuration-guides/zfs.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/zfs/
- /doc/ZFS/
- /wiki/ZFS/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zfs.md
redirect_to: https://forum.qubes-os.org/t/18994
ref: 111
title: ZFS
---

2
external/customization-guides/dark-theme.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/dark-theme/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md
redirect_to: https://forum.qubes-os.org/t/18997
ref: 74
title: Dark theme
---

2
external/customization-guides/fedora-minimal-template-customization.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /en/doc/fedora-minimal-template-customization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md
redirect_to: https://forum.qubes-os.org/t/18999
ref: 76
title: Fedora minimal template customization
---

2
external/customization-guides/language-localization.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/language-localization/
- /doc/LanguageLocalization/
- /wiki/LanguageLocalization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md
redirect_to: https://forum.qubes-os.org/t/19001
ref: 73
title: Language localization
---

2
external/customization-guides/removing-templatevm-packages.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/removing-templatevm-packages/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md
redirect_to: https://forum.qubes-os.org/t/19002
ref: 75
title: Removing template packages
---

2
external/customization-guides/windows-template-customization.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/windows-template-customization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md
redirect_to: https://forum.qubes-os.org/t/19005
ref: 72
title: Windows template customization
---

2
external/os-guides/centos.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/templates/centos/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md
redirect_to: https://forum.qubes-os.org/t/19006
ref: 81
title: CentOS template
---

2
external/os-guides/gentoo.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/templates/gentoo/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md
redirect_to: https://forum.qubes-os.org/t/19007
ref: 221
title: Gentoo template
---

2
external/os-guides/linux-hvm-tips.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/linux-hvm-tips/
- /doc/LinuxHVMTips/
- /wiki/LinuxHVMTips/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md
redirect_to: https://forum.qubes-os.org/t/19008
ref: 82
title: Linux HVM tips
---

2
external/os-guides/netbsd.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/netbsd/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md
redirect_to: https://forum.qubes-os.org/t/19009
ref: 84
title: How to create a NetBSD qube
---

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

@ -1,9 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /doc/pentesting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting.md
ref: 83
title: Penetration testing
---

2
external/os-guides/pentesting/blackarch.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/blackarch/
- /doc/blackarch/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md
redirect_to: https://forum.qubes-os.org/t/19010
ref: 88
title: How to create a BlackArch qube
---

2
external/os-guides/pentesting/kali.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/kali/
- /doc/kali/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md
redirect_to: https://forum.qubes-os.org/t/19071
ref: 87
title: How to create a Kali Linux qube
---

2
external/os-guides/pentesting/ptf.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/ptf/
- /doc/ptf/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md
redirect_to: https://forum.qubes-os.org/t/19011
ref: 89
title: How to create penetration testers framework (PTF) qube
---

2
external/os-guides/ubuntu.md vendored
View File

@ -7,7 +7,7 @@ redirect_from:
- /en/doc/templates/ubuntu/
- /doc/Templates/Ubuntu/
- /wiki/Templates/Ubuntu/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md
redirect_to: https://qubes.3isec.org
ref: 80
title: Ubuntu template
---

2
external/privacy-guides/anonymizing-your-mac-address.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/anonymizing-your-mac-address/
- /doc/randomizing-your-mac-address/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/anonymizing-your-mac-address.md
redirect_to: https://forum.qubes-os.org/t/19072
ref: 67
title: Anonymizing your MAC address
---

2
external/privacy-guides/signal.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/signal/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md
redirect_to: https://forum.qubes-os.org/t/19073
ref: 70
title: Signal
---

2
external/privacy-guides/tails.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/tails/
- /doc/running-tails/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md
redirect_to: https://forum.qubes-os.org/t/19012
ref: 71
title: Running Tails in qubes
---

2
external/privacy-guides/torvm.md vendored
View File

@ -8,7 +8,7 @@ redirect_from:
- /doc/TorVM/
- /doc/UserDoc/TorVM/
- /wiki/UserDoc/TorVM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/torvm.md
redirect_to: https://forum.qubes-os.org/t/19013
ref: 68
title: TorVM
---

2
external/privacy-guides/whonix.md vendored
View File

@ -16,7 +16,7 @@ redirect_from:
- /doc/privacy/uninstall-whonix/
- /doc/whonix/update/
- /doc/privacy/updating-whonix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md
redirect_to: https://forum.qubes-os.org/t/19014
ref: 69
title: Whonix for privacy & anonymity
---

2
external/security-guides/multifactor-authentication.md vendored
View File

@ -5,7 +5,7 @@ redirect_from:
- /doc/multifactor-authentication/
- /en/doc/multifactor-authentication/
- /doc/Multi-factorAuthentication/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md
redirect_to: https://forum.qubes-os.org/t/19016
ref: 78
title: Multifactor authentication
---

2
external/security-guides/security-guidelines.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/security-guidelines/
- /doc/SecurityGuidelines/
- /wiki/SecurityGuidelines/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md
redirect_to: https://forum.qubes-os.org/t/19075
ref: 79
title: Security guidelines
---

2
external/security-guides/split-bitcoin.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/split-bitcoin/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md
redirect_to: https://forum.qubes-os.org/t/19017
ref: 77
title: Split Bitcoin
---

2
external/troubleshooting/application-troubleshooting.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/application-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19019
ref: 236
title: Application troubleshooting
---

2
external/troubleshooting/intel-igfx-troubleshooting.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/intel-igfx-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19081
ref: 90
title: Intel integrated graphics troubleshooting
---

2
external/troubleshooting/macbook-troubleshooting.md vendored
View File

@ -1,7 +1,7 @@
---
lang: en
layout: doc
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19020
ref: 238
title: Apple MacBook troubleshooting
---

2
external/troubleshooting/nvidia-troubleshooting.md vendored
View File

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/NvidiaTroubleshooting/
- /wiki/NvidiaTroubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19021
ref: 91
title: Nvidia troubleshooting
---

2
external/troubleshooting/sony-vaio-tinkering.md vendored
View File

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/sony-vaio-tinkering/
- /doc/SonyVaioTinkering/
- /wiki/SonyVaioTinkering/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/sony-vaio-tinkering.md
redirect_to: https://forum.qubes-os.org/t/19022
ref: 93
title: Sony Vaio tinkering
---

2
external/troubleshooting/tails-troubleshooting.md vendored
View File

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/tails-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/tails-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19023
ref: 237
title: Tails troubleshooting
---

2
external/troubleshooting/thinkpad-troubleshooting.md vendored
View File

@ -11,7 +11,7 @@ redirect_from:
- /en/doc/lenovo450-tinkering/
- /doc/Lenovo450Tinkering/
- /wiki/Lenovo450Tinkering/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/thinkpad-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19024
ref: 95
title: Lenovo ThinkPad troubleshooting
---

4
introduction/faq.md
View File

@ -459,7 +459,7 @@ You have to restart the NetVM after the template has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it poses a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md).
But if you understand the risk and accept it, read [documentation on multibooting](https://forum.qubes-os.org/t/18988).
It begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running?
@ -806,4 +806,4 @@ If you need to support not-fully-updated systems, check for the existence of `/u
Yes, Qubes natively supports automation via [Salt (SaltStack)](/doc/salt/).
There is also the unofficial [ansible-qubes toolkit](https://github.com/Rudd-O/ansible-qubes).
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://forum.qubes-os.org/t/19075#dom0-precautions).)

4
introduction/getting-started.md
View File

@ -80,7 +80,7 @@ random web surfing in a different qube, you wouldn't want to accidentally enter
your banking password in the latter! The colored frames help to avoid such
mistakes.
[![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png)
[![snapshot_41.png](/attachment/doc/r4.1-snapshot_40.png)](/attachment/doc/r4.1-snapshot_40.png)
Most Qubes users associate red with what's untrusted and dangerous (like a red
light: stop! danger!), green with what's safe and trusted, and yellow and
@ -142,7 +142,7 @@ To see all of your qubes at the same time, you can use the **Qube Manager** (go
to the App Menu → Qubes Tools → Qube Manager), which displays the states of
all the qubes in your system, even the ones that aren't running.
[![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png)
[![r4.1-qubes-manager.png](/attachment/doc/r4.1-qubes-manager.png)](/attachment/doc/r4.1-qubes-manager.png)
#### Command-line interface

4
introduction/intro.md
View File

@ -136,9 +136,9 @@ title: Introduction
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>U2F proxy</h3>
<h3>CTAP proxy</h3>
<p>
Operate <a href="/doc/u2f-proxy/">Qubes U2F proxy</a> to use your
Operate <a href="/doc/ctap-proxy/">Qubes CTAP proxy</a> to use your
two-factor authentication devices without exposing your web browser to the
full USB stack.
</p>

76
introduction/issue-tracking.md
View File

@ -51,13 +51,13 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure
Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs.
## Labels, milestones, and projects
## Labels and projects
Labels, milestones, and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
Labels and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
### Labels
When an issue is first created, certain labels may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify [labels](https://github.com/QubesOS/qubes-issues/labels) and [milestones](https://github.com/QubesOS/qubes-issues/milestones). Many labels and milestones have descriptions on them that can be viewed either in their respective lists or by hovering over them. Let's go over some of the most important ones.
When an issue is first created, certain [labels](https://github.com/QubesOS/qubes-issues/labels) may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones.
#### Type
@ -75,29 +75,45 @@ There are several issue **priority** levels ranging from `P: minor` to `P: block
#### Component
There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?page=2&q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
#### Affected release
A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases.
### Milestones
The issue tracker has several [milestones](https://github.com/QubesOS/qubes-issues/milestones). Individual issues can be assigned to milestones. The issue tracker does not allow an issue to be assigned to more than one milestone. If an issue is already assigned to a milestone, assigning it to a different one will *replace* the existing milestone assignment. Each milestone has a progress indicator showing how close that milestone is to completion.
Most milestones correspond to specific Qubes OS releases. The Qubes developers decide which issues will be assigned to specific milestones. The general idea is that each milestone's progress indicator should provide a rough idea of how much progress has been made on that milestone and how much work remains until the milestone is complete. Most issues will not be assigned to any milestone at all until a Qubes developer manually assigns it to one. While anyone is free to open an issue, this does not create an obligation on the Qubes developers to act on that issue. Every open issue should be understood to be merely "under consideration" unless or until a Qubes developer decides to assign it to a milestone. Issues that are assigned to a milestone are issues that either the Qubes developers or another contributor plans to complete *for* that milestone. The Qubes developers reserve the right to modify or remove milestones at any time at their discretion.
### 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.
According to GitHub, a [project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) is "an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively." The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). Github projects allows more detailed issue states, and also attaching more metadata to issues. They also allow more focused view.
There is a special project in Qubes OS project: the [Current team tasks project](https://github.com/orgs/QubesOS/projects/19/views/1) which represents current work of the core team. Issues in this project's **backlog** section are not yet ready for work - they might be waiting for clarifications, blockers, decisions on priorities etc. Issues that are **ready** can be picked up by any team member. There should not be too many issues in **ready** column to decrease confusion and decision paralysis - good number is around 20. The **in review** state means that the developer is finished with the work (the completion state has been reached) - if something has to be postponed or abandoned, a justification should be posted in issue discussion.
### Meta-issues
A meta-issue is an issue that serves to collect and organize a group of other issues. We use meta-issues when we need a way to track work on specific features. We cannot use [projects](#projects) for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects.
Meta-issues must abide by the following rules:
- Only members of the core team may create meta-issues (or convert existing issues into meta-issues).
Rationale: The purpose of meta-issues is to track the development of certain features that fit into the overall goals of the Qubes OS Project, which requires making informed project-management decisions with the approval of the project lead.
- Meta-issues must be [locked](https://docs.github.com/en/communities/moderating-comments-and-conversations/locking-conversations).
Rationale: One of the historical problems we've experienced with meta-issues (and one of the reasons they were discouraged for a long time) is that each meta-issue tends to turn into a discussion thread that becomes hopelessly long to the point where the person who is supposed to work on it has no idea what is supposed to be done or where to start, and it eventually just gets closed. Locking is intended to prevent that from happening again.
- Meta-issues must have informative descriptions, not just lists of issues. In particular, each meta-issue should explain its goal, what is in scope, and what the relevant categories and priorities are.
- Meta-issues must have clear, concrete, and actionable criteria for when they will be closed. Meta-issues should never be "open-ended" or expected to stay open indefinitely. If this ever becomes unclear, the meta-issue should be closed until it becomes clear.
## Search tips
[Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
- [Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3A%22T%3A+bug%22+sort%3Aupdated-desc).
[Search using labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
- [Search with labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
You can also try searching by [milestone](https://github.com/QubesOS/qubes-issues/milestones) and by [project](https://github.com/QubesOS/qubes-issues/projects).
- Search by closure reason: [`reason:completed`](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
@ -109,7 +125,7 @@ This guideline is important for keeping issues focused on *actionable informatio
### 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 places 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
@ -168,11 +184,17 @@ In the case of bugs, the package containing the change will move to the appropri
### 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)
@ -186,8 +208,26 @@ We close issues at step 3. Then, as updates are released, the issue automaticall
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 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.
## Workflow and what do issue states mean
There are some rules we use when assigning issues and tagging them.
### Assigning issues
To avoid a situation where an issue is "dead" - assigned to someone who is not actively working on it - and to help the team organize their work, an issue should be assigned to a person who currently works on it, or will start working on it in a very near future (about a week or two). One person can have several issues assigned at the same time (for example they may be working on one another issue while waiting for review), but if an issue is no longer actively being worked on (for example when it's blocked by something else), it should be unassigned. At that point, if there is some partial work already done, there should be a comment about that, including link to the code (some WIP commit in some branch?) if applicable.
Issues should not be assigned as a todo-list several months in the future, or assigned to someone without their explicit confirmation that they are currently working on that issue or will start doing it shortly.
### Working on an issue
Every issue should involve a clear statement of success: when is the issue finished? It might not be clear to the person making the issue, especially if it's an enhancement request, but before work starts, the person working on the issue should make sure that it includes clear completion criteria in the description (via editing the description, if necessary). The completion criteria would ideally be a checklist, and consist of a list of pull requests/features, each preferably no more than two weeks of work. It's also important to remember tests and documentation should also be part of the issue, if applicable.
An issue should also have a rough estimate how much time it needs, if it's more than one-two days. Of course this might be updated later, if an issue turns out to be more (or maybe less) complicated than it has initially seemed.
When an issue is done (that is, the completion checklist has been completed), the issue should be moved to **ready** column in the *Current team tasks* project.

19
introduction/support.md
View File

@ -39,7 +39,7 @@ No worries! Here's how we recommend proceeding:
3. Try [searching the issue tracker](/doc/issue-tracking/#search-tips). There
may already be an open **or closed** issue about your problem. The issue
tracker is constantly being updated with known bugs and may contain
workarounds for problems you're experiencing. If there any pinned issues at
workarounds for problems you're experiencing. If there are any pinned issues at
the top, make sure to check them first!
4. Try [searching the Qubes Forum](https://forum.qubes-os.org/). There may
@ -176,7 +176,7 @@ information in your message. A great way to provide your hardware details is by
[generating and submitting a Hardware Compatibility List (HCL)
report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then
linking to it in your message. [Ask questions the smart
way.](http://www.catb.org/esr/faqs/smart-questions.html)
way.](https://www.catb.org/esr/faqs/smart-questions.html)
### Be patient
@ -226,7 +226,7 @@ The moderation team aims to enforce our [Code of Conduct](/code-of-conduct/).
Beyond this, users should not expect any specific action from the moderation
team. Specifically, users should not request that posts or messages be deleted
or edited by a moderator. Users are reminded that, in most venues, anything
posted will be sent out as an email to other others, and these emails cannot be
posted will be sent out as an email to others, and these emails cannot be
deleted from others' inboxes.
### Specific mailing list rules and notes
@ -309,7 +309,7 @@ account is in no way required, expected, or encouraged. Many discussants
[mailing lists](https://en.wikipedia.org/wiki/Electronic_mailing_list),
interacting with them solely through plain text email with
[MUAs](https://en.wikipedia.org/wiki/Email_client) like
[Thunderbird](https://www.thunderbird.net/) and [Mutt](http://www.mutt.org/).
[Thunderbird](https://www.thunderbird.net/) and [Mutt](https://www.mutt.org/).
The Google Groups service is just free infrastructure, and we [distrust the
infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure). This
is why, for example, we encourage discussants to use [Split
@ -403,7 +403,7 @@ interface](https://groups.google.com/group/qubes-devel).
This list is for non-technical discussion and coordination around the Qubes OS
project.
Examples of topics or question suitable for this list include:
Examples of topics or questions suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
@ -430,7 +430,7 @@ interface](https://groups.google.com/group/qubes-project).
This list is for discussion around the localization and translation of Qubes
OS, its documentation, and the website.
Examples of topics or question suitable for this list include:
Examples of topics or questions suitable for this list include:
* Questions about or issues with [Transifex](https://www.transifex.com/), the
translation platform we use
@ -514,8 +514,11 @@ news.
## Chat
If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix
bridge: `#qubes:libera.chat`).
If you'd like to chat, join us on
- the `#qubes` channel on `irc.libera.chat` or
- the `#qubes:invisiblethingslab.com` matrix channel.
these two should be linked/bridged, but for technical reasons currently are not.
## Unofficial venues

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

@ -171,26 +171,68 @@ 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:
For the purpose of convincing yourself that you know the authentic QMSK
fingerprint, 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 should not be
considered the same. 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 should not be considered the same.
However, for the purpose of *searching for*, *looking up*, or *entering* keys,
spaces and capitalization can matter, depending on the software or tool you're
using. You may need to try different variations (e.g., with and without
spaces). You may also sometimes see (or need to enter) 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. Again,
for the purpose of convincing yourself that you know the authentic QMSK
fingerprint, 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 considered the same. The `0x` prefix only matters if the
software or tool you're using cares about it.
The general idea of "comparing fingerprints" is to go out into the world
(whether digitally, physically, or both) and find other 40-character strings
purporting to be the QMSK fingerprint, then compare them to your own purported
QMSK fingerprint to ensure that the sequence of alphanumeric characters is
exactly the same (again, regardless of spaces or capitalization). If any of the
characters do not match or are not in the same order, then at least one of the
fingerprints is a forgery. Here are some ideas to get you started:
- Check the fingerprint on various websites (e.g., [mailing
lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ),
@ -204,10 +246,10 @@ Here are some ideas for how to do that:
talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a
[T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or
in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes
Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat
rooms.
- Download old Qubes ISOs from different sources and check the included Qubes
Master Signing Key.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
@ -215,11 +257,11 @@ Here are some ideas for how to do that:
confirm the fingerprint.
- Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough
different ways that you feel confident that you know the genuine fingerprint,
keep it in a safe place. Every time you need to check whether a key claiming to
be the QMSK is authentic, compare that key's fingerprint to your trusted copy
and confirm they match.
Once you've observed enough matching fingerprints from enough independent
sources in enough different ways that you feel confident that you have the
genuine fingerprint, keep it in a safe place. Every time you need to check
whether a key claiming to be the QMSK is authentic, compare that key's
fingerprint to your trusted copy and confirm they match.
Now that you've imported the authentic QMSK, set its trust level to "ultimate"
so that it can be used to automatically verify all the keys signed by the QMSK

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

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

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

@ -84,7 +84,3 @@ The safest way to remove (most of) KDE is:
sudo dnf remove kdelibs plasma-workspace
~~~
Mailing List Threads
--------------------
* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)

12
user/advanced-topics/managing-vm-kernels.md
View File

@ -224,7 +224,7 @@ Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` director
* `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
* `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present.
All the files besides `vmlinuz` and `initramfs` are optional in Qubes R4.0 or newer.
## Using kernel installed in the VM
@ -275,9 +275,11 @@ grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your
Then shutdown the VM.
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
**Notes:**
* You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
* If you require `PV` mode, install `grub2-xen-pvh` in dom0 and change the template's kernel to `pvgrub2-pvh`.
* Booting to a kernel inside the template is not supported under `PVH`.
### Installing kernel in Debian VM
@ -311,7 +313,7 @@ Go to dom0 -> Qubes VM Manger -> right click on the VM -> Qube settings -> Advan
Depends on `Virtualization` mode setting:
* `Virtualization` mode `PV`: Possible, however use of `Virtualization` mode `PV` mode is discouraged for security purposes.
* If you require `Virtualization` mode `PV` mode, install `grub2-xen` in dom0. This can be done by running command `sudo qubes-dom0-update grub2-xen` in dom0.
* If you require `Virtualization` mode `PV` mode, install `grub2-xen-pvh` in dom0. This can be done by running command `sudo qubes-dom0-update pvgrub2-pvh in dom0.
* `Virtualization` mode `PVH`: Possible.
* `Virtualization` mode `HVM`: Possible.

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

@ -31,7 +31,7 @@ its clients (called *minions*).
In typical situations, it is intended that the administrator interacts only
with the master and keeps the configurations there.
In Qubes, we don't have a master.
Instead we have one minion which resides in `dom0` and manages domains from
Instead we have one minion which resides in `dom0` and manages qubes from
there.
This setup is also supported by Salt.
@ -61,8 +61,26 @@ enforcing the state in a particular area.
It exposes some *imperative* functions for the administrator.
For example, there is a `system` module that has a `system.halt` function that,
when issued, will immediately halt a domain.
There is another function called `state.highstate` which will synchronize the
state of the system with the administrator's configuration/desires.
In salt, there are different levels of functionality.
The lowest level is a single state function, called like
this `state.single pkg.installed name=firefox-esr`
When the system compiles data from sls formulas, it generates *chunks* -
low chunks are at the bottom of the compiler . You can call them with
`state.low`
Next up is the *lowstate* level - this is the list of all low chunks in
order. - To see them you have `state.show_lowstate`, and use `state.lowstate` to apply them.
At the top level is *highstate* - this is an interpretation of **all** the data represented in YAML
in sls files. You can view it with `state.show_highstate`.
When you want to apply a configuration, you can use `qubesctl state.highstate.`
This will apply all the states you have included in highstate.
There is another function, `state.apply`; `state.apply` has two uses.
When used on its own, it will apply *highstate* - all the configuration that has been enabled.
It can also be used to apply a specific state, like this: `state.apply browser` - this will apply the state specified in `browser.sls`.
For simplicity we will use `state.apply` through this page, when we want to apply all configured states.
### Configuration
@ -126,11 +144,11 @@ The official documentation has more details on the
When configuring a system you will write one or more state files (`*.sls`) and
put (or symlink) them into the main Salt directory `/srv/salt/`.
Each state file contains multiple states and should describe some unit of
configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
configuration (e.g., a state file `mail.sls` could setup a qube for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
After you have several state files, you need something to assign them to a qube.
This is done by `*.top` files ([official documentation](https://docs.saltproject.io/en/latest/ref/states/top.html)).
Their structure looks like this:
@ -142,8 +160,8 @@ environment:
```
In most cases, the environment will be called `base`.
The `target_matching_clause` will be used to select your minions (VMs).
It can be either the name of a VM or a regular expression.
The `target_matching_clause` will be used to select your minions (Templates or qubes).
It can be either the name of a qube or a regular expression.
If you are using a regular expressions, you need to give Salt a hint you are
doing so:
@ -184,7 +202,7 @@ $ qubesctl top.disable my-new-vm
To apply the states to dom0 and all VMs:
```
$ qubesctl --all state.highstate
$ qubesctl --all state.apply
```
(More information on the `qubesctl` command further down.)
@ -212,17 +230,17 @@ However, the states that are part of the standard Qubes distribution are mostly
templates and the configuration is done in pillars from formulas.
The formulas are in `/srv/formulas`, including stock formulas for domains in
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by firstboot.
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by first boot.
Because we use some code that is not found in older versions of Salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`.
It accepts all the same arguments of the vanilla tool.
## Configuring a VM's System from Dom0
## Configuring a qube's System from Dom0
Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
Salt can be used to configure qubes from dom0.
Simply set the qube name as the target minion name in the top file.
You can also use the `qubes` pillar module to select qubes with a particular
property (see below).
If you do so, then you need to pass additional arguments to the `qubesctl` tool:
@ -232,7 +250,7 @@ usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0]
...
positional arguments:
command Salt command to execute (e.g., state.highstate)
command Salt command to execute (e.g., state.apply)
optional arguments:
-h, --help show this help message and exit
@ -246,32 +264,32 @@ optional arguments:
--all Target all non-disposables (templates and app qubes)
```
To apply a state to all templates, call `qubesctl --templates state.highstate`.
To apply a state to all templates, call `qubesctl --templates state.apply`.
The actual configuration is applied using `salt-ssh` (running over `qrexec`
instead of `ssh`).
Which means you don't need to install anything special in a VM you want to
Which means you don't need to install anything special in a qube you want to
manage.
Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
Additionally, for each target qube, `salt-ssh` is started from a temporary qube.
This way dom0 doesn't directly interact with potentially malicious target qubes;
and in the case of a compromised Salt qube, because they are temporary, the
compromise cannot spread from one qube to another.
Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the disposable
1. Added the `management_dispvm` qube property, which specifies the disposable
Template that should be used for management, such as Salt
configuration. App qubes inherit this property from their
parent templates. If the value is not set explicitly, the default
is taken from the global `management_dispvm` property. The
VM-specific property is set with the `qvm-prefs` command, while the
qube-specific property is set with the `qvm-prefs` command, while the
global property is set with the `qubes-prefs` command.
2. Created the `default-mgmt-dvm` disposable template, which is hidden from
the menu (to avoid accidental use), has networking disabled, and has
a black label (the same as templates). This VM is set as the global
a black label (the same as templates). This qube is set as the global
`management_dispvm`. Keep in mind that this disposable template has full control
over the VMs it's used to manage.
over the qubes it's used to manage.
## Writing Your Own Configurations
@ -289,17 +307,17 @@ my new and shiny VM:
- proxy
```
It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
It uses the Qubes-specific `qvm.present` state, which ensures that the qube is
present (if not, it creates it).
- The `name` flag informs Salt that the domain should be named `salt-test` (not
- The `name` flag informs Salt that the qube should be named `salt-test` (not
`my new and shiny VM`).
- The `template` flag informs Salt which template should be used for the domain.
- The `label` flag informs Salt what color the domain should be.
- The `mem` flag informs Salt how much RAM should be allocated to the domain.
- The `template` flag informs Salt which template should be used for the qube.
- The `label` flag informs Salt what color the qube should be.
- The `mem` flag informs Salt how much RAM should be allocated to the qube.
- The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
domain
- The `proxy` flag informs Salt that the domain should be a ProxyVM.
qube
- The `proxy` flag informs Salt that the qube should be a ProxyVM.
As you will notice, the options are the same (or very similar) to those used in
`qvm-prefs`.
@ -325,10 +343,10 @@ $ qubesctl top.enable my-new-vm
To apply the state:
```
$ qubesctl state.highstate
$ qubesctl state.apply
```
### Example of Configuring a VM's System from Dom0
### Example of Configuring Templates from Dom0
Lets make sure that the `mc` package is installed in all templates.
Similar to the previous example, you need to create a state file
@ -357,18 +375,18 @@ $ qubesctl top.enable mc-everywhere
And apply the configuration:
```
$ qubesctl --all state.highstate
$ qubesctl --all state.apply
```
## All Qubes-specific States
### `qvm.present`
As in the example above, it creates a domain and sets its properties.
As in the example above, it creates a qube and sets its properties.
### `qvm.prefs`
You can set properties of an existing domain:
You can set properties of an existing qube:
```
my preferences:
@ -377,13 +395,13 @@ my preferences:
- netvm: sys-firewall
```
***Note*** The `name:` option will not change the name of a domain, it will only
be used to match a domain to apply the configurations to it.
***Note*** The `name:` option will not change the name of a qube, it will only
be used to match a qube to apply the configurations to it.
### `qvm.service`
```
services in my domain:
services in my qube:
qvm.service:
- name: salt-test3
- enable:
@ -400,18 +418,18 @@ This enables, disables, or sets to default, services as in `qvm-service`.
### `qvm.running`
Ensures the specified domain is running:
Ensures the specified qube is running:
```
domain is running:
qube is running:
qvm.running:
- name: salt-test4
```
## Virtual Machine Formulae
You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details.
You can use these formulae to download, install, and configure qubes in Qubes.
These formulae use pillar data to define default qube names and configuration details.
The default settings can be overridden in the pillar data located in:
```
@ -419,7 +437,7 @@ The default settings can be overridden in the pillar data located in:
```
In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (template, `sys-firewall`, and `sys-net`).
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` qube (if it does not already exist) with all its dependencies (template, `sys-firewall`, and `sys-net`).
### Available states
@ -429,16 +447,16 @@ System NetVM
#### `qvm.sys-usb`
System USB VM
System USB qube
#### `qvm.sys-net-as-usbvm`
System USB VM bundled into NetVM. Do not enable together with `qvm.sys-usb`.
System USB qube bundled into NetVM. Do not enable together with `qvm.sys-usb`.
#### `qvm.usb-keyboard`
Enable USB keyboard together with USB VM, including for early system boot (for LUKS passhprase).
This state implicitly creates a USB VM (`qvm.sys-usb` state), if not already done.
Enable USB keyboard together with USB qube, including for early system boot (for LUKS passhprase).
This state implicitly creates a USB qube (`qvm.sys-usb` state), if not already done.
#### `qvm.sys-firewall`
@ -525,7 +543,7 @@ Useful options:
- `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
- `--targets=vm1,vm2,...` --- Limit to specific qubes, instead of all of them.
(Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL.
@ -539,31 +557,31 @@ Additional pillar data is available to ease targeting configurations (for exampl
### `qubes:type`
VM type. Possible values:
qube type. Possible values:
- `admin` - Administration domain (`dom0`)
- `admin` - Administration qube (`dom0`)
- `template` - template
- `standalone` - Standalone VM
- `standalone` - Standalone qube
- `app` - Template based app qube
### `qubes:template`
Template name on which a given VM is based (if any).
Template name on which a given qube is based (if any).
### `qubes:netvm`
VM which provides network to the given VM
qube which provides network to the given qube
## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
The output for each qube is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
If the log does not contain useful information:
1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
2. When your VM is being started (yellow) press Ctrl-z on qubesctl.
3. Open terminal in disp-mgmt-VM_NAME.
1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.apply`
2. When your qube is being started (yellow) press Ctrl-z on qubesctl.
3. Open terminal in disp-mgmt-qube_NAME.
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
executed in the management VM.
executed in the management qube.
5. Get the last two lines:
```shell_session
@ -571,7 +589,7 @@ If the log does not contain useful information:
$ salt-ssh "$target_vm" $salt_command
```
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
Adjust $target_vm (VM_NAME) and $salt_command (state.apply).
6. Execute them, fix problems, repeat.
## Known Pitfalls
@ -607,4 +625,4 @@ install template and shutdown updateVM:
- [Top files](https://docs.saltproject.io/en/latest/ref/states/top.html)
- [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)
- [Formulas for default Qubes qubes](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)

15
user/advanced-topics/standalones-and-hvms.md
View File

@ -56,14 +56,21 @@ You can create a standalone in the Qube Manager by selecting the "Type" of
"Standalone qube copied from a template" or "Empty standalone qube (install
your own OS)."
Alternatively, from the dom0 command line:
Alternatively, to create an empty standalone from the dom0 command line:
```
qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm <NEW_STANDALONE_NAME>
```
(Note: Technically, `virt_mode=hvm` is not necessary for every standalone.
However, it makes sense if you want to use a kernel from within the qube.)
Or to create a standalone copied from a template:
```
qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm --template <TEMPLATE_QUBE_NAME> <NEW_STANDALONE_NAME>
```
Notes:
- Technically, `virt_mode=hvm` is not necessary for every standalone.
However, it is needed if you want to use a kernel from within the qube.
- If you want to make software installed in a template available in your standalone, pass in the name of the template using the `--template` option.
## Updating standalones
@ -440,4 +447,4 @@ qemu-img -h | tail -n1
Other documents related to HVMs:
- [Windows VMs](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md)
- [Linux HVM Tips](https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md)
- [Linux HVM Tips](https://forum.qubes-os.org/t/19008)

301
user/downloading-installing-upgrading/installation-guide-4.1.md Normal file
View File

@ -0,0 +1,301 @@
---
lang: en
layout: doc
permalink: /doc/installation-guide-4.1/
redirect_from:
ref: 901
title: Qubes 4.1 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.
## Pre-installation
### Hardware requirements
<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>
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.
<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>
### 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.
<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.
</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.
<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. 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.
</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`:
```
$ 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`).
#### 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.
<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>
[![Rufus menu](/attachment/doc/rufus-menu.png)](/attachment/doc/rufus-menu.png)
[![Rufus DD image mode](/attachment/doc/rufus-dd-image-mode.png)](/attachment/doc/rufus-dd-image-mode.png)
## Installation
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).
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.
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:
[![ThinkPad T430 BIOS menu](/attachment/doc/Thinkpad-t430-bios-main.jpg)](/attachment/doc/Thinkpad-t430-bios-main.jpg)
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'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)
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
* Troubleshooting
Select the option to test this media and install Qubes OS.
<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**.
[![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.
[![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.
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.
### 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.
</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.
[![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!
[![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.
[![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.
Don't forget to select your time and date by clicking on the Time & Date entry.
[![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png)
### Software
[![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:
* **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.
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)).
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.
<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.
</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.
<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.)
</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.
[![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> 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**.
<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.
</div>
[![Select storage passhprase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
When you're ready, press **Begin Installation**.
[![Installation summary ready](/attachment/doc/installation-summary-ready.png)](/attachment/doc/installation-summary-ready.png)
### 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.
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.
## Post-installation
### First boot
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)
Just after this screen, you will be asked to enter your encryption passphrase.
[![Unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)](/attachment/doc/unlock-storage-device-screen.png)
### Initial Setup
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.
[![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.
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.
[![Login screen](/attachment/doc/login-screen.png)](/attachment/doc/login-screen.png)
Congratulations, you are now ready to use Qubes OS!
[![Desktop menu](/attachment/doc/desktop-menu.png)](/attachment/doc/desktop-menu.png)
## Next steps
### 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.
### 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.
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/).
### 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.
### 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).
### 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).
## 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!)
* 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.
* 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.

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

@ -111,19 +111,21 @@ Once you access your computer's BIOS or UEFI menu, you'll want to go to the "boo
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)
[![Boot screen](/attachment/doc/boot-screen-4.2.png)](/attachment/doc/boot-screen-4.2.png)
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 five options:
* Install Qubes OS
* Test this media and install Qubes OS
* Troubleshooting
* Troubleshooting - verbose boot
* Rescue a Qubes SO system
* Install Qubes OS 4.2.1 using kernel-latest
Select the option to test this media and install Qubes OS.
<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>.
<b>Note:</b> If the latest stable release is not compatible with your hardware, you may wish to consider installing using the latest kernel. Be aware that this has not been as well testes as the standard kernel.
</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).
@ -132,7 +134,7 @@ If the boot screen does not appear, there are several options to troubleshoot. F
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)
[![Language selection window](/attachment/doc/welcome-to-qubes-os-installation-screen-4.2.png)](/attachment/doc/welcome-to-qubes-os-installation-screen-4.2.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.
@ -153,7 +155,7 @@ Like Fedora, Qubes OS uses the Anaconda installer. Those that are familiar with
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)
[![Installation summary screen awaiting input ](/attachment/doc/installation-summary-not-ready-4.2.png)](/attachment/doc/installation-summary-not-ready-4.2.png)
### Localization
@ -170,24 +172,6 @@ You can have as many keyboard layout and languages as you want. Post-install, yo
Don't forget to select your time and date by clicking on the Time & Date entry.
[![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png)
### Software
[![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:
* **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.
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)).
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.
@ -206,7 +190,7 @@ Your installation destination can be an internal or external storage drive, such
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)
[![Select storage device screen](/attachment/doc/select-storage-device-4.2.png)](/attachment/doc/select-storage-device-4.2.png)
<div class="alert alert-success" role="alert">
<i class="fa fa-check-circle"></i>
@ -220,21 +204,22 @@ As soon as you press **Done**, the installer will ask you to enter a passphrase
<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)
When you're ready, press **Begin Installation**.
[![Installation summary ready](/attachment/doc/installation-summary-ready.png)](/attachment/doc/installation-summary-ready.png)
[![Select storage passphrase](/attachment/doc/select-storage-passphrase.png)](/attachment/doc/select-storage-passphrase.png)
### 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.
Select "User Creation" to 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.
The new user you create has full administrator privileges and is protected by 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)
[![Account name and password creation window. ](/attachment/doc/account-name-and-password-4.2.png)](/attachment/doc/account-name-and-password-4.2.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.
### Installation
When you have completed all the items marked with the warning icon, press **Begin Installation**.
Installation can take some time.
[![Windows showing installation complete and Reboot button. ](/attachment/doc/installation-complete-4.2.png)](/attachment/doc/installation-complete-4.2.png)
When the installation is complete, press **Reboot System**. Don't forget to remove the installation medium, or else you may end up seeing the installer boot screen again.
## Post-installation
@ -246,31 +231,32 @@ If the installation was successful, you should now see the GRUB menu during the
Just after this screen, you will be asked to enter your encryption passphrase.
[![Unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)](/attachment/doc/unlock-storage-device-screen.png)
[![Screen to enter device decryption password](/attachment/doc/unlock-storage-device-screen-4.2.png)](/attachment/doc/unlock-storage-device-screen-4.2.png)
### Initial Setup
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)
[![Window with link for final configuration ](/attachment/doc/initial-setup-menu-4.2.png)](/attachment/doc/initial-setup-menu-4.2.png)
Click on the item marked with the warning triangle to enter the configuration screen.
[![Initial configuration menu](/attachment/doc/initial-setup-menu-configuration-4.2.png)](/attachment/doc/initial-setup-menu-configuration-4.2.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.
[![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.
* **Templates Configuration:** Here you can decide which [templates](../templates/) you want to have installed, and which will be the default template.
* **Create default system qubes:** These are the core components of the system, required for things like internet access. You can opt to have some created as [disposables](../glossary#disposable)
* **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 a qube to hold 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 Whonix Gateway and Workstation qubes:** If you want to use [Whonix](https://www.whonix.org/wiki/Qubes), 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.
* **Do not configure anything:** This is for very advanced users only. If you select this option, you will have to manually set up everything.
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 your 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 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)
@ -313,3 +299,4 @@ Find out [Getting Started](/doc/getting-started/) with Qubes, check out the othe
* 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.

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

@ -8,38 +8,27 @@ ref: 154
title: Supported releases
---
This page details the level and period of support for releases of operating
systems in the Qubes ecosystem.
This page details the level and period of support for releases of operating systems in the Qubes ecosystem.
## Qubes OS
Qubes OS releases are supported for **six months** after each subsequent major
or minor release (see [Version Scheme](/doc/version-scheme/)). The current
release and past major releases are always available on the
[Downloads](/downloads/) page, while all ISOs, including past minor releases,
are available from our [download mirrors](/downloads/#mirrors).
Qubes OS releases are supported for **six months** after each subsequent major or minor release (see [Version Scheme](/doc/version-scheme/)). The current release and past major releases are always available on the [Downloads](/downloads/) page, while all ISOs, including past minor releases, are available from our [download mirrors](/downloads/#mirrors).
| Qubes OS | Start Date | End Date | Status |
| ----------- | ---------- | ---------- | --------------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported |
| Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported |
| Release 4.1 | 2022-02-04 | TBA | Supported |
| Release 4.2 | TBA | TBA | [In testing](https://github.com/QubesOS/qubes-issues/milestone/26) |
| Release 4.3 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/milestone/28) |
| Qubes OS | Start Date | End Date | Status |
| ----------- | ---------- | ---------- | -------------- |
| Release 1 | 2012-09-03 | 2015-03-26 | Unsupported |
| Release 2 | 2014-09-26 | 2016-04-01 | Unsupported |
| Release 3.0 | 2015-10-01 | 2016-09-09 | Unsupported |
| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported |
| Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported |
| Release 4.1 | 2022-02-04 | 2024-06-18 | Supported |
| Release 4.2 | 2023-12-18 | TBA | Supported |
| Release 4.3 | TBA | TBA | In development |
### Note on patch releases
Please note that patch releases, such as 3.2.1 and 4.0.1, do not designate
separate, new major or minor releases of Qubes OS. Rather, they designate their
respective major or minor releases, such as 3.2 and 4.0, inclusive of all
package updates up to a certain point. For example, installing Release 4.0 and
fully updating it results in the same system as installing Release 4.0.1.
Therefore, patch releases are not displayed as separate rows on any of the
tables on this page.
Please note that patch releases, such as 3.2.1 and 4.0.1, do not designate separate, new major or minor releases of Qubes OS. Rather, they designate their respective major or minor releases, such as 3.2 and 4.0, inclusive of all package updates up to a certain point. For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1. Therefore, patch releases are not displayed as separate rows on any of the tables on this page.
## Dom0
@ -58,56 +47,23 @@ The table below shows the OS used for dom0 in each Qubes OS release.
### Note on dom0 and EOL
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as
Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM),
and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are
[security-critical](/doc/security-critical-code/), and we provide updates for
all of them (when necessary), regardless of the support status of the base
distribution. For this reason, we consider it safe to continue using a given
base distribution in dom0 even after it has reached end-of-life (EOL).
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are [security-critical](/doc/security-critical-code/), and we provide updates for all of them (when necessary), regardless of the support status of the base distribution. For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
## Templates
The following table shows select [template](/doc/templates/) releases that are
currently supported. Currently, only [Fedora](/doc/templates/fedora/) and
[Debian](/doc/templates/debian/) templates are officially supported by the
Qubes OS Project. [Whonix](https://www.whonix.org/wiki/Qubes) templates are
supported by our partner, the [Whonix Project](https://www.whonix.org/). Qubes
support for each template ends when that upstream release reaches end-of-life
(EOL), even if that release is included in the table below. Please see below for
distribution-specific notes.
The following table shows select [template](/doc/templates/) (and [standalone](/doc/standalones-and-hvms/)) releases that are currently supported. Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) templates are officially supported by the Qubes OS Project. [Whonix](https://www.whonix.org/wiki/Qubes) templates are supported by our partner, the [Whonix Project](https://www.whonix.org/). Qubes support for each template ends when that upstream release reaches end-of-life (EOL), even if that release is included in the table below. Please see below for distribution-specific notes.
It is the responsibility of each distribution to clearly notify its users in
advance of its own EOL dates, and it is users' responsibility to heed these
notices by upgrading to supported releases. As a courtesy to Qubes users, we
attempt to pass along any upstream EOL notices we receive for
officially-supported templates, but our ability to do this reliably is
dependent on the upstream distribution's practices. If a distribution provides
a mailing list similar to [qubes-announce](/support/#qubes-announce), which
allows us to receive only very important, infrequent messages, including EOL
announcements, we are much more likely to be able to pass along EOL notices to
Qubes users reliably. Qubes users can always check the EOL status of an
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)).
It is the responsibility of each distribution to clearly notify its users in advance of its own EOL dates, and it is users' responsibility to heed these notices by upgrading to supported releases. As a courtesy to Qubes users, we attempt to pass along upstream EOL notices we receive for select distributions, but our ability to do this reliably is dependent on the upstream distribution's practices. For example, if a distribution provides a mailing list similar to [qubes-announce](/support/#qubes-announce), which allows us to receive only very important, infrequent messages, including EOL announcements, we are much more likely to be able to pass along EOL notices to Qubes users reliably. Qubes users can always check the EOL status of an upstream release on the upstream distribution's website (see [Fedora EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian Releases](https://wiki.debian.org/DebianReleases)).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ------ | ------ |
| Release 4.1 | 37, 38 | 11, 12 | 16 |
| Release 4.2 | 37, 38 | 11, 12 | 17 |
| Qubes OS | Fedora | Debian |
| ----------- | ------ | ------ |
| Release 4.1 | 38, 39 | 11, 12 |
| Release 4.2 | 38, 39 | 12 |
### Note on Debian support
Debian releases have two EOL dates: regular and [long-term support
(LTS)](https://wiki.debian.org/LTS). See [Debian Production
Releases](https://wiki.debian.org/DebianReleases#Production_Releases) for a
chart that illustrates this. Qubes support ends at the *regular* EOL date,
*not* the LTS EOL date, unless a specific exception has been made.
Debian releases have two EOL dates: regular and [long-term support (LTS)](https://wiki.debian.org/LTS). See [Debian Production Releases](https://wiki.debian.org/DebianReleases#Production_Releases) for a chart that illustrates this. Qubes support ends at the *regular* EOL date, *not* the LTS EOL date, unless a specific exception has been made.
### Note on Whonix support
[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. Please see the
[Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts)
for details.
[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. Please see the [Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts) for details.

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

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

26
user/downloading-installing-upgrading/upgrade/4_2.md
View File

@ -33,14 +33,12 @@ in-place:
**Note**: This step is critical to ensure the templates will receive updates once Qubes 4.1 reaches end-of-life (EOL) and was missing in previous clean installation instructions.
4. Create a
[backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your
4. Create a [backup](/doc/how-to-back-up-restore-and-migrate/#creating-a-backup) of your
current installation.
5. [Download](/downloads/) the latest 4.2 release.
6. Follow the [installation guide](/doc/installation-guide/) to install Qubes
4.1.
7. [Restore from your
backup](/doc/how-to-back-up-restore-and-migrate/#restoring-from-a-backup) on
4.2.
7. [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
@ -59,8 +57,8 @@ can install it with the following command in the dom0 terminal:
sudo qubes-dom0-update -y qubes-dist-upgrade
The upgrade consists of five stages --- three before restarting the system ---
labeled "STAGE 1" through "STAGE 3" in the options list below, and two after restarting the system --- labeled as "STAGE 4" and "STAGE 5" below.
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`:
@ -70,15 +68,17 @@ Full list of options can be obtained with `qubes-dist-upgrade --help`:
Options:
--update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM.
--release-upgrade, -r (STAGE 2) Update 'qubes-release' for Qubes R4.1.
--dist-upgrade, -s (STAGE 3) Upgrade to Qubes R4.1 and Fedora 32 repositories.
--template-standalone-upgrade, -l (STAGE 4) Upgrade templates and standalone VMs to R4.1 repository.
--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
--all-pre-reboot Execute stages 1 do 3
--all-post-reboot Execute stages 4 and 5
--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').

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

@ -23,43 +23,55 @@ You may also be interested in the [community-recommended hardware](https://forum
Qubes-certified computers are certified for a [major release](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major release. The developers test all new updates within that major release to ensure that no regressions are introduced.
The current Qubes-certified models are listed below in chronological order of certification.
The current Qubes-certified models are listed below in reverse chronological order of certification.
### Insurgo PrivacyBeast X230
### NitroPC Pro 2
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
[![Photo of the NitroPC Pro 2](/attachment/posts/nitropc-pro.jpg)](https://shop.nitrokey.com/shop/nitropc-pro-2-523)
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) for details.
The [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) is a desktop based on the MSI PRO Z790-P DDR5 motherboard. It is certified for Qubes OS 4.
### NitroPad X230
### Star Labs StarBook
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
[![Photo of the Star Labs StarBook](/attachment/site/starlabs-starbook.png)](https://starlabs.systems/pages/starbook)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X. Read our [announcement](/news/2020/03/04/nitropad-x230-qubes-certification/) for details.
### NitroPad T430
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.X. Read our [announcement](/news/2021/06/01/nitropad-t430-qubes-certification/) for details.
### Dasharo FidelisGuard Z690
[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/03/15/dasharo-fidelisguard-z690-first-qubes-certified-desktop/) for details.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://configurelaptop.eu/nv41-series/)
The [NovaCustom NV41 Series](https://configurelaptop.eu/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X. Read our [announcement](/news/2023/05/03/novacustom-nv41-series-qubes-certified/) for details.
The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is a 14-inch laptop. It is certified for Qubes OS 4.
### 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.
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.
### 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.
### Dasharo FidelisGuard Z690
[![Photo of the Dasharo FidelisGuard Z690](/attachment/site/dasharo-fidelisguard-z690.jpg)](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a desktop based on the MSI PRO Z690-A DDR4 motherboard. It is certified for Qubes OS 4.
### NitroPad T430
[![Photo of the NitroPad T430](/attachment/site/nitropad-t430.jpg)](https://shop.nitrokey.com/shop/product/nitropad-t430-119)
The [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) is a laptop based on the ThinkPad T430. It is certified for Qubes OS 4.
### NitroPad X230
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.
### Insurgo PrivacyBeast X230
[![Photo of the Insurgo PrivacyBeast X230](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.
## Become hardware certified

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

@ -99,7 +99,7 @@ the other. Alice's setup looks like this:
- **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)
[Mutt](https://forum.qubes-os.org/t/18989)
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
@ -199,7 +199,7 @@ for work, which contains:
communication.
- **Two qubes for
[Signal](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md).**
[Signal](https://forum.qubes-os.org/t/19073).**
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
@ -217,7 +217,7 @@ for work, which contains:
the side benefit of helping to keep things organized.
- **A [VPN
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md)
qube](https://forum.qubes-os.org/t/19061)
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
@ -391,7 +391,7 @@ Carol has added the following to her Qubes setup:
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)
Qubes](https://forum.qubes-os.org/t/19017)
and is interested in exploring that further.
- **Whonix qubes.** Carol read somewhere that Bitcoin nodes should be run over

2
user/how-to-guides/how-to-use-optical-discs.md
View File

@ -17,7 +17,7 @@ Currently, the only options for reading and recording optical discs (e.g., CDs,
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to a VM.
3. Use a SATA optical drive attached to dom0.
(**Caution:** This option is [potentially dangerous](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
(**Caution:** This option is [potentially dangerous](https://forum.qubes-os.org/t/19075#dom0-precautions).)
To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/how-to-use-usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to.
Typically this would be `sr0`.

2
user/how-to-guides/how-to-use-usb-devices.md
View File

@ -25,7 +25,7 @@ Examples of valid cases for USB-passthrough:
- [external audio devices](/doc/external-audio/)
- [optical drives](/doc/recording-optical-discs/) for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/).
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/ctap-proxy/).
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
## Attaching And Detaching a USB Device

19
user/reference/glossary.md
View File

@ -128,10 +128,22 @@ 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.
## policies
In Qubes OS, "policies" govern interactions between qubes, powered by [Qubes' qrexec system](https://www.qubes-os.org/doc/qrexec/).
A single policy is a rule applied to a qube or set of qubes, that governs how and when information or assets may be shared with other qubes.
An example is the rules governing how files can be copied between qubes.
Policy rules are grouped together in files under `/etc/qubes/policy.d`
Policies are an important part of what makes Qubes OS special.
## qube
A secure compartment in Qubes OS. Currently, qubes are implemented as Xen
@ -145,8 +157,7 @@ still be called "qubes."
* 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). You may wish to rephrase
sentences in order to avoid this ambiguity.
plurality of qubes or [Qubes OS](#qubes-os).
* 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
@ -210,5 +221,5 @@ See [Templates](/doc/templates/).
## VM
An abbreviation for "virtual machine." A software implementation of a machine
(for example, a computer) that executes programs like a physical machine.
An abbreviation for "virtual machine." A software implementation of a computer
that provides the functionality of a physical machine.

4
user/security-in-qubes/anti-evil-maid.md
View File

@ -39,7 +39,7 @@ For more information, see the [qubes-antievilmaid](https://github.com/QubesOS/qu
Security Considerations
-----------------------
[Qubes security guidelines](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md) dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised.
[Qubes security guidelines](https://forum.qubes-os.org/t/19075) dictate that USB devices should never be attached directly to dom0, since this can result in the entire system being compromised.
However, in its default configuration, installing and using AEM requires attaching a USB drive (i.e., [mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class)) directly to dom0.
(The other option is to install AEM to an internal disk.
However, this carries significant security implications, as explained [here](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html).) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand.
@ -50,7 +50,7 @@ Therefore, it is up to each individual Qubes user to evaluate the relative risk
For example, a user who frequently travels with a Qubes laptop holding sensitive data may be at a much higher risk of Evil Maid attacks than a home user with a stationary Qubes desktop.
If the frequent traveler judges her risk of an Evil Maid attack to be higher than the risk of a malicious USB device, she might reasonably opt to install and use AEM.
On the other hand, the home user might deem the probability of an Evil Maid attack occurring in her own home to be so low that there is a higher probability that any USB drive she purchases is already compromised, in which case she might reasonably opt never to attach any USB devices directly to dom0.
(In either case, users can--and should--secure dom0 against further USB-related attacks through the use of a [USB VM](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#creating-and-using-a-usbvm).)
(In either case, users can--and should--secure dom0 against further USB-related attacks through the use of a [USB VM](https://forum.qubes-os.org/t/19075#creating-and-using-a-usbvm).)
For more information, please see [this discussion thread](https://groups.google.com/d/msg/qubes-devel/EBc4to5IBdg/n1hfsHSfbqsJ).

144
user/security-in-qubes/ctap-proxy.md Normal file
View File

@ -0,0 +1,144 @@
---
lang: en
layout: doc
permalink: /doc/ctap-proxy/
redirect_from: /doc/u2f-proxy/
ref: 167
title: CTAP proxy
---
The [Qubes CTAP Proxy](https://github.com/QubesOS/qubes-app-u2f) is a secure proxy intended to make use of CTAP two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies](/doc/usb/) implemented in Qubes.
## What is CTAP, U2F, FIDO2?
CTAP, U2F, and FIDO2 are all related to authentication protocols and standards developed by the FIDO Alliance. CTAP has two versions: CTAP1 and CTAP2:
1. [CTAP1/U2F](https://en.wikipedia.org/wiki/Universal_2nd_Factor) (Universal 2nd Factor): U2F is an earlier protocol developed by the FIDO Alliance as part of the FIDO U2F standard. It provides a strong second-factor authentication method using dedicated hardware security keys. U2F allows users to authenticate to online services by simply plugging in a U2F-compliant security key and pressing a button, providing a higher level of security compared to traditional passwords.
2. [CTAP2](https://en.wikipedia.org/wiki/Client_to_Authenticator_Protocol) (Client to Authenticator Protocol): CTAP2 is a protocol within the FIDO2 framework that enables communication between a client device (e.g., a computer or smartphone) and an authenticator (e.g., a hardware device). CTAP allows for secure and convenient authentication using public key cryptography and strong authentication factors.
3. [FIDO2](https://en.wikipedia.org/wiki/FIDO_Alliance): FIDO2 is a set of standards and protocols developed by the FIDO Alliance for passwordless and strong authentication. It combines two main components: CTAP (Client to Authenticator Protocol) and WebAuthn (Web Authentication API). FIDO2 enables users to authenticate to online services using various authentication methods, such as biometrics, PINs, or hardware tokens, instead of relying on passwords.
The aim of these protocols is to introduce additional control which provides [good protection](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/) in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
While passphrase compromise may not be obvious to the user, a physical device that cannot be duplicated must be stolen to be used outside the owner's control.
Nonetheless, it is important to note at the outset that CTAP cannot guarantee security when the host system is compromised (e.g. a malware-infected operating system under an adversary's control).
The CTAP specification defines protocols for multiple layers from USB to the browser API, and the whole stack is intended to be used with web applications (most commonly websites) in browsers.
In most cases, authenticators are USB dongles.
The protocol is very simple, allowing the devices to store very little state inside (so the tokens may be reasonably cheap) while simultaneously authenticating a virtually unlimited number of services (so each person needs only one token, not one token per application).
The user interface is usually limited to a single LED and a button that is pressed to confirm each transaction, so the devices themselves are also easy to use.
Both CTAP1 and CTAP2 share the same underlying transports: USB Human Interface Device (USB HID), Near Field Communication (NFC), and Bluetooth Smart / Bluetooth Low Energy Technology (BLE).
Currently, the most common form of two-step authentication consists of a numeric code that the user manually types into a web application.
These codes are typically generated by an app on the user's smartphone or sent via SMS.
By now, it is well-known that this form of two-step authentication is vulnerable to phishing and man-in-the-middle attacks due to the fact that the application requesting the two-step authentication code is typically not itself authenticated by the user.
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the CTAP model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here](https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs)).
Nonetheless, [some attacks are still possible](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) even with CTAP (more on this below).
## The Qubes approach to CTAP
In a conventional setup, web browsers and the USB stack (to which the authenticator is connected) are all running in the same monolithic OS.
Since the CTAP model assumes that the browser is trustworthy, any browser in the OS is able to access any key stored on the authenticator.
The user has no way to know which keys have been accessed by which browsers for which services.
If any of the browsers are compromised, it should be assumed that all the token's keys have been compromised.
(This problem can be mitigated, however, if the CTAP device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil).
In Qubes OS, by contrast, it is possible to securely compartmentalise the browser in one qube and the USB stack in another so that they are always kept separate from each other.
The Qubes CTAP Proxy then allows the token connected to the USB stack in one qube to communicate with the browser in a separate qube.
We operate under the assumption that the USB stack is untrusted from the point of view of the browser and also that the browser is not to be trusted blindly by the token.
Therefore, the token is never in the same qube as the browser.
Our proxy forwards only the data necessary to actually perform the authentication, leaving all unnecessary data out, so it won't become a vector of attack.
This is depicted in the diagram below (click for full size).
[![Qubes CTAP Proxy diagram](/attachment/doc/ctap.svg)](/attachment/doc/ctap.svg)
The Qubes CTAP Proxy has two parts: the frontend and the backend.
The frontend runs in the same qube as the browser and presents a fake USB-like HID device using `uhid`.
The backend runs in `sys-usb` and behaves like a browser.
This is done using the `fido2` reference library.
All of our code was written in Python.
The standard [qrexec](/doc/qrexec3/) policy is responsible for directing calls to the appropriate domains.
The `vault` qube with a dashed line in the bottom portion of the diagram depicts future work in which we plan to implement the Qubes CTAP Proxy with a software token in an isolated qube rather than a physical hardware token.
This is similar to the manner in which [Split GPG](/doc/split-gpg/) allows us to emulate the smart card model without physical smart cards.
One very important assumption of protocol is that the browser verifies every request sent to the authenticator --- in particular, that the web application sending an authentication request matches the application that would be authenticated by answering that request (in order to prevent, e.g., a phishing site from sending an authentication request for your bank's site).
With the WebUSB feature in Chrome, however, a malicious website can [bypass](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) this safeguard by connecting directly to the token instead of using the browser's CTAP API.
The Qubes CTAP Proxy also prevents this class of attacks by implementing an additional verification layer.
This verification layer allows you to enforce, for example, that the web browser in your `twitter` qube can only access the CTAP key associated with `https://twitter.com`.
This means that if anything in your `twitter` qube were compromised --- the browser or even the OS itself --- it would still not be able to access the CTAP keys on your token for any other websites or services, like your email and bank accounts.
This is another significant security advantage over monolithic systems.
(For details and instructions, see the [Advanced usage](#advanced-usage-per-qube-key-access) section below.)
For even more protection, you can combine this with the [Qubes firewall](/doc/firewall/) to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
By configuring the Qubes firewall to prevent your `banking` qube from accessing any other websites, you reduce the risk of another website compromising the browser in an attempt to bypass CTAP authentication.
## Installation
These instructions assume that there is a `sys-usb` qube that holds the USB stack, which is the default configuration in most Qubes OS installations.
In dom0:
```
$ sudo qubes-dom0-update qubes-ctap-dom0
$ qvm-service --enable work qubes-ctap-proxy
```
The above assumes a `work` qube in which you would like to enable ctap. Repeat the `qvm-service` command for all qubes that should have the proxy enabled. Alternatively, you can add `qubes-ctap-proxy` in VM settings -> Services in the Qube Manager of each qube you would like to enable the service.
In Fedora templates:
```
$ sudo dnf install qubes-ctap
```
In Debian templates:
```
$ sudo apt install qubes-ctap
```
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your CTAP authenticator (but see [Browser support](#template-and-browser-support) below).
## Advanced usage: per-qube key access
If you are using Qubes 4.0, you can further compartmentalise your CTAP keys by restricting each qube's access to specific keys.
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 CTAP 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/policy.d/30-user-ctapproxy.policy` with the following content:
```
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.
Do not delete the file itself.
(If you do, the default file will be recreated the next time you update, so it will no longer be empty.) Finally, follow your web application's instructions to enroll your token and use it as usual.
(This enrollment process depends on the web application and is in no way specific to Qubes CTAP.)
The default model is to allow a qube to access all and only the keys that were enrolled by that qube.
For example, if your `banking` qube enrolls your banking key, and your `twitter` qube enrolls your Twitter key, then your `banking` qube will have access to your banking key but not your Twitter key, and your `twitter` qube will have access to your Twitter key but not your banking key.
## Non-default USB qube name
If your USB qube is named differently than `sys-usb`, then do the following in the appropriate template(s):
```
systemctl enable qubes-ctapproxy@USB_QUBE.service
systemctl disable qubes-ctapproxy@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/policy.d/30-user-ctapproxy.policy`.
## Template and browser support
The large number of possible combinations of template (Fedora 37, 38; Debian 10, 11) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes CTAP Proxy.
In some cases, you may be the first person to try a particular combination.
Consequently, (and as with any new feature), users will inevitably encounter bugs.
We ask for your patience and understanding in this regard.
As always, please [report any bugs you encounter](/doc/issue-tracking/).

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

@ -11,6 +11,12 @@ ref: 166
title: Firewall
---
Introduction
----------------------------------
This page explains use of the firewall in Qubes 4.2, using `nftables`.
In Qubes 4.1, all firewall components used `iptables`. For details of that usage see [here](../firewall_4.1/)
Understanding firewalling in Qubes
----------------------------------
@ -31,8 +37,8 @@ In order to edit rules for a given qube, select it in the Qube Manager and press
If the qube is running, you can open Settings from the Qube Popup Menu.
*R4.0 note:* ICMP and DNS are no longer accessible in the GUI, but can be changed via `qvm-firewall` described below.
Connections to Updates Proxy are not made over a network so can not be allowed or blocked with firewall rules, but are controlled using the relevant policy file (see [R4.0 Updates proxy](/doc/software-update-vm/) for more detail).
ICMP and DNS are not accessible in the GUI, but can be changed via `qvm-firewall` described below.
Connections to Updates Proxy are not made over a network so can not be allowed or blocked with firewall rules, but are controlled using the relevant policy file (see [R4.x Updates proxy](/doc/software-update-vm/) for more detail).
Note that if you specify a rule by DNS name it will be resolved to IP(s) *at the moment of applying the rules*, and not on the fly for each new connection.
This means it will not work for servers using load balancing, and traffic to complex web sites which draw from many servers will be difficult to control.
@ -50,28 +56,32 @@ Rules are implemented on the netvm.
You can also manually create rules in the qube itself using standard firewalling controls.
See [Where to put firewall rules](#where-to-put-firewall-rules).
In complex cases, it might be appropriate to load a ruleset using `iptables-restore` called from `/rw/config/rc.local`.
In complex cases, it might be appropriate to load a ruleset using `nft -f /path/to/ruleset` called from `/rw/config/rc.local`, the ruleset file can be populated from the current ruleset using `nft list ruleset > /path/to/ruleset`, you should add `flush ruleset` at the top of the file to remove all existing rules before loading them.
if you do this, be aware that `rc.local` is called *after* the network is up, so local rules should not be relied upon to block leaks.
Reconnecting qubes after a NetVM reboot
-------------------------------------
Normally Qubes doesn't let the user stop a NetVM if there are other qubes running which use it as their own NetVM.
But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.0 will often automatically repair the connection.
But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.x will often automatically repair the connection.
If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0:
` qvm-prefs <vm> netvm <netvm> `
```
qvm-prefs <vm> netvm <netvm>
```
Normally qubes do not connect directly to the actual NetVM which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers.
Normally qubes do not connect directly to the actual NetVM (sys-net by default) which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers.
In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation):
` qvm-prefs sys-firewall netvm sys-net `
```
qvm-prefs sys-firewall netvm sys-net
```
Network service qubes
---------------------
Qubes does not support running any networking services (e.g. VPN, local DNS server, IPS, ...) directly in a qube that is used to run the Qubes firewall service (usually sys-firewall) for good reasons.
In particular, if you want to ensure proper functioning of the Qubes firewall, you should not tinker with iptables or nftables rules in such qubes.
In particular, if you want to ensure proper functioning of the Qubes firewall, you should not tinker with nftables rules in such qubes.
Instead, you should deploy a network infrastructure such as
@ -88,52 +98,50 @@ The sys-firewall-2 proxy ensures that:
If you adopt this model, you should be aware that all traffic will arrive at the `network service qube` appearing to originate from the IP address of `sys-firewall-2`.
For the VPN service please also look at the [VPN documentation](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md).
For the VPN service please also look at the [VPN documentation](https://forum.qubes-os.org/t/19061).
Enabling networking between two qubes
-------------------------------------
Normally any networking traffic between qubes is prohibited for security reasons.
However, in special situations, you might want to selectively allow specific qubes to establish networking connectivity between each other.
For example, this might be useful in some development work, when you want to test networking code, or to allow file exchange between HVM domains (which do not have Qubes tools installed) via SMB/scp/NFS protocols.
For example, this might be useful in some development work, when you want to test networking code, or to allow file exchange between HVM domains (which do not have Qubes tools installed) via SMB/SSH/NFS protocols.
In order to allow networking between qubes A and B follow these steps:
In order to allow networking from qube A (client) to qube B (server) follow these steps:
- Make sure both A and B are connected to the same firewall vm (by default all VMs use the same firewall VM).
- Note the Qubes IP addresses assigned to both qubes.
This can be done using the `qvm-ls -n` command, or via the Qubes Manager preferences pane for each qube.
This can be done using the `qvm-ls -n` command, or via the Qubes Manager using the IP column.
- Start both qubes, and also open a terminal in the firewall VM
- In the firewall VM's terminal enter the following iptables rule:
- In the firewall VM's terminal enter the following nftables rule:
~~~
sudo iptables -I FORWARD 2 -s <IP address of A> -d <IP address of B> -j ACCEPT
sudo nft add rule ip qubes custom-forward ip saddr <IP address of A> ip daddr <IP address of B> ct state new,established,related counter accept
~~~
- In qube B's terminal enter the following iptables rule:
- In qube B's terminal enter the following nftables rule:
~~~
sudo iptables -I INPUT -s <IP address of A> -j ACCEPT
sudo nft add rule qubes custom-input ip saddr <IP address of A> ct state new,established,related counter accept
~~~
- Now you should be able to reach B from A -- test it using e.g. ping issued from A.
Note however, that this doesn't allow you to reach A from B -- for this you would need two more rules, with A and B swapped.
- If everything works as expected, then you should write the above iptables rules into firewallVM's `qubes-firewall-user-script` script.
- If everything works as expected, then you should write the above nftables rules into firewallVM's `qubes-firewall-user-script` script.
This script is run when the netvm starts up.
You should also write relevant rules in A and B's `rc.local` script which is run when the qube is launched.
Here's an example how to update the script:
~~~
[user@sys-firewall ~]$ sudo bash
[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script
[root@sys-firewall user]# chmod +x /rw/config/qubes-firewall-user-script
[user@sys-firewall ~]$ sudo -i
[root@sys-firewall user]# echo "nft add rule ip qubes custom-forward ip saddr 10.137.2.25 ip daddr 10.137.2.6 ct state new,established,related counter accept" >> /rw/config/qubes-firewall-user-script
~~~
- Here is an example how to update `rc.local`:
~~~
[user@B ~]$ sudo bash
[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local
[root@B user]# chmod +x /rw/config/rc.local
[user@B ~]$ sudo -i
[root@B user]# echo "nft add rule qubes custom-input ip saddr 10.137.2.25 accept" >> /rw/config/rc.local
~~~
Opening a single TCP port to other network-isolated qube
@ -242,7 +250,7 @@ When the qube `unstrusted` has started (after a first reboot), you can directly
Port forwarding to a qube from the outside world
------------------------------------------------
In order to allow a service present in a qube to be exposed to the outside world in the default setup (where the qube has sys-firewall as network VM, which in turn has sys-net as network VM) the following needs to be done:
In order to allow a service present in a qube to be exposed to the outside world in the default setup (where the qube has `sys-firewall` as network VM, which in turn has `sys-net` as network VM) the following needs to be done:
- In the sys-net VM:
- Route packets from the outside world to the sys-firewall VM
@ -250,10 +258,10 @@ In order to allow a service present in a qube to be exposed to the outside world
- In the sys-firewall VM:
- Route packets from the sys-net VM to the VM
- Allow packets through the sys-firewall VM firewall
- In the qube:
- In the qube QubeDest:
- Allow packets through the qube firewall to reach the service
As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local network 192.168.x.0/24.
As an example we can take the use case of qube QubeDest running a web server listening on port 443 that we want to expose on our physical interface ens6, but only to our local network 192.168.x.y/24.
> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
@ -261,113 +269,92 @@ As an example we can take the use case of a web server listening on port 443 tha
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
You can get this information from the Settings Window for the qube, or by running this command in each qube:
`ifconfig | grep -i cast `
Note the IP addresses you will need.
You can get this information using various methods, but only the first one can be used for `sys-net` outside world IP:
- by running this command in each qube: `ip -4 -br a | grep UP`
- using `qvm-ls -n`
- in the Qubes Manager window using the column IP
- from the Settings Window for the qube
Note the IP addresses you will need, they will be required in the next steps.
> Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
**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.
For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, 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
In the sys-net VM's Terminal, the first step is to to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT --to-destination 10.137.1.z
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
```
Code the appropriate new filtering firewall rule to allow new connections for the service
> Note: the name `custom-dnat-qubeDST` is arbitrary
> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
```
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
```
> 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.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)
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
```
iptables -t nat -L -v -n
iptables -L -v -n
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
```
> Note: On Qubes R4, you can also check the nft counters
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
```
nft list table ip qubes-firewall
nft list table ip qubes
```
Send a test packet by trying to connect to the service from an external device
In this example, we can see 7 packets in the forward rule, and 3 packets in the dnat rule:
```
telnet 192.168.x.y 443
chain custom-forward {
iif "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
}
chain custom-dnat-qubeDEST {
type nat hook prerouting priority filter + 1; policy accept;
iif "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
}
```
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
(Optional) You can send a test packet by trying to connect to the service from an external device using the following command:
```
sudo nano /rw/config/rc.local
telnet 192.168.x.n 443
```
Once you have confirmed that the counters increase, store the commands used in the previous steps in `/rw/config/qubes-firewall-user-script` so they get set on sys-net start-up:
```
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
```
Content of `/rw/config/qubes-firewall-user-script` in `sys-net`:
~~~
#!/bin/sh
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
####################
# My service routing
# 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 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
# If no prerouting rule exist for my service
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.x.y -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# 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
# If no forward rule exist for my service
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.z -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~
> Note: Again in R4 the following needs to be added:
~~~
#############
# In Qubes R4
# If not already present
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.1.z tcp dport 443 ct state new counter accept
# allow forwarded traffic
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
fi
~~~
@ -375,133 +362,77 @@ fi
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
In the sys-firewall VM's Terminal, add a DNAT chain that will contain routing rules:
```
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j DNAT --to-destination 10.137.0.xx
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
```
Code the appropriate new filtering firewall rule to allow new connections for the service
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
```
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
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
```
> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
> Note: On Qubes R4
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
```
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
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
```
Once you have confirmed that the counters increase, store these command in `/rw/config/qubes-firewall-user-script`
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
Once you have confirmed that the counters increase, store these commands in the script `/rw/config/qubes-firewall-user-script`
```
sudo nano /rw/config/qubes-firewall-user-script
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
```
Content of `/rw/config/qubes-firewall-user-script` in `sys-firewall`:
~~~
#!/bin/sh
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
####################
# My service routing
# 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 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
# If no prerouting rule exist for my service
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.z -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# 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
# If no forward rule exist for my service
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.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
################
# In Qubes OS R4
# If not already present
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.xx tcp dport 443 ct state new counter accept
# allow forwarded traffic
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
fi
~~~
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.
If the service should be available to other VMs on the same system, do not forget to specify the additional rules described earlier in this guide.
**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.
No routing is required in the destination qube, only filtering.
For the following example, we assume that the target VM running the web server has the IP address 10.137.0.xx
The according rule to allow the traffic is:
```
sudo nano /rw/config/rc.local
nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept
```
~~~
######################
# My service filtering
To make it persistent, you need to add this command in the script `/rw/config/rc.local`:
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
```
[user@qubeDEST user]$ sudo -i
[root@qubeDEST user]# echo 'nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept' >> /rw/config/rc.local
```
# 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
# If no input rule exists for my service
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.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~
This time testing should allow connectivity to the service as long as the service is up :-)
This time testing should allow connectivity to the service as long qubeDEST is running and the service is up :-)
Where to put firewall rules
---------------------------
Implicit in the above example [scripts](/doc/config-files/), but worth calling attention to: for all qubes *except* those supplying networking, iptables commands should be added to the `/rw/config/rc.local` script.
For app qubes supplying networking (`sys-firewall` inclusive), iptables commands should be added to `/rw/config/qubes-firewall-user-script`.
Implicit in the above example [scripts](/doc/config-files/), but worth calling attention to: for all qubes *except* those supplying networking, nftables commands should be added to the `/rw/config/rc.local` script.
For service qubes supplying networking (`sys-firewall` and `sys-net` inclusive), nftables commands should be added to `/rw/config/qubes-firewall-user-script`.
Firewall troubleshooting
------------------------
@ -509,3 +440,34 @@ Firewall troubleshooting
Firewall logs are stored in the systemd journal of the qube the firewall is running in (probably `sys-firewall`).
You can view them by running `sudo journalctl -u qubes-firewall.service` in the relevant qube.
Sometimes these logs can contain useful information about errors that are preventing the firewall from behaving as you would expect.
An effective console utility to troubleshoot network is [tcpdump](https://www.tcpdump.org/), it can be used to display network packets entering or leaving network interfaces.
For instance, if you want to check if your network interface `eth0` is receiving packets on port TCP 443 from the network 192.168.x.y, you can run this command:
```
tcpdump -i eth0 -nn dst port 443 and src net 192.168.x.y/24
```
This can be used effectively in a destination qube and its Network VM to see if forwarding / NAT rules are working.
Nftables tips
-------------
A simple way to experiment changes with your ruleset can be achieved by saving the current working ruleset in two files, one for backup and the other for making changes.
By adding `flush ruleset` at the top of the file, you can achieve atomic update, which mean the new ruleset would replace the current one only if it fully succeed to load.
You can dump the ruleset in two files using the following command:
```
nft list ruleset | tee nft_backup | tee nft_new_ruleset
```
Then, edit `nft_new_ruleset`, add `flush ruleset` on top and make changes, load it with `nft -f nft_new_ruleset`.
You can revert to the original ruleset with the following commands:
```
nft flush ruleset && nft -f nft_backup
```

513
user/security-in-qubes/firewall_4.1.md Normal file
View File

@ -0,0 +1,513 @@
---
lang: en
layout: doc
permalink: /doc/firewall_4.1/
redirect_from:
ref: 401
title: Firewall 4.1
---
Introduction
----------------------------------
This page explains use of the firewall in Qubes 4.1, using `iptables`.
From Qubes 4.2, all firewall components use `nftables`. For details of that usage see [here](../firewall/)
Understanding firewalling in Qubes
----------------------------------
Every qube in Qubes is connected to the network via a FirewallVM, which is used to enforce network-level policies.
By default there is one default FirewallVM, but the user is free to create more, if needed.
For more information, see the following:
- [https://groups.google.com/group/qubes-devel/browse\_thread/thread/9e231b0e14bf9d62](https://groups.google.com/group/qubes-devel/browse_thread/thread/9e231b0e14bf9d62)
- [https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html)
How to edit rules
-----------------
In order to edit rules for a given qube, select it in the Qube Manager and press the "firewall" button.
![r4.0-manager-firewall.png](/attachment/doc/r4.0-manager-firewall.png)
If the qube is running, you can open Settings from the Qube Popup Menu.
*R4.0 note:* ICMP and DNS are no longer accessible in the GUI, but can be changed via `qvm-firewall` described below.
Connections to Updates Proxy are not made over a network so can not be allowed or blocked with firewall rules, but are controlled using the relevant policy file (see [R4.0 Updates proxy](/doc/software-update-vm/) for more detail).
Note that if you specify a rule by DNS name it will be resolved to IP(s) *at the moment of applying the rules*, and not on the fly for each new connection.
This means it will not work for servers using load balancing, and traffic to complex web sites which draw from many servers will be difficult to control.
Instead of using the firewall GUI, you can use the `qvm-firewall` command in Dom0 to edit the firewall rules by hand.
This gives you greater control than by using the GUI.
The firewall rules for each qube are saved in an XML file in that qube's directory in dom0:
```
/var/lib/qubes/appvms/<vm-name>/firewall.xml
```
Rules are implemented on the netvm.
You can also manually create rules in the qube itself using standard firewalling controls.
See [Where to put firewall rules](#where-to-put-firewall-rules).
In complex cases, it might be appropriate to load a ruleset using `iptables-restore` called from `/rw/config/rc.local`.
if you do this, be aware that `rc.local` is called *after* the network is up, so local rules should not be relied upon to block leaks.
Reconnecting qubes after a NetVM reboot
-------------------------------------
Normally Qubes doesn't let the user stop a NetVM if there are other qubes running which use it as their own NetVM.
But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.0 will often automatically repair the connection.
If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0:
` qvm-prefs <vm> netvm <netvm> `
Normally qubes do not connect directly to the actual NetVM which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers.
In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation):
` qvm-prefs sys-firewall netvm sys-net `
Network service qubes
---------------------
Qubes does not support running any networking services (e.g. VPN, local DNS server, IPS, ...) directly in a qube that is used to run the Qubes firewall service (usually sys-firewall) for good reasons.
In particular, if you want to ensure proper functioning of the Qubes firewall, you should not tinker with iptables or nftables rules in such qubes.
Instead, you should deploy a network infrastructure such as
~~~
sys-net <--> sys-firewall-1 <--> network service qube <--> sys-firewall-2 <--> [client qubes]
~~~
Thereby sys-firewall-1 is only needed if you have other client qubes connected there, or you want to manage the traffic of the local network service qube.
The sys-firewall-2 proxy ensures that:
1. Firewall changes done in the network service qube cannot render the Qubes firewall ineffective.
2. Changes to the Qubes firewall by the Qubes maintainers cannot lead to unwanted information leakage in combination with user rules deployed in the network service qube.
3. A compromise of the network service qube does not compromise the Qubes firewall.
If you adopt this model, you should be aware that all traffic will arrive at the `network service qube` appearing to originate from the IP address of `sys-firewall-2`.
For the VPN service please also look at the [VPN documentation](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md).
Enabling networking between two qubes
-------------------------------------
Normally any networking traffic between qubes is prohibited for security reasons.
However, in special situations, you might want to selectively allow specific qubes to establish networking connectivity between each other.
For example, this might be useful in some development work, when you want to test networking code, or to allow file exchange between HVM domains (which do not have Qubes tools installed) via SMB/scp/NFS protocols.
In order to allow networking between qubes A and B follow these steps:
- Make sure both A and B are connected to the same firewall vm (by default all VMs use the same firewall VM).
- Note the Qubes IP addresses assigned to both qubes.
This can be done using the `qvm-ls -n` command, or via the Qubes Manager preferences pane for each qube.
- Start both qubes, and also open a terminal in the firewall VM
- In the firewall VM's terminal enter the following iptables rule:
~~~
sudo iptables -I FORWARD 2 -s <IP address of A> -d <IP address of B> -j ACCEPT
~~~
- In qube B's terminal enter the following iptables rule:
~~~
sudo iptables -I INPUT -s <IP address of A> -j ACCEPT
~~~
- Now you should be able to reach B from A -- test it using e.g. ping issued from A.
Note however, that this doesn't allow you to reach A from B -- for this you would need two more rules, with A and B swapped.
- If everything works as expected, then you should write the above iptables rules into firewallVM's `qubes-firewall-user-script` script.
This script is run when the netvm starts up.
You should also write relevant rules in A and B's `rc.local` script which is run when the qube is launched.
Here's an example how to update the script:
~~~
[user@sys-firewall ~]$ sudo bash
[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script
[root@sys-firewall user]# chmod +x /rw/config/qubes-firewall-user-script
~~~
- Here is an example how to update `rc.local`:
~~~
[user@B ~]$ sudo bash
[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local
[root@B user]# chmod +x /rw/config/rc.local
~~~
Opening a single TCP port to other network-isolated qube
--------------------------------------------------------
In the case where a specific TCP port needs to be exposed from a qubes to another one, you do not need to enable networking between them but you can use the qubes RPC service `qubes.ConnectTCP`.
**1. Simple port binding**
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/policy.d/30-user-networking.policy`: (it could be `another-other-name.policy` -- just remember to keep it consistent)
~~~
qubes.ConnectTCP * untrusted @default allow target=mytcp-service
~~~
- In untrusted, use the Qubes tool `qvm-connect-tcp`:
~~~
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
~~~
> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`.
Here `@default` is used to hide the destination qube which is specified in the Qubes RPC policy by `target=mytcp-service`. Equivalent call is to use the tool as follow:
~~~
[user@untrusted #]$ qvm-connect-tcp ::444
~~~
which means to use default local port of `unstrusted` as the same of the remote port and unspecified destination qube is `@default` by default in `qrexec` call.
**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
~~~
qubes.ConnectTCP * untrusted mytcp-service allow
~~~
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
~~~
The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:10444`.
**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/policy.d/30-user-networking.policy`:
~~~
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`
~~~
[user@untrusted #]$ qvm-connect-tcp ::445
~~~
will restrict the binding to only the corresponding TCP port of `mytcp-service-bis`.
**4. Permanent port binding**
For creating a permanent port bind between two qubes, `systemd` can be used. We use the case of the first example. In `/rw/config` (or any place you find suitable) of qube `untrusted`, create `my-tcp-service.socket` with content:
~~~
[Unit]
Description=my-tcp-service
[Socket]
ListenStream=127.0.0.1:444
Accept=true
[Install]
WantedBy=sockets.target
~~~
and `my-tcp-service@.service` with content:
~~~
[Unit]
Description=my-tcp-service
[Service]
ExecStart=qrexec-client-vm '' qubes.ConnectTCP+444
StandardInput=socket
StandardOutput=inherit
~~~
In `/rw/config/rc.local`, append the lines:
~~~
cp -r /rw/config/my-tcp-service.socket /rw/config/my-tcp-service@.service /lib/systemd/system/
systemctl daemon-reload
systemctl start my-tcp-service.socket
~~~
When the qube `unstrusted` has started (after a first reboot), you can directly access the service of `mytcp-service` running on port `444` as `localhost:444`.
Port forwarding to a qube from the outside world
------------------------------------------------
In order to allow a service present in a qube to be exposed to the outside world in the default setup (where the qube has sys-firewall as network VM, which in turn has sys-net as network VM) the following needs to be done:
- In the sys-net VM:
- Route packets from the outside world to the sys-firewall VM
- Allow packets through the sys-net VM firewall
- In the sys-firewall VM:
- Route packets from the sys-net VM to the VM
- Allow packets through the sys-firewall VM firewall
- In the qube:
- Allow packets through the qube firewall to reach the service
As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local network 192.168.x.0/24.
> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
You can get this information from the Settings Window for the qube, or by running this command in each qube:
`ifconfig | grep -i cast `
Note the IP addresses you will need.
> Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
**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.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.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.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)
```
iptables -t nat -L -v -n
iptables -L -v -n
```
> Note: On Qubes R4, you can also check the nft counters
```
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.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
```
sudo nano /rw/config/rc.local
```
~~~
#!/bin/sh
####################
# My service routing
# 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 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
# If no prerouting rule exist for my service
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.x.y -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# 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
# If no forward rule exist for my service
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.z -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~
> Note: Again in R4 the following needs to be added:
~~~
#############
# In Qubes R4
# If not already present
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.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.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.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 `
> 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.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`
```
sudo nano /rw/config/qubes-firewall-user-script
```
~~~
#!/bin/sh
####################
# My service routing
# 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 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
# If no prerouting rule exist for my service
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.z -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# 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
# If no forward rule exist for my service
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.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
################
# In Qubes OS R4
# If not already present
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.xx tcp dport 443 ct state new counter accept
fi
~~~
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 nano /rw/config/rc.local
```
~~~
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# 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
# If no input rule exists for my service
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.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
~~~
This time testing should allow connectivity to the service as long as the service is up :-)
Where to put firewall rules
---------------------------
Implicit in the above example [scripts](/doc/config-files/), but worth calling attention to: for all qubes *except* those supplying networking, iptables commands should be added to the `/rw/config/rc.local` script.
For app qubes supplying networking (`sys-firewall` inclusive), iptables commands should be added to `/rw/config/qubes-firewall-user-script`.
Firewall troubleshooting
------------------------
Firewall logs are stored in the systemd journal of the qube the firewall is running in (probably `sys-firewall`).
You can view them by running `sudo journalctl -u qubes-firewall.service` in the relevant qube.
Sometimes these logs can contain useful information about errors that are preventing the firewall from behaving as you would expect.

393
user/security-in-qubes/mfa.md Normal file
View File

@ -0,0 +1,393 @@
---
lang: en
layout: doc
permalink: /doc/mfa/
redirect_from:
- /doc/yubi-key/
- /en/doc/yubi-key/
- /doc/YubiKey/
- /doc/yubikey/
ref: 169
title: Multi-factor Login
---
## Multi-factor authentication within particular qubes
Most use cases for the hardware tokens can be achieved exactly as described by the
manufacturer or other instructions found online. One usually just needs to
attach the token (e.g. 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 CTAP in Qubes is described
[here](https://www.qubes-os.org/doc/ctap-proxy/).
## Multi-factor login for Qubes OS
By default Qubes has two protection mechanisms against attackers.
The first is full disk encryption and the second the user login screen / lockscreen.
This article section concerns only adding multi-factor authentication to the second one.
### Time-based One-time Password (TOTP)
As the name implies, this generates authentication code that is time-dependent. You can save the TOTP secret in a mobile app like [FreeOTP](https://en.wikipedia.org/wiki/FreeOTP)
and then use it as an additional factor to login to your Qubes system.
> **Warning**: remember to keep backup access codes.
1. Download `google-authenticator` in dom0:
```
sudo qubes-dom0-update google-authenticator
```
2. Run google authenticator:
```
google-authenticator
```
3. Walk through the setup instructions 2 which will also generate your QR code for your auth app of choice:
```
Do you want me to update your “/home/user/.google_authenticator” file (y/n) y
Do you want to disallow multiple uses of the same authentication token? This restricts you to one login about every 30s, but it increases your chances to notice or even prevent man-in-the-middle attacks (y/n)
By default, tokens are good for 30 seconds, and to compensate for possible time-skew between the client and the server, we allow an extra token before and after the current time. If you experience problems with poor time synchronization, you can increase the window from its default size of 1:30min to about 4min. Do you want to do so (y/n)
If the computer that you are logging into isn’t hardened against brute-force login attempts, you can enable rate-limiting for the authentication module. By default, this limits attackers to no more than 3 login attempts every 30s. Do you want to enable rate-limiting (y/n)
```
> **Warning**: in the next session if incorrectly performed, there is the risk of locking yourself out. Before procedding ensure that you have an up-to-date backup.
>
> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd> and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>.
Now we are going to add the authenticator as a login requirement:
1. `sudo authselect create-profile mfa --base-on sssd`
2. Edit the custom system authentication template with `sudo nanois encouraged /etc/authselect/custom/mfa/system-auth`.
Add the following line right after `auth required pam_faildelay.so delay=2000000`:
```
auth required pam_google_authenticator.so
```
After the change, the top of the file should look like this:
```
{imply "with-smartcard" if "with-smartcard-required"}
auth required pam_env.so
auth required pam_faildelay.so delay=2000000
auth required pam_google_authenticator.so
```
3. Lastly, activate this authentication method with:
```
sudo authselect select custom/mfa
```
Now you can test by locking the screen with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>l</kbd>. If it was successful and you are pleased with the results, restart your computer.
**Note**: When logging in. the first thing you put is the TOTP secret and then the password. This is true in the screen locker and as well as the session manager (the login window that shows right after you put the disk encryption passphrase).
After this is done, its recommended to do a backup. This is because as long as you incude dom0 in the backup, your authentication code will be backed up as well.
#### Troubleshooting
The following assumes you haven't restarted your computer since setting up TOTP secret.
1. Switch to TTY2 with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd>.
2. Revert to the original policy with:
```
sudo authselect select sssd
```
3. Switch back to the graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>. You should be able to login normally (without multi-factor authentication).
4. Change the mfa custom policy and apply it again.
#### Lost TOTP / authentication device?
In case you've lost your TOTP authentication device, you have two options.
The first option is backup codes. When generating the TOTP secret you must have saved some recovery codes. Those can be used in place of the TOTP code, but they're discarded after use. So make sure you redo the multi-factor authentications intructions.
The second option is recovery from a backup. It will work as long as you included dom0 in said backup. After restoring the dom0 backup, open a terminal in dom0 and the file should be located in `/home/<USER>/home-restore-<DATE>/dom0-home/<USER>/.google_authenticator`.
### Login with a YubiKey / NitroKey3
The YubiKey / NitroKey3 is a hardware authentication device manufactured by Yubico / NitroKey
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.
You can use a YubiKey / NitroKey3 to enhance the user authentication in Qubes. The following
instructions explain how to setup the YubiKey / NitroKey3 as an *additional* way to login.
After setting it up, you can login by providing both - a password typed in via
keyboard *and* the YubiKey / NitroKey3 plugged in. Someone eavesdropping your login attempt
would not be able to login by only observing and remembering your password.
Stealing your YubiKey / NitroKey3 would not suffice to login either. Only if an attacker has
both, the password and the Yubikey / NitroKey3, 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 / NitroKey3 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 / NitroKey3
To use the YubiKey / NitroKey3 for multi-factor authentication you need to
* install software for the YubiKey / NitroKey3,
* configure the YubiKey for the
[Challenge-Response](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication)
mode or the NitroKey3 for [HOTP](https://en.wikipedia.org/wiki/HMAC-based_one-time_password) mode,
* store the password for YubiKey / NitroKey3 Login and the Challenge-Response / HOTP secret in
dom0,
* enable YubiKey / NitroKey3 authentication for every service you want to use it for.
All these requirements are described below, step by step, for the YubiKey and NitroKey3.
Note that setting up both a YubiKey and a NitroKey3 is not supported.
1. Install YubiKey / NitroKey3 software in the template on which your USB VM is based.
Without this software the challenge-response / HOTP mechanism won't work.
**YubiKey**
For Fedora.
```
sudo dnf install ykpers
```
For Debian.
```
sudo apt-get install yubikey-personalization
```
**NitroKey3**
Follow the installation instructions on the official [NitroKey
website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
**WARNING**: *as of April 2024 the official instructions involve using pipx to
install the pynitrokey package and its dependencies without any GPG
verification! This is not a recommended practice, but will soon be
fixed by NitroKey when they start providing release artifacts with
detached signatures on [their GitHub](https://github.com/Nitrokey/pynitrokey/releases).
Proper packaging and distribution for Debian and perhaps Fedora is
also planned for the mid-long term.*
**Installing packages using pip or pipx is not recommended!**
**both**
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. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in
dom0. This provides the program to authenticate with password and YubiKey / NitroKey3.
```
sudo qubes-dom0-update qubes-yubikey-dom0
```
3. Configure your YubiKey / NitroKey3:
**YubiKey**
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.
You need to (temporarily) install the package "yubikey-personalization-gui" and
run it by typing `yubikey-personalization-gui` in the command line.
- 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.
**NitroKey3**
Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
USB qube and running the following commands in it:
```
AESKEY=$(echo -n "your-20-digit-secret" | base32)
nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
```
Note that the 20 digit sequence can contain any printable ASCII character,
e.g. letters, numbers, punctuation marks. The actual `Secret Key (base 32)`
is the base32 encoded form of that sequence.
**both**
We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `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 one gets
lost, stolen or breaks) you can write the same settings into other
YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up
the secret for multiple of them, but you must always use the same NitroKey, because the
HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
of this method. If you want to switch to a different NitroKey later, delete the file
`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
Do the same if for some reason your counters get desynchronized (it stops working), e.g. due
to connectivity issues (NitroKey3A Minis are known to wear out quickly).
4. **YubiKey**
Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
Note that if you had previously used a NitroKey3 with this package, you *must* delete
the file `/etc/qubes/yk-keys/nk-hotp-secret` or its content!
**NitroKey3**
Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY`
(in base 32 format) into it.
5. As mentioned before, you need to define a new password that is only used in
combination with the YubiKey / NitroKey3. You can write this password in plain text into
`/etc/qubes/yk-keys/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/login-pass-hashed.hex` in dom0.
You can calculate your hashed password using the following two commands.
First run the following command to store your password in a temporary variable `password`.
(This way your password will not leak to the terminal command history file.)
```
read -r password
```
Now run the following command to calculate your hashed password.
```
echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
```
6. To enable multi-factor authentication for a service, you need to add
```
auth include yubikey
```
(same for YubiKey and NitroKey3) to the corresponding service file in `/etc/pam.d/` in dom0.
This means, if you want to enable the login via YubiKey / NitroKey3 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.
It is important, that `auth include yubikey` is added at the beginning of
these files, otherwise it will most likely not work.
7. Adjust the USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/vm` in dom0.
#### Usage
When you want to authenticate
1. plug your YubiKey / NitroKey3 into an USB slot,
2. enter the password associated with the YubiKey / NitroKey3,
3. press Enter and
4. press the button of the YubiKey / NitroKey3, if you configured the confirmation
(it will light up or blink).
When everything is ok, your screen will be unlocked.
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.
#### Optional: Enforce YubiKey / NitroKey3 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.
```
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
```
#### Optional: Locking the screen when YubiKey / NitroKey3 is removed
You can setup your system to automatically lock the screen when you unplug your YubiKey / NitroKey3.
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.
In dom0:
1. First configure the qrexec service.
Create `/etc/qubes-rpc/custom.LockScreen` with a simple command to lock the screen.
In the case of xscreensaver (used in Xfce) it would be:
```
DISPLAY=:0 xscreensaver-command -lock
```
2. Then make `/etc/qubes-rpc/custom.LockScreen` executable.
```
sudo chmod +x /etc/qubes-rpc/custom.LockScreen
```
3. Allow your USB VM to call that service.
Assuming that it's named `sys-usb` it would require creating `/etc/qubes-rpc/policy/custom.LockScreen` with:
```
sys-usb dom0 allow
```
In your USB VM:
3. Create udev hook.
Store it in `/rw/config` to have it persist across VM restarts.
For example name the file `/rw/config/yubikey.rules`.
Add the following line:
```
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen"
```
4. Ensure that the udev hook is placed in the right place after VM restart.
Append to `/rw/config/rc.local`:
```
ln -s /rw/config/yubikey.rules /etc/udev/rules.d/
udevadm control --reload
```
5. Then make `/rw/config/rc.local` executable.
```
sudo chmod +x /rw/config/rc.local
```
6. For changes to take effect, you need to call this script manually for the first time.
```
sudo /rw/config/rc.local
```
If you use KDE, the command(s) in first step would be different:
```
# In the case of USB VM being autostarted, it will not have direct access to D-Bus
# session bus, so find its address manually:
kde_pid=`pidof kdeinit4`
export `cat /proc/$kde_pid/environ|grep -ao 'DBUS_SESSION_BUS_ADDRESS=[[:graph:]]*'`
qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock
```

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

@ -1,135 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/u2f-proxy/
ref: 167
title: U2F proxy
---
The [Qubes U2F Proxy](https://github.com/QubesOS/qubes-app-u2f) is a secure proxy intended to make use of U2F two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies](/doc/usb/) implemented in Qubes.
## What is U2F?
[U2F](https://en.wikipedia.org/wiki/U2F), which stands for "Universal 2nd Factor", is a framework for authentication using hardware devices (U2F tokens) as "second factors", i.e. *what you have* as opposed to *what you know*, like a passphrase.
This additional control provides [good protection](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/) in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
While passphrase compromise may not be obvious to the user, a physical device that cannot be duplicated must be stolen to be used outside of the owner's control.
Nonetheless, it is important to note at the outset that U2F cannot guarantee security when the host system is compromised (e.g. a malware-infected operating system under an adversary's control).
The U2F specification defines protocols for multiple layers from USB to the browser API, and the whole stack is intended to be used with web applications (most commonly websites) in browsers.
In most cases, tokens are USB dongles.
The protocol is very simple, allowing the devices to store very little state inside (so the tokens may be reasonably cheap) while simultaneously authenticating a virtually unlimited number of services (so each person needs only one token, not one token per application).
The user interface is usually limited to a single LED and a button that is pressed to confirm each transaction, so the devices themselves are also easy to use.
Currently, the most common form of two-step authentication consists of a numeric code that the user manually types into a web application.
These codes are typically generated by an app on the user's smartphone or sent via SMS.
By now, it is well-known that this form of two-step authentication is vulnerable to phishing and man-in-the-middle attacks due to the fact that the application requesting the two-step authentication code is typically not itself authenticated by the user.
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the U2F model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here](https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs)).
Nonetheless, [some attacks are still possible](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) even with U2F (more on this below).
## The Qubes approach to U2F
In a conventional setup, web browsers and the USB stack (to which the U2F token is connected) are all running in the same monolithic OS.
Since the U2F model assumes that the browser is trustworthy, any browser in the OS is able to access any key stored on the U2F token.
The user has no way to know which keys have been accessed by which browsers for which services.
If any of the browsers are compromised, it should be assumed that all of the token's keys have been compromised.
(This problem can be mitigated, however, if the U2F device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil).
In Qubes OS, by contrast, it is possible to securely compartmentalise the browser in one qube and the USB stack in another so that they are always kept separate from each other.
The Qubes U2F Proxy then allows the token connected to the USB stack in one qube to communicate with the browser in a separate qube.
We operate under the assumption that the USB stack is untrusted from the point of view of the browser and also that the browser is not to be trusted blindly by the token.
Therefore, the token is never in the same qube as the browser.
Our proxy forwards only the data necessary to actually perform the authentication, leaving all unnecessary data out, so it won't become a vector of attack.
This is depicted in the diagram below (click for full size).
[![Qubes U2F Proxy diagram](/attachment/doc/u2f.svg)](/attachment/doc/u2f.svg)
The Qubes U2F Proxy has two parts: the frontend and the backend.
The frontend runs in the same qube as the browser and presents a fake USB-like HID device using `uhid`.
The backend runs in `sys-usb` and behaves like a browser.
This is done using the `u2flib_host` reference library.
All of our code was written in Python.
The standard [qrexec](/doc/qrexec3/) policy is responsible for directing calls to the appropriate domains.
The `vault` qube with a dashed line in the bottom portion of the diagram depicts future work in which we plan to implement the Qubes U2F Proxy with a software token in an isolated qube rather than a physical hardware token.
This is similar to the manner in which [Split GPG](/doc/split-gpg/) allows us to emulate the smart card model without physical smart cards.
One very important assumption of U2F is that the browser verifies every request sent to the U2F token --- in particular, that the web application sending an authentication request matches the application that would be authenticated by answering that request (in order to prevent, e.g., a phishing site from sending an authentication request for your bank's site).
With the WebUSB feature in Chrome, however, a malicious website can [bypass](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) this safeguard by connecting directly to the token instead of using the browser's U2F API.
The Qubes U2F Proxy also prevents this class of attacks by implementing an additional verification layer.
This verification layer allows you to enforce, for example, that the web browser in your `twitter` qube can only access the U2F key associated with `https://twitter.com`.
This means that if anything in your `twitter` qube were compromised --- the browser or even the OS itself --- it would still not be able to access the U2F keys on your token for any other websites or services, like your email and bank accounts.
This is another significant security advantage over monolithic systems.
(For details and instructions, see the [Advanced usage](#advanced-usage-per-qube-key-access) section below.)
For even more protection, you can combine this with the [Qubes firewall](/doc/firewall/) to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
By configuring the Qubes firewall to prevent your `banking` qube from accessing any other websites, you reduce the risk of another website compromising the browser in an attempt to bypass U2F authentication.
## Installation
These instructions assume that there is a `sys-usb` qube that holds the USB stack, which is the default configuration in most Qubes OS installations.
In dom0:
```
$ sudo qubes-dom0-update qubes-u2f-dom0
$ qvm-service --enable work qubes-u2f-proxy
```
The above assumes a `work` qube in which you would like to enable u2f. Repeat the `qvm-service` command for all qubes that should have the proxy enabled. Alternatively, you can add `qubes-u2f-proxy` in VM settings -> Services in the Qube Manager of each qube you would like to enable the service.
In Fedora templates:
```
$ sudo dnf install qubes-u2f
```
In Debian templates:
```
$ sudo apt install qubes-u2f
```
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your U2F token (but see [Browser support](#template-and-browser-support) below).
## Advanced usage: per-qube key access
If you are using Qubes 4.0, you can further compartmentalise your U2F keys by restricting each qube's access to specific keys.
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/policy.d/30-user-u2fproxy.policy` with the following content:
```
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.
Do not delete the file itself.
(If you do, the default file will be recreated the next time you update, so it will no longer be empty.) Finally, follow your web application's instructions to enroll your token and use it as usual.
(This enrollment process depends on the web application and is in no way specific to Qubes U2F.)
The default model is to allow a qube to access all and only the keys that were enrolled by that qube.
For example, if your `banking` qube enrolls your banking key, and your `twitter` qube enrolls your Twitter key, then your `banking` qube will have access to your banking key but not your Twitter key, and your `twitter` qube will have access to your Twitter key but not your banking key.
## Non-default USB qube name
If your USB qube is named differently than `sys-usb`, then do the following in the appropriate template(s):
```
systemctl enable qubes-u2fproxy@USB_QUBE.service
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/policy.d/30-user-u2fproxy.policy`.
## Template and browser support
The large number of possible combinations of template (Fedora 27, 28; Debian 8, 9) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes U2F Proxy.
In some cases, you may be the first person to try a particular combination.
Consequently (and as with any new feature), users will inevitably encounter bugs.
We ask for your patience and understanding in this regard.
As always, please [report any bugs you encounter](/doc/issue-tracking/).

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

@ -10,7 +10,7 @@ ref: 165
title: Passwordless root access in qubes
---
Background (`/etc/sudoers.d/qubes` in VM):
The background to passswordless root access is summarised in this statement, that used to be found at `/etc/sudoers.d/qubes` in each qube:
```
user ALL=(ALL) NOPASSWD: ALL
@ -59,59 +59,31 @@ user ALL=(ALL) NOPASSWD: ALL
#
# joanna.
```
The core of this statement continues to reflect the views of the Qubes developers.
Below is a complete list of configuration made according to the above statement, with (not necessary complete) list of mechanisms depending on each of them:
Passwordless root is provided by the `qubes-core-agent-passwordless-root` package.
Details of the implementation are [here](/doc/vm-sudo-implementation).
1. sudo (`/etc/sudoers.d/qubes`):
[Minimal templates](/doc/templates/minimal/), which are intended for use by advanced users, do not have this package installed by default.
```
user ALL=(ALL) NOPASSWD: ALL
(...)
```
Replacing passwordless root access
----------------------------------
- Easy user -> root access (main option for the user).
- `qvm-usb` (not really working, as of R2).
Some users may wish to modify their system by enabling user/root isolation in qubes.
We do not support this in any packages, but users are free to remove the qubes-core-agent-passwordless-root package if they wish, using standard packaging tools.
2. PolicyKit (`/etc/polkit-1/rules.d/00-qubes-allow-all.rules`):
```
//allow any action, detailed reasoning in sudoers.d/qubes
polkit.addRule(function(action,subject) { return polkit.Result.YES; });
```
and `/etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla`:
```
[Qubes allow all]
Identity=*
Action=*
ResultAny=yes
ResultInactive=yes
ResultActive=yes
```
- NetworkManager configuration from normal user (`nm-applet`).
- Updates installation (`gpk-update-viewer`).
- User can use pkexec just like sudo Note: above is needed mostly because Qubes user GUI session isn't treated by PolicyKit/logind as "local" session because of the way in which X server and session is started.
Perhaps we will address this issue in the future, but this is really low priority.
Patches welcomed anyway.
3. Empty root password:
- Used for access to 'root' account from text console (`qvm-console-dispvm`) - the only way to access the VM when GUI isn't working.
- Can be used for easy 'su -' from user to root.
Root access can then be gained from dom0 by (e.g) `qvm-run -u root QUBE qubes-run-terminal`, or `qvm-console-dispvm QUBE`.
Replacing passwordless root access with Dom0 user prompt
--------------------------------------------------------
While the Qubes developers support the statement above, some Qubes users may wish to enable user/root isolation in VMs anyway.
We do not support 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.
An alternative approach is to enable user/root isolation by using a dom0 generated prompt.
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.**
Dom0 passwordless root access
-----------------------------
There is also passwordless user->root access in dom0.
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.
There is also passwordless user->root access in dom0.
As stated in the comment in `/etc/sudoers.d/qubes` there is really no point in user/root isolation in dom0, because all user data (and the whole Qubes management interface) is already accessible to the user, so there is nothing more to be gained from the dom0 root account.

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

@ -1,248 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/yubikey/
redirect_from:
- /doc/yubi-key/
- /en/doc/yubi-key/
- /doc/YubiKey/
ref: 169
title: YubiKey
---
"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))
## General usage in Qubes OS
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/).
## Multi-factor login for Qubes OS
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.
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
```
For Debian.
```
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 as well if you would like to avoid rebooting it.
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
```
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.
You need to (temporarily) install the package "yubikey-personalization-gui" and
run it by typing `yubikey-personalization-gui` in the command line.
- 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.
First run the following command to store your password in a temporary variable `password`.
(This way your password will not leak to the terminal command history file.)
```
read -r password
```
Now run the following command to calculate your hashed password.
```
echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
```
6. To enable multi-factor authentication for a service, you need to add
```
auth include yubikey
```
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.
It is important, that `auth include yubikey` is added at the beginning of
these files, otherwise it will most likely not work.
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 authenticate
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 normal login password, but do it in a secure
location where no one can snoop your password.
### 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.
```
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
```
### 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.
In dom0:
1. First configure the qrexec service.
Create `/etc/qubes-rpc/custom.LockScreen` with a simple command to lock the screen.
In the case of xscreensaver (used in Xfce) it would be:
```
DISPLAY=:0 xscreensaver-command -lock
```
2. Then make `/etc/qubes-rpc/custom.LockScreen` executable.
```
sudo chmod +x /etc/qubes-rpc/custom.LockScreen
```
3. Allow your USB VM to call that service.
Assuming that it's named `sys-usb` it would require creating `/etc/qubes-rpc/policy/custom.LockScreen` with:
```
sys-usb dom0 allow
```
In your USB VM:
3. Create udev hook.
Store it in `/rw/config` to have it persist across VM restarts.
For example name the file `/rw/config/yubikey.rules`.
Add the following line:
```
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen"
```
4. Ensure that the udev hook is placed in the right place after VM restart.
Append to `/rw/config/rc.local`:
```
ln -s /rw/config/yubikey.rules /etc/udev/rules.d/
udevadm control --reload
```
5. Then make `/rw/config/rc.local` executable.
```
sudo chmod +x /rw/config/rc.local
```
6. For changes to take effect, you need to call this script manually for the first time.
```
sudo /rw/config/rc.local
```
If you use KDE, the command(s) in first step would be different:
```
# In the case of USB VM being autostarted, it will not have direct access to D-Bus
# session bus, so find its address manually:
kde_pid=`pidof kdeinit4`
export `cat /proc/$kde_pid/environ|grep -ao 'DBUS_SESSION_BUS_ADDRESS=[[:graph:]]*'`
qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock
```

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

@ -51,6 +51,7 @@ If you wish to install a new, unmodified Fedora template instead of upgrading a
[user@dom0 ~]$ qvm-shutdown fedora-<new>
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ qvm-features fedora-<new> template-name fedora-<new>
```
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
@ -159,15 +160,21 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
```
8. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
8. Set the template-name, which is used by the Qubes updater.
9. (Optional) Make the new template the global default.
```
[user@dom0 ~]$ qvm-features fedora-<new> template-name fedora-<new>
```
9. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
10. (Optional) Make the new template the global default.
```
[user@dom0 ~]$ qubes-prefs --set default_template fedora-<new>
```
10. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
11. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
Make sure that the template you're uninstalling is the old one, not the new one!
## Summary instructions for Fedora Minimal templates
@ -180,6 +187,7 @@ The same general procedure may be used to upgrade any template based on the stan
[root@fedora-<new>-minimal ~]# dnf clean all
[user@fedora-<new>-minimal ~]# dnf --releasever=<new> --best --allowerasing distro-sync
[user@fedora-<new>-minimal ~]# fstrim -v /
[user@dom0 ~]$ qvm-features fedora-<new>-minimal template-name fedora-<new>
```
(Shut down template by any normal means.)

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

@ -144,7 +144,7 @@ list of packages to be installed):
(which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`
`qubes-core-agent-network-manager` `NetworkManager-wifi`
`network-manager-applet` `wireless-tools` `notification-daemon`
`network-manager-applet` `notification-daemon`
`gnome-keyring` `polkit` `@hardware-support`. If your network devices need
extra packages for the template to work as a network VM, use the `lspci`
command to identify the devices, then run `dnf search firmware` (replace
@ -155,16 +155,18 @@ list of packages to be installed):
`qubes-usb-proxy` to provide USB devices to other Qubes and
`qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [VPN
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md):
qube](https://forum.qubes-os.org/t/19061):
Use the `dnf search "NetworkManager VPN plugin"` command to look up the VPN
packages you need, based on the VPN technology you'll be using, and install
them. Some GNOME related packages may be needed as well. After creation of a
machine based on this template, follow the [VPN
instructions](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
instructions](https://forum.qubes-os.org/t/19061#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
to configure it.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
To manage fedora-39-minimal templates with salt, you may need to install `python3-urllib3` in older versions of the template. (This package is already installed in recent builds: see [discussion](https://github.com/QubesOS/qubes-issues/issues/8806).)
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
are:
@ -192,7 +194,7 @@ are:
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-u2f`: For implementing secure forwarding of U2F messages.
- `qubes-ctap`: For implementing secure forwarding of CTAP messages.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
@ -206,7 +208,7 @@ You may also wish to consider additional packages from the `qubes-core-agent`
suite.
See
[here](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md)
[here](https://forum.qubes-os.org/t/18999)
for further information on customizing `fedora-minimal`.
#### Logging
@ -240,9 +242,9 @@ list of packages to be installed):
- [FirewallVM](/doc/firewall/), such as the template for `sys-firewall`: at
least `qubes-core-agent-networking`, and also `qubes-core-agent-dom0-updates`
if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`
`qubes-core-agent-network-manager`. If your network devices need extra
packages for a network VM, use the `lspci` command to identify the devices,
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`,
`qubes-core-agent-network-manager`, `ntpd` (or other NTP Service).
If your network devices need extra packages for a network VM, use the `lspci` command to identify the devices,
then find the package that provides necessary firmware and install it. If you
need utilities for debugging and analyzing network connections, install the
following packages: `tcpdump` `telnet` `nmap` `ncat`.
@ -254,11 +256,11 @@ list of packages to be installed):
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):
qube](https://forum.qubes-os.org/t/19061):
You may need to install network-manager VPN packages, depending on the VPN
technology you'll be using. After creating a machine based on this template,
follow the [VPN
howto](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
howto](https://forum.qubes-os.org/t/19061#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
to configure it.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
@ -287,7 +289,7 @@ are:
Also, there are packages to provide additional services:
- `qubes-gpg-split`: For implementing split GPG.
- `qubes-u2f`: For implementing secure forwarding of U2F messages.
- `qubes-ctap`: For implementing secure forwarding of CTAP messages.
- `qubes-pdf-converter`: For implementing safe conversion of PDFs.
- `qubes-img-converter`: For implementing safe conversion of images.
- `qubes-snapd-helper`: If you want to use snaps in qubes.
@ -324,7 +326,7 @@ list of packages to be installed):
if you want to use it as the `UpdateVM` (which is normally `sys-firewall`).
- NetVM, such as the template for `sys-net`: `qubes-core-agent-networking`
`qubes-core-agent-network-manager` `NetworkManager-wifi`
`network-manager-applet` `wireless-tools` `notification-daemon`
`network-manager-applet` `notification-daemon`
`gnome-keyring`. If your network devices need extra packages for a network
VM, use the `lspci` command to identify the devices, then find the package
that provides necessary firnware and install it. If you need utilities for
@ -334,11 +336,11 @@ list of packages to be installed):
`qubes-usb-proxy` to provide USB devices to other Qubes and
`qubes-input-proxy-sender` to provide keyboard or mouse input to dom0.
- [VPN
qube](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md):
qube](https://forum.qubes-os.org/t/19061):
You may need to install network-manager VPN packages, depending on the VPN
technology you'll be using. After creating a machine based on this template,
follow the [VPN
howto](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
howto](https://forum.qubes-os.org/t/19061#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager)
to configure it.
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.

9
user/templates/templates.md
View File

@ -273,6 +273,15 @@ new template:
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.
Or in the `System` menu select `Manage templates for qubes`, select
any qubes using the old template and update them to the new template
using the drop down menu.
4. **Change the template for the default-mgmt-dvm** If the old template
was used for management qubes, then you should change the template.
This is an *internal* qube which does not appear by default in the Qube manager.
In the `System` menu select `Manage templates for qubes`, and you will see the *default-mgmt-dvm* qube.
Change the template used for this disposable template to the new template.
## Advanced

16
user/templates/windows/qubes-windows-tools-4-1.md
View File

@ -25,7 +25,21 @@ Qubes Windows Tools (QWT) are a set of programs and drivers that provide integra
- **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`

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

@ -75,11 +75,11 @@ These errors may also occur due to an incompatible Nvidia graphics card. If you
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
```
For more information, look at the [Nvidia Troubleshooting guide](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md#disabling-nouveau).
For more information, look at the [Nvidia Troubleshooting guide](https://forum.qubes-os.org/t/19021#disabling-nouveau).
## Installation freezes at "Setting up Networking"
If you are facing this problem on an Apple computer, check out the [Macbook Troubleshooting guide](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md).
If you are facing this problem on an Apple computer, check out the [Macbook Troubleshooting guide](https://forum.qubes-os.org/t/19020).
If you are installing Qubes 4.0 on an external storage device, you may have forgotten to disable `sys-usb` during the [initial setup](/doc/installation-guide/#initial-setup), which is generally required for that setup to work.
@ -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

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

@ -120,7 +120,7 @@ You can also configure strict reset directly from the Qubes interface by followi
## Broadcom BCM43602 Wi-Fi card causes system freeze
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in [Macbook Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card).
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in [Macbook Troubleshooting](https://forum.qubes-os.org/t/19020#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card).
For other non-Macbook machines, it is advisable to replace the Broadcom BCM43602 with one known to work on Qubes, such as the Atheros AR9462.

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

@ -30,7 +30,7 @@ If you've installed successfully in legacy mode but had to change some kernel pa
## Installation freezes before displaying installer
If you have an Nvidia card, see also [Nvidia Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md#disabling-nouveau).
If you have an Nvidia card, see also [Nvidia Troubleshooting](https://forum.qubes-os.org/t/19021#disabling-nouveau).
### Removing `noexitboot` and `mapbs`