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

Commit changes from #1286 - Update Windows pages

This commit is contained in:
unman 2023-10-30 12:05:27 +00:00
parent 894e023fa2 173054362c
commit d441fdf277
No known key found for this signature in database
GPG Key ID: BB52274595B71262
46 changed files with 945 additions and 1978 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

@ -15,7 +15,7 @@ title: Qubes ISO building
Build Environment
-----------------
Fedora 32 has been successfully used to build Qubes R4.1 with the below steps.
Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below steps.
Other rpm-based operating systems may also work.
Travis-CI uses Ubuntu 18.04 to perform test builds, except it can not test the `./setup` script.
@ -29,13 +29,13 @@ sudo setenforce 0
~~~
In `dom0`, install the Fedora 32 template if you don't already have it.
In `dom0`, install the Fedora 36 (or 37) template if you don't already have it.
~~~
sudo qubes-dom0-update qubes-template-fedora-32
sudo qubes-dom0-update qubes-template-fedora-36
~~~
Create a standalone AppVM from the Fedora 32 template.
Create a standalone AppVM from the Fedora template.
Set private storage to at least 60 GB if you will be building only the default templates; 100 GB or more if you plan on additional.
It's not required, but if you allocate additional CPU cores, the build process can utilize them at some steps such as the kernel build.
Likewise, more memory (up to 16 GB) can help.

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

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

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

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

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

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

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

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

123
developer/general/gsod.md
View File

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

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

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

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

@ -0,0 +1,48 @@
---
layout: doc
title: Qubes OS 4.2.0 release notes
permalink: /doc/releases/4.2/release-notes/
---
_**Please note:** This page is still an unfinished draft in progress. It is being updated as Qubes 4.2 development and testing continues._
## New features and improvements since Qubes 4.1
- Dom0 upgraded to Fedora 37 ([#6982](https://github.com/QubesOS/qubes-issues/issues/6982))
- Xen upgraded to version 4.17
- Default Debian template upgraded to Debian 12
- Default Fedora and Debian templates use Xfce instead of GNOME ([#7784](https://github.com/QubesOS/qubes-issues/issues/7784))
- SELinux support in Fedora templates ([#4239](https://github.com/QubesOS/qubes-issues/issues/4239))
- Several GUI applications rewritten, including:
- Applications Menu (also available as preview in R4.1) ([#6665](https://github.com/QubesOS/qubes-issues/issues/6665)), ([#5677](https://github.com/QubesOS/qubes-issues/issues/5677))
- Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898))
- Create New Qube
- Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985))
- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358))
- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855))
- Optional automatic clipboard clearing ([#3415](https://github.com/QubesOS/qubes-issues/issues/3415))
- Official packages built using Qubes Builder v2 ([#6486](https://github.com/QubesOS/qubes-issues/issues/6486))
- Split GPG and Split SSH management in Qubes Global Settings
- Qrexec services use new qrexec policy format by default (but old format is still supported) ([#8000](https://github.com/QubesOS/qubes-issues/issues/8000))
For a full list, including more detailed descriptions, please see
[here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.2%22+label%3A%22release+notes%22+is%3Aclosed).
## Known issues
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062))
For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes.
## Download
All Qubes ISOs and associated [verification files](/security/verifying-signatures/) are available on the [downloads](/downloads/) page.
## Installation instructions
See the [installation guide](/doc/installation-guide/).
## Upgrading
Please see [how to upgrade to Qubes 4.2](/doc/upgrade/4.2/).

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

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

15
developer/releases/notes.md
View File

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

11
developer/releases/schedules.md
View File

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

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

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

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

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

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

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

4
introduction/contributing.md
View File

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

17
introduction/faq.md
View File

@ -186,10 +186,7 @@ We believe that this is currently the only practically viable approach to implem
### Does Qubes use full disk encryption (FDE)?
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt).
You can even [manually configure your encryption parameters](/doc/custom-install/) if you like!
By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) to encrypt everything except the `/boot` partition.
### What do all these terms mean?
@ -331,6 +328,16 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
If it seems like a feature that we can and should enable, please [let us know](/doc/issue-tracking/)!
### Why do the mailing lists require a Google account?
They don't. This is a common misconception. The mailing lists have never required a Google account. It has always been possible to use them purely via email (see the [mailing lists](/support/#mailing-lists) section for instructions).
A lot of people probably see that the mailing lists use Google Groups and just assume that a Google account must be required, but it's not true. Google Groups is simply used for the infrastructure. Of course, you *can* use the web interface with a Google account, but there are many people in the Qubes community who participate on the mailing lists without one.
### Why do you use Google Groups for the mailing lists?
For the same general reasons as listed in [FAQ: Why do you use GitHub?](/faq/#why-do-you-use-github)
## Users
### Can I watch YouTube videos in qubes?
@ -787,7 +794,7 @@ UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very
Arguably secure boot reliance on UEFI integrity is not the best design.
The relevant binaries (shim.efi, xen.efi, kernel / initramfs) are not signed by the Qubes Team and secure boot has not been tested.
Intel TXT (used in [Anti Evil Maid](/doc/anti-evil-maid/)) at least tries to avoid or limit trust in BIOS.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](http://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
See the Heads project [[1]](https://trmm.net/Heads) [[2]](https://osresearch.net/) for a better-designed non-UEFI-based secure boot scheme with very good support for Qubes.
### What is the canonical way to detect Qubes VM?

307
introduction/issue-tracking.md
View File

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

11
introduction/support.md
View File

@ -512,6 +512,11 @@ on the [news](/news/) page. If you use one of these platforms, you may find it
convenient to follow the Qubes OS Project there as a way of receiving Qubes
news.
## Chat
If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix
bridge: `#qubes:libera.chat`).
## Unofficial venues
If you find another venue on the Internet that is not listed above, it is
@ -522,9 +527,3 @@ moderate it. Please be especially careful in unofficial venues.
should not be taken as a commitment to monitor or moderate the venue. It still
remains unofficial. Also, please make sure someone claiming to be a Qubes team
member really is one. It could be an impostor!)
For example, here are some **unofficial** chat channels we know about that are
maintained by the community:
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
* `#qubes` channel on irc.libera.chat via traditional IRC clients

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

@ -294,11 +294,9 @@ Before we proceed, you must first complete the following prerequisite steps:
2. [Import and authenticate the QMSK.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
After you have completed these two prerequisite steps, the next step is to
obtain the correct RSK. The filename of the RSK for your Qubes OS release is
usually `qubes-release-X-signing-key.asc`, where `X` is the [major version
number](https://semver.org/) of your Qubes release. For example, if you were
installing release `1.2.3`, you would replace `X` with `1`, resulting in
`qubes-release-1-signing-key.asc`. There are several ways to get the RSK for
obtain the correct RSK. The filename pattern for RSKs is
`qubes-release-X-signing-key.asc`, where `X` is either a major or minor Qubes
release number, such as `4` or `4.2`. There are several ways to get the RSK for
your Qubes release.
- If you have access to an existing Qubes installation, the release keys are

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

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

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

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

2
user/advanced-topics/gui-domain.md
View File

@ -147,7 +147,7 @@ qvm-prefs personal guivm dom0
You are now able to delete the GUI domain, for example `sys-gui-gpu`:
```bash
qvm-remove -y sys-gui-gpu
qvm-remove -f sys-gui-gpu
```
#### General issues

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -28,7 +28,8 @@ are available from our [download mirrors](/downloads/#mirrors).
| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported |
| Release 4.0 | 2018-03-28 | 2022-08-04 | Unsupported |
| Release 4.1 | 2022-02-04 | TBA | Supported |
| Release 4.2 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.2%22) |
| Release 4.2 | TBA | TBA | [In testing](https://github.com/QubesOS/qubes-issues/milestone/26) |
| Release 4.3 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/milestone/28) |
### Note on patch releases
@ -53,6 +54,7 @@ The table below shows the OS used for dom0 in each Qubes OS release.
| Release 3.2 | Fedora 23 |
| Release 4.0 | Fedora 25 |
| Release 4.1 | Fedora 32 |
| Release 4.2 | Fedora 37 |
### Note on dom0 and EOL
@ -89,9 +91,10 @@ upstream release on the upstream distribution's website (see [Fedora
EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian
Releases](https://wiki.debian.org/DebianReleases)).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | --------------------------------------------------- | ------ |
| Release 4.1 | 36 | 10 (Buster), 11 (Bullseye) | 16 |
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ------ | ------ |
| Release 4.1 | 37, 38 | 11, 12 | 16 |
| Release 4.2 | 37, 38 | 11, 12 | 17 |
### Note on Debian support
@ -105,23 +108,6 @@ chart that illustrates this. Qubes support ends at the *regular* EOL date,
[Whonix](https://www.whonix.org/wiki/Qubes) templates are supported by our
partner, the [Whonix Project](https://www.whonix.org/). The Whonix Project has
set its own support policy for Whonix templates in Qubes.
This policy requires Whonix template users to stay reasonably close to the
cutting edge by upgrading to new stable releases of Qubes OS and Whonix
templates within a month of their respective releases. To be precise:
* One month after a new stable version of Qubes OS is released, Whonix
templates will no longer be supported on any older release of Qubes OS. This
means that users who wish to continue using Whonix templates on Qubes must
always upgrade to the latest stable Qubes OS release within one month of its
release.
* One month after new stable versions of Whonix templates are released, older
releases of Whonix templates will no longer be supported. This means that
users who wish to continue using Whonix templates on Qubes must always
upgrade to the latest stable Whonix template releases within one month of
their release.
We aim to announce both types of events one month in advance in order to remind
users to upgrade.
set its own support policy for Whonix templates in Qubes. Please see the
[Qubes-Whonix version support policy](https://www.whonix.org/wiki/About#Qubes_Hosts)
for details.

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

@ -23,6 +23,9 @@ How to test upcoming Qubes OS releases:
* Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
* Test the latest release candidate (RC), if one is currently available.
* Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn
more](https://forum.qubes-os.org/t/16929) and [track their
status](https://github.com/fepitre/updates-status-iso/issues).)
* (No support) Experiment with devel alpha ISOs found from time to time at
[Qubes OpenQA](https://openqa.qubes-os.org/).
@ -78,14 +81,12 @@ How to test [templates](/doc/templates/):
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>`
option. Example commands:
```
sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing
sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing
qvm-template --enablerepo=qubes-templates-itl-testing list --available
qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
```
To enable or disable any of these repos permanently, change the corresponding
`enabled` value to `1` in `/etc/yum.repos.d/qubes-templates.repo`.
To enable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/qubes/repo-templates`.
To disable any of these repos permanently, change the corresponding `enabled` value to `0`.
## Providing feedback

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

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

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

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

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

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

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

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

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

@ -317,7 +317,7 @@ her setup looks like this:
to these generally doesn't allow spending or withdrawing any money. So, even
the worst case scenario here wouldn't be catastrophic, unlike with her bank
and brokerage accounts. Third, she's not too worried about any of her credit
card company websites being used to attach each other or her qube (As long as
card company websites being used to attack each other or her qube. (As long as
it's contained to a single qube, she's fine with that level of risk.) Last,
but not least: She has way too many credit cards! While Carol is very frugal,
she likes to collect the sign-up bonuses that are offered for opening new
@ -526,7 +526,7 @@ lessons from our case studies:
able to actually *use* your computer efficiently to do the things you need to
do. For example, if you immediately try to jump into doing everything in
[disposables](/doc/how-to-use-disposables/) and find yourself constantly
losing working (e.g., because you forget to transfer it out before the
losing work (e.g., because you forget to transfer it out before the
disposable self-destructs), then that's a big problem! Your extra
self-imposed security measures are interfering with the very thing they're
designed to protect. At times like these, take a deep breath and remember

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

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

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

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

5
user/reference/glossary.md
View File

@ -141,11 +141,12 @@ still be called "qubes."
* **Important:** The term "qube" is a common noun and should follow the
capitalization rules of common nouns. For example, "I have three qubes" is
correct," while "I have three Qubes" is incorrect.
correct, while "I have three Qubes" is incorrect.
* Note that starting a sentence with the plural of "qube" (i.e., "Qubes...")
can be ambiguous, since it may not be clear whether the referent is a
plurality of qubes or [Qubes OS](#qubes-os).
plurality of qubes or [Qubes OS](#qubes-os). You may wish to rephrase
sentences in order to avoid this ambiguity.
* Example usage: "In Qubes OS, you do your banking in your 'banking' qube and
your web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube

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

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

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

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

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

@ -25,9 +25,13 @@ templates, along with some examples of common use cases.
## Important
1. [The minimal templates are intended only for advanced
users.](https://forum.qubes-os.org/t/9717/15) If you encounter problems with
the minimal templates, we recommend that you use their standard template
counterparts instead.
users.](https://forum.qubes-os.org/t/9717/15) Most things will *not* work
out-of-the-box, and you *will* have to fix them yourself. If you are not
prepared to do a lot of reading, searching, learning, and troubleshooting,
then you should instead stick to the standard templates, which are perfectly
suitable for the vast majority of users. In particular, if you are new to
Qubes, you should not attempt to use minimal templates until you have gained
more experience.
2. If something works with a standard template but not the minimal version,
this is most likely due to user error (e.g., a missing package or
@ -259,6 +263,9 @@ list of packages to be installed):
- `default-mgmt-dvm`: requires `qubes-core-agent-passwordless-root` and
`qubes-mgmt-salt-vm-connector`.
- [Yubikey](/doc/yubikey/): You may need to install `xserver-xorg-input-libinput` for 2FA responses to work in web browsers like Firefox.
- Thumbnails (e.g., file previews in Nautilus): `libgdk-pixbuf2.0-bin` (images),
`ffmpegthumbnailer` (videos). (Try `apt search thumbnailer` for other file
types.)
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be
needed to make the customized minimal template work properly. These packages

92
user/templates/templates.md
View File

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

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

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

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

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