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

Merge branch 'main' into yubikey-nk-update

This commit is contained in:
UndeadDevel 2024-04-18 00:47:38 +02:00 committed by GitHub
parent f8326123ca be6a36f7ea
commit d4e4388c5f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
23 changed files with 715 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

88
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.
@ -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

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

@ -42,9 +42,17 @@ The new Qubes OS Policy Editor tool:
## 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

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.

40
introduction/issue-tracking.md
View File

@ -83,7 +83,27 @@ A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects t
### 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
@ -193,3 +213,21 @@ In order to assist with this, we have a label called [backport pending](https://
### 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.

7
introduction/support.md
View File

@ -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

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)

13
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

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.

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

@ -57,8 +57,8 @@ It is the responsibility of each distribution to clearly notify its users in adv
| Qubes OS | Fedora | Debian |
| ----------- | ------ | ------ |
| Release 4.1 | 38 | 11, 12 |
| Release 4.2 | 38 | 12 |
| Release 4.1 | 38, 39 | 11, 12 |
| Release 4.2 | 38, 39 | 12 |
### Note on Debian support

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

@ -23,49 +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.
### NitroPad X230
[![Photo of the NitroPad X230](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) is a laptop based on the ThinkPad X230. It is certified for Qubes OS 4.X.
### 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.
### 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.
### NovaCustom NV41 Series
[![Photo of the NovaCustom NV41 Series](/attachment/site/novacustom-nv41-series.png)](https://novacustom.com/product/nv41-series/)
The [NovaCustom NV41 Series](https://novacustom.com/product/nv41-series/) is a 14-inch custom laptop. It is certified for Qubes OS 4.X.
### 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.
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.
### Star Labs StarBook
[![Photo of the Star Labs StarBook](/attachment/site/starlabs-starbook.png)](https://starlabs.systems/pages/starbook)
The [Star Labs StarBook](https://starlabs.systems/pages/starbook) is a 14-inch laptop. It is certified for Qubes OS 4.X.
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.
### 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

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.

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

@ -66,12 +66,16 @@ Normally Qubes doesn't let the user stop a NetVM if there are other qubes runnin
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 (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
---------------------
@ -304,12 +308,12 @@ nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr
> 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.
> 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
```
In this example, we can see 7 packets in the forward rule, and 3 packets in the dnat rule:
@ -331,7 +335,7 @@ chain custom-dnat-qubeDEST {
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/rc.local` so they get set on sys-net start-up:
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

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.

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

6
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
@ -165,6 +165,8 @@ list of packages to be installed):
- `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:
@ -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

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