Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-22 20:51:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

Wrap text and miscellaneous cleanup

Browse Source
This commit is contained in:
Andrew David Wong 2021-06-18 06:25:06 -07:00
parent e451f92cde
commit 07c130df00
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
21 changed files with 1845 additions and 1022 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

456
developer/general/doc-guidelines.md
View File

@ -10,60 +10,91 @@ ref: 30
title: Documentation Guidelines
---
All Qubes OS documentation pages are stored as plain text files in the
dedicated [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.
All Qubes OS documentation pages are stored as plain text files in the dedicated [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 community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
If you notice a problem or some way it can be improved, please [edit the documentation](#how-to-contribute)!
The documentation is a community effort. Volunteers work hard trying to keep
everything accurate and comprehensive. If you notice a problem or some way it
can be improved, please [edit the documentation](#how-to-contribute)!
## Security
*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)*
All pull requests (PRs) against [qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be merged, except in the case of [external documentation](/doc/#external-documentation) (see [#4693](https://github.com/QubesOS/qubes-issues/issues/4693)).
This process is designed to ensure that contributed text is accurate and non-malicious.
This process is a best effort that should provide a reasonable degree of assurance, but it is not foolproof.
For example, all text characters are checked for ANSI escape sequences.
However, binaries, such as images, are simply checked to ensure they appear or function the way they should when the website is rendered.
They are not further analyzed in an attempt to determine whether they are malicious.
All pull requests (PRs) against
[qubes-doc](https://github.com/QubesOS/qubes-doc) must pass review prior to be
merged, except in the case of [external
documentation](/doc/#external-documentation) (see
[#4693](https://github.com/QubesOS/qubes-issues/issues/4693)). This process is
designed to ensure that contributed text is accurate and non-malicious. This
process is a best effort that should provide a reasonable degree of assurance,
but it is not foolproof. For example, all text characters are checked for ANSI
escape sequences. However, binaries, such as images, are simply checked to
ensure they appear or function the way they should when the website is
rendered. They are not further analyzed in an attempt to determine whether they
are malicious.
Once a pull request passes review, the reviewer should add a signed comment stating, "Passed review as of `<latest_commit>`" (or similar).
The documentation maintainer then verifies that the pull request is mechanically sound (no merge conflicts, broken links, ANSI escapes, etc.).
If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote.
In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
Once a pull request passes review, the reviewer should add a signed comment
stating, "Passed review as of `<latest_commit>`" (or similar). The
documentation maintainer then verifies that the pull request is mechanically
sound (no merge conflicts, broken links, ANSI escapes, etc.). If so, the
documentation maintainer then merges the pull request, adds a PGP-signed tag to
the latest commit (usually the merge commit), then pushes to the remote. In
cases in which another reviewer is not required, the documentation maintainer
may review the pull request (in which case no signed comment is necessary,
since it would be redundant with the signed tag).
## Questions, problems, and improvements
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list](/support/).
If you see that something in the documentation should be fixed or improved, please [contribute](#how-to-contribute) the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines](/doc/reporting-bugs/).
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
If you have a question about something you read in the documentation, please
send it to the appropriate [mailing list](/support/). If you see that something
in the documentation should be fixed or improved, please
[contribute](#how-to-contribute) the change yourself. To report an issue with
the documentation, please follow our standard [issue reporting
guidelines](/doc/reporting-bugs/). (If you report an issue with the
documentation, you will likely be asked to address it, unless there is a clear
indication in your report that you are not willing or able to do so.)
## How to contribute
Editing the documentation is easy, so if you see that a change should be made, please contribute it!
Editing the documentation is easy, so if you see that a change should be made,
please contribute it!
A few notes before we get started:
* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
This allows us to maintain quality control and protect our users.
* We don't want you to spend time and effort on a contribution that we can't accept.
If your contribution would take a lot of time, please [file an issue](/doc/reporting-bugs/) for it first so that we can make sure we're on the same page before significant works begins.
* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
In this case, you can still submit it by following the instructions below.
Just make a note in your pull request (PR) that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes.
* Since Qubes is a security-oriented project, every documentation change will
be reviewed before it's accepted. This allows us to maintain quality control
and protect our users.
* We don't want you to spend time and effort on a contribution that we can't
accept. If your contribution would take a lot of time, please [file an
issue](/doc/reporting-bugs/) for it first so that we can make sure we're on
the same page before significant works begins.
* Alternatively, you may already have written content that doesn't conform to
these guidelines, but you'd be willing to modify it so that it does. In this
case, you can still submit it by following the instructions below. Just make
a note in your pull request (PR) that you're aware of the changes that need
to be made and that you're just asking for the content to be reviewed before
you spend time making those changes.
As mentioned above, we keep all the documentation in a dedicated [Git repository](https://github.com/QubesOS/qubes-doc) hosted on [GitHub](https://github.com/).
Thanks to GitHub's interface, you can edit the documentation even if you don't know Git at all!
The only thing you need is a GitHub account, which is free.
As mentioned above, we keep all the documentation in a dedicated [Git
repository](https://github.com/QubesOS/qubes-doc) hosted on
[GitHub](https://github.com/). Thanks to GitHub's interface, you can edit the
documentation even if you don't know Git at all! The only thing you need is a
GitHub account, which is free.
(**Note:** If you're already familiar with GitHub or wish to work from the command line, you can skip the rest of this section.
All you need to do to contribute is to [fork and clone](https://guides.github.com/activities/forking/) the [qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests/).)
(**Note:** If you're already familiar with GitHub or wish to work from the
command line, you can skip the rest of this section. All you need to do to
contribute is to [fork and
clone](https://guides.github.com/activities/forking/) the
[qubes-doc](https://github.com/QubesOS/qubes-doc) repo, make your changes, then
[submit a pull
request](https://help.github.com/articles/using-pull-requests/).)
Ok, let's start.
Every documentation page has an "Edit this page" button.
It may be on the side (in the desktop layout):
Ok, let's start. Every documentation page has an "Edit this page" button. It
may be on the side (in the desktop layout):
[![edit-button-desktop](/attachment/doc/03-button2.png)](/attachment/doc/03-button2.png)
@ -71,129 +102,191 @@ Or at the bottom (in the mobile layout):
[![edit-button-mobile](/attachment/doc/02-button1.png)](/attachment/doc/02-button1.png)
When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in).
You can also create an account from here.
When you click on it, you'll be prompted for your GitHub username and password
(if you aren't already logged in). You can also create an account from here.
[![github-sign-in](/attachment/doc/04-sign-in.png)](/attachment/doc/04-sign-in.png)
If this is your first contribution to the documentation, you need to "fork" the repository (make your own copy). It's easy --- just click the big green button on the next page.
This step is only needed the first time you make a contribution.
If this is your first contribution to the documentation, you need to "fork" the
repository (make your own copy). It's easy --- just click the big green button
on the next page. This step is only needed the first time you make a
contribution.
[![fork](/attachment/doc/05-fork.png)](/attachment/doc/05-fork.png)
Now you can make your modifications.
You can also preview the changes to see how they'll be formatted by clicking the "Preview changes" tab.
If you want to add images, please see [How to add images](#how-to-add-images).
If you're making formatting changes, please [render the site locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify that everything looks correct before submitting any changes.
Now you can make your modifications. You can also preview the changes to see
how they'll be formatted by clicking the "Preview changes" tab. If you want to
add images, please see [How to add images](#how-to-add-images). If you're
making formatting changes, please [render the site
locally](https://github.com/QubesOS/qubesos.github.io#instructions) to verify
that everything looks correct before submitting any changes.
[![edit](/attachment/doc/06-edit.png)](/attachment/doc/06-edit.png)
Once you're finished, describe your changes at the bottom and click "Propose file change".
Once you're finished, describe your changes at the bottom and click "Propose
file change".
[![commit](/attachment/doc/07-commit-msg.png)](/attachment/doc/07-commit-msg.png)
After that, you'll see exactly what modifications you've made.
At this stage, those changes are still in your own copy of the documentation ("fork").
If everything looks good, send those changes to us by pressing the "Create pull request" button.
After that, you'll see exactly what modifications you've made. At this stage,
those changes are still in your own copy of the documentation ("fork"). If
everything looks good, send those changes to us by pressing the "Create pull
request" button.
[![pull-request](/attachment/doc/08-review-changes.png)](/attachment/doc/08-review-changes.png)
You will be able to adjust the pull request message and title there.
In most cases, the defaults are ok, so you can just confirm by pressing the "Create pull request" button again.
You will be able to adjust the pull request message and title there. In most
cases, the defaults are ok, so you can just confirm by pressing the "Create
pull request" button again.
[![pull-request-confirm](/attachment/doc/09-create-pull-request.png)](/attachment/doc/09-create-pull-request.png)
If any of your changes should be reflected in the [documentation index (a.k.a. table of contents)](/doc/) --- for example, if you're adding a new page, changing the title of an existing page, or removing a page --- please see [How to edit the documentation index](#how-to-edit-the-documentation-index).
If any of your changes should be reflected in the [documentation index (a.k.a.
table of contents)](/doc/) --- for example, if you're adding a new page,
changing the title of an existing page, or removing a page --- please see [How
to edit the documentation index](#how-to-edit-the-documentation-index).
That's all!
We will review your changes.
If everything looks good, we'll pull them into the official documentation.
Otherwise, we may have some questions for you, which we'll post in a comment on your pull request.
(GitHub will automatically notify you if we do.)
If, for some reason, we can't accept your pull request, we'll post a comment explaining why we can't.
That's all! We will review your changes. If everything looks good, we'll pull
them into the official documentation. Otherwise, we may have some questions for
you, which we'll post in a comment on your pull request. (GitHub will
automatically notify you if we do.) If, for some reason, we can't accept your
pull request, we'll post a comment explaining why we can't.
[![done](/attachment/doc/10-done.png)](/attachment/doc/10-done.png)
## How to edit the documentation index
The source file for the [documentation index (a.k.a. table of contents)](/doc/) lives here:
The source file for the [documentation index (a.k.a. table of contents)](/doc/)
lives here:
<https://github.com/QubesOS/qubesos.github.io/blob/master/_data/index.yml>
Editing this file will change what appears on the documentation index.
If your pull request (PR) adds, removes, or edits anything that should be reflected in the documentation index, please make sure you also submit an associated pull request against this file.
Editing this file will change what appears on the documentation index. If your
pull request (PR) adds, removes, or edits anything that should be reflected in
the documentation index, please make sure you also submit an associated pull
request against this file.
## How to add images
To add an image to a page, use the following syntax in the main document.
This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself.
To add an image to a page, use the following syntax in the main document. This
will make the image a hyperlink to the image file, allowing the reader to click
on the image in order to view the image by itself.
```
[![Image Title](/attachment/doc/image-filename.png)](/attachment/doc/image-filename.png)
[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png)
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
This is the only permitted way to include images.
Do not link to images on other websites.
Then, submit your image(s) in a separate pull request to the
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository
using the same path and filename. This is the only permitted way to include
images. Do not link to images on other websites.
## 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](#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the "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](#how-to-edit-the-documentation-index)) to add
and update Qubes Community links in the "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 go through a review process to ensure accuracy before being merged (see [security](#security)), 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 go through a review process to ensure
accuracy before being merged (see [security](#security)), 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.
### Version-specific documentation
*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential changes to this policy.*
*See [#5308](https://github.com/QubesOS/qubes-issues/issues/5308) for potential
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 version 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 version 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 versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions:
In cases where a documentation page covers functionality that differs
considerably between Qubes OS versions, the page should be subdivided into
clearly-labeled sections that cover the different functionality in different
versions:
#### Incorrect Example
@ -256,42 +349,69 @@ 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 version has several benefits:
Subdividing the page into clearly-labeled sections for each version has several
benefits:
* It preserves good content for older (but still supported) versions.
Many documentation contributors are also people who prefer to use the latest version.
Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
This is somewhat understandable.
Since they only use the latest version, they may be focused on their own experience, and they may even regard the older version 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 version.
In many cases, these users value the stability and reliability of the older, supported version.
With the older, supported version, 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 version 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 version.
* 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 version-specific sections is not a problem, since no reader has to read the same thing twice.
Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version 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 versions.
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 versions.
* It preserves good content for older (but still supported) versions. Many
documentation contributors are also people who prefer to use the latest
version. Many of them are tempted to *replace* existing content that applies
to an older, supported version with content that applies only to the latest
version. This is somewhat understandable. Since they only use the latest
version, they may be focused on their own experience, and they may even
regard the older version 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 version. In many
cases, these users value the stability and reliability of the older,
supported version. With the older, supported version, 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
version 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 version.
* 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 version-specific sections is not a problem, since no reader has to read
the same thing twice. Moreover, as one version gets updated, it's likely that
the documentation for that version will also be updated. Therefore, content
that is initially duplicated between version-specific sections will not
necessarily stay that way, and this is a good thing: We want the
documentation for a version that *doesn't* change to stay the same, and we
want the documentation for a version 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 versions.
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
versions.
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions 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-version-specific content.
Good general content that was submitted only to one branch would effectively disappear once that version 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 version, 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 versions 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-version-specific content. Good general content
that was submitted only to one branch would effectively disappear once that
version 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
version, 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 version-specific documentation in Qubes, see [here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
For further discussion about version-specific documentation in Qubes, see
[here](https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion).
## Style guidelines
* 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.
* Syntactically distinguish variables in commands.
For example, this is ambiguous:
@ -308,30 +428,46 @@ For further discussion about version-specific documentation in Qubes, see [here]
## Markdown conventions
All the documentation is written in Markdown for maximum accessibility.
When making contributions, please try to observe the following style conventions:
All the documentation is written in Markdown for maximum accessibility. When
making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs.
* 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.
* Link only to images in [qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see [instructions above](#how-to-add-images)).
Do not link to images on other websites.
* In order to enable offline browsing and automatic onion redirection, always use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`.
Examples of exceptions:
* The signed plain text portions of [QSBs](/security/bulletins/) and [Canaries](/security/canaries/)
* URLs that appear inside code blocks (e.g., in comments and document templates)
* 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.
* Link only to images in
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) (see
[instructions above](#how-to-add-images)). Do not link to images on other
websites.
* In order to enable offline browsing and automatic onion redirection, always
use relative (rather than absolute) links, e.g., `/doc/doc-guidelines/`
instead of `https://www.qubes-os.org/doc/doc-guidelines/`. Examples of
exceptions:
* The signed plain text portions of [QSBs](/security/bulletins/) and
[Canaries](/security/canaries/)
* URLs that appear inside code blocks (e.g., in comments and document
templates)
* Files like `README.md` and `CONTRIBUTING.md`
* Hard wrap Markdown lines at 80 characters, unless the line can't be broken (e.g., code or a URL).
* If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Hard wrap Markdown lines at 80 characters, unless the line can't be broken
(e.g., code or a URL).
* If appropriate, make numerals in numbered lists match between Markdown
source and HTML output.
* Rationale: In the event that a user is required to read the Markdown
source directly, this will make it easier to follow, e.g., numbered steps
in a set of instructions.
* Use hanging indentations
where appropriate.
* Do not use `h1` headings (single `#` or `======` underline). These are automatically generated from the `title:` line in the YAML frontmatter.
* Do not use `h1` headings (single `#` or `======` underline). These are
automatically generated from the `title:` line in the YAML frontmatter.
* Use Atx-style headings: , `##h 2`, `### h3`, etc.
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When writing code blocks, use [syntax
highlighting](https://github.github.com/gfm/#info-string) where
[possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers)
and use `[...]` for anything omitted.
* 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:
@ -342,8 +478,9 @@ When making contributions, please try to observe the following style conventions
```
~~~
* 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:
@ -363,10 +500,11 @@ When making contributions, please try to observe the following style conventions
* Use non-reference-style links like `[website](https://example.com/)`.
Do *not* use reference links like `[website][example]`, `[website][]` or `[website]`.
([This](https://daringfireball.net/projects/markdown/) is a great source for learning about Markdown.)
([This](https://daringfireball.net/projects/markdown/) is a great source for
learning about Markdown.)
## Git conventions
Please try to write good commit messages, according to the
[instructions in our coding style guidelines](/doc/coding-style/#commit-message-guidelines).
Please try to write good commit messages, according to the [instructions in our
coding style guidelines](/doc/coding-style/#commit-message-guidelines).

92
introduction/code-of-conduct.md
View File

@ -8,19 +8,35 @@ title: Code of Conduct
## Introduction
This Code of Conduct is a collaborative, evolving document that attempts to transparently set out a public set of standards regarding appropriate conduct in the Qubes OS Project.
It is *not* intended to be a statement or endorsement, whether implicit or explicit, of any particular political or philosophical attitude, belief, or way of living.
Rather, it is an attempt to find a reasonable middle ground among the inevitable disagreements regarding free expression that arise in a large, diverse community of people from around the world.
It is intended to be a practical means of serving the best interests of our users, contributors, and the project itself.
We welcome you to view the [history of changes](https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md) to this document and the [discussion](https://github.com/QubesOS/qubes-issues/issues/2163) leading to its creation.
This Code of Conduct is a collaborative, evolving document that attempts to
transparently set out a public set of standards regarding appropriate conduct
in the Qubes OS Project. It is *not* intended to be a statement or endorsement,
whether implicit or explicit, of any particular political or philosophical
attitude, belief, or way of living. Rather, it is an attempt to find a
reasonable middle ground among the inevitable disagreements regarding free
expression that arise in a large, diverse community of people from around the
world. It is intended to be a practical means of serving the best interests of
our users, contributors, and the project itself. We welcome you to view the
[history of
changes](https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md)
to this document and the
[discussion](https://github.com/QubesOS/qubes-issues/issues/2163) leading to
its creation.
## Our Pledge
The Qubes OS project creates a reasonably secure OS. In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, sexual identity and orientation, or other characteristic.
The Qubes OS project creates a reasonably secure OS. In the interest of
fostering an open and welcoming environment, we as contributors and maintainers
pledge to make participation in our project and our community a harassment-free
experience for everyone, regardless of age, body size, disability, ethnicity,
gender identity and expression, level of experience, nationality, personal
appearance, race, religion, sexual identity and orientation, or other
characteristic.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
Examples of behavior that contributes to creating a positive environment
include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
@ -30,36 +46,72 @@ Examples of behavior that contributes to creating a positive environment include
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or advances
- The use of sexualized language or imagery and unwelcome sexual attention or
advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Reinforcing stereotypical models for illustration of non-technical users (e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of Conduct](http://citizencodeofconduct.org/)
- Publishing others' private information, such as a physical or electronic address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
- Reinforcing stereotypical models for illustration of non-technical users
(e.g. our mothers/grandmothers, etc.)
- Public or private harassment, as defined by the [Citizen Code of
Conduct](http://citizencodeofconduct.org/)
- Publishing others' private information, such as a physical or electronic
address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
(Please also see our [discussion guidelines](/support/#discussion-guidelines).)
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. This action can include removing, editing, or rejecting comments, commits, code, wiki edits, issues, and other contributions, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior. This action can include
removing, editing, or rejecting comments, commits, code, wiki edits, issues,
and other contributions, or to ban temporarily or permanently any contributor
for other behaviors that they deem inappropriate, threatening, offensive, or
harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an
appointed representative at an online or offline event. Representation of a
project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project CoC team at `mods@qubes-os.org`. The project CoC team is the [Marek Marczykowski-Górecki](/team/#marek-marczykowski-g%C3%B3recki), [Andrew David Wong](/team/#andrew-david-wong), and [Michael Carbone](/team/#michael-carbone). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident, and will ensure reporter, reported and all others impacted are regularly updated through the process. Further details of specific enforcement policies may be posted separately.
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project CoC team at `mods@qubes-os.org`. The project
CoC team is the [Marek
Marczykowski-Górecki](/team/#marek-marczykowski-g%C3%B3recki), [Andrew David
Wong](/team/#andrew-david-wong), and [Michael Carbone](/team/#michael-carbone).
All complaints will be reviewed and investigated and will result in a response
that is deemed necessary and appropriate to the circumstances. The project team
is obligated to maintain confidentiality with regard to the reporter of an
incident, and will ensure reporter, reported and all others impacted are
regularly updated through the process. Further details of specific enforcement
policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## A Note on Trust
Expect all contributions to be reviewed with some amount of healthy adversarial skepticism, regardless of your perceived standing in the community.
This is a security project, and allowing ourselves to get complacent while reviewing code simply because it comes from a well-known party would not be in the best interest of the project.
Please try not to get offended if you perceive your contributions as being met with distrust -- we are most definitely thankful and appreciative of your efforts, but must also remain vigilant in order to ensure continued quality and safeguard against potential sabotage.
Expect all contributions to be reviewed with some amount of healthy adversarial
skepticism, regardless of your perceived standing in the community. This is a
security project, and allowing ourselves to get complacent while reviewing code
simply because it comes from a well-known party would not be in the best
interest of the project. Please try not to get offended if you perceive your
contributions as being met with distrust -- we are most definitely thankful and
appreciative of your efforts, but must also remain vigilant in order to ensure
continued quality and safeguard against potential sabotage.
## Attribution
The initial published version of this Code of Conduct was adapted from the [Contributor Covenant, version 1.4](https://contributor-covenant.org/version/1/4) and the [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html).
The initial published version of this Code of Conduct was adapted from the
[Contributor Covenant, version
1.4](https://contributor-covenant.org/version/1/4) and the [Rust Code of
Conduct](https://www.rust-lang.org/en-US/conduct.html).

25
introduction/contributing.md
View File

@ -15,33 +15,36 @@ ways in which you can help:
* Audit the [source code](/doc/source-code/)
* [Report security issues](/security/)
* [Send patches](/doc/source-code/#how-to-send-patches) to fix bugs or implement features
* [Send patches](/doc/source-code/#how-to-send-patches) to fix bugs or
implement features
* [Contribute packages](/doc/package-contributions)
* [Report bugs](/doc/reporting-bugs/)
* [Test new releases and updates](/doc/testing/)
* Submit [HCL reports](/doc/hcl/) for your hardware
* Record [video tours](/video-tours/)
* Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes, installer themes, wallpapers, etc.)
* Create [artwork](https://github.com/QubesOS/qubes-artwork) (plymouth themes,
installer themes, wallpapers, etc.)
* [Write and edit the documentation](/doc/doc-guidelines)
* [Donate](/donate/) to the project
* If you represent an organization, become a [Qubes partner](/partners/)
* Add a [Qubes download mirror](/downloads/mirrors/)
* Answer questions and discuss Qubes on the [mailing lists](/support/) and [forum](/support/#forum)
* Answer questions and discuss Qubes on the [mailing lists](/support/) and
[forum](/support/#forum)
* Engage with us on social media:
* Follow us on [Twitter](https://twitter.com/QubesOS)
* Join us on [Reddit](https://www.reddit.com/r/Qubes/)
* Like us on [Facebook](https://www.facebook.com/QubesOS)
* Connect with us on [LinkedIn](https://www.linkedin.com/company/qubes-os/)
* And last but not least, tell your friends and colleagues about how Qubes
can help them secure their digital lives!
* And last but not least, tell your friends and colleagues about how Qubes can
help them secure their digital lives!
Contributing Code
-----------------
If you're interested in contributing code, the best starting point is to have a
look at our [GitHub issues](https://github.com/QubesOS/qubes-issues/issues) to see which tasks are the most urgent. You can
filter issues depending on your interest and experience. For example, here are
some common issue labels:
look at our [GitHub issues](https://github.com/QubesOS/qubes-issues/issues) to
see which tasks are the most urgent. You can filter issues depending on your
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)
@ -52,7 +55,7 @@ some common issue labels:
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,
preferably via the [qubes-devel](/support/#qubes-devel) mailing list. Once we've worked out the
details, we'll add you to our [Community-Developed Feature Tracker](/qubes-issues/). We'll then
be grateful to [receive your patch](/doc/source-code/#how-to-send-patches).
preferably via the [qubes-devel](/support/#qubes-devel) mailing list. Once
we've worked out the details, we'll be grateful to [receive your
patch](/doc/source-code/#how-to-send-patches).

83
introduction/privacy.md
View File

@ -9,17 +9,41 @@ redirect_from:
title: Privacy Policy
---
The short version is that we try to respect your privacy as much as possible. We absolutely do not sell any user data. In fact, we go out of our way to help you keep your data private from everyone, including us. For example, from the moment you [install Qubes OS](/doc/installation-guide/), we offer to set up [Whonix](https://www.whonix.org/) so that all of your updates are routed through [Tor](https://www.torproject.org/).
The short version is that we try to respect your privacy as much as possible.
We absolutely do not sell any user data. In fact, we go out of our way to help
you keep your data private from everyone, including us. For example, from the
moment you [install Qubes OS](/doc/installation-guide/), we offer to set up
[Whonix](https://www.whonix.org/) so that all of your updates are routed
through [Tor](https://www.torproject.org/).
## Website
For the legally-required boilerplate, see [Website Privacy Policy](/website-privacy-policy/).
For the legally-required boilerplate, see [Website Privacy
Policy](/website-privacy-policy/).
This is just a static website generated with Jekyll and hosted from GitHub Pages. We try to use as little JavaScript as possible. We host all resources locally (no third-party CDNs) so that you only have to connect to one domain. This site should be easy to browse using Tor Browser and with scripts blocked. We also have an [onion service](http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/) (access is not logged). We even go out of our way to make it easy to download [this website's git repo](https://github.com/QubesOS/qubesos.github.io), including all the website source code, so that you can host this entire site from your own local machine offline. Better yet, we've specifically written all of the [documentation](/doc/) in Markdown so that the plain text can be enjoyed from the comfort of your terminal. Here's the [repo](https://github.com/QubesOS/qubes-doc). (By the way, Git tags on our repos are PGP-signed so you can [verify](/doc/verifying-signatures) the authenticity of the content.) Obviously, we don't use any ads or trackers, but this is still a public website, so man-in-the-middle attacks and such are always a possibility. Please be careful. See [FAQ: Should I trust this website?](/faq/#should-i-trust-this-website)
This is just a static website generated with Jekyll and hosted from GitHub
Pages. We try to use as little JavaScript as possible. We host all resources
locally (no third-party CDNs) so that you only have to connect to one domain.
This site should be easy to browse using Tor Browser and with scripts blocked.
We also have an [onion
service](http://qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion/)
(access is not logged). We even go out of our way to make it easy to download
[this website's git repo](https://github.com/QubesOS/qubesos.github.io),
including all the website source code, so that you can host this entire site
from your own local machine offline. Better yet, we've specifically written all
of the [documentation](/doc/) in Markdown so that the plain text can be enjoyed
from the comfort of your terminal. Here's the
[repo](https://github.com/QubesOS/qubes-doc). (By the way, Git tags on our
repos are PGP-signed so you can [verify](/doc/verifying-signatures) the
authenticity of the content.) Obviously, we don't use any ads or trackers, but
this is still a public website, so man-in-the-middle attacks and such are
always a possibility. Please be careful. See [FAQ: Should I trust this
website?](/faq/#should-i-trust-this-website)
## Update Servers & Repositories
We provide repositories at <https://yum.qubes-os.org> and <https://deb.qubes-os.org>.
We provide repositories at <https://yum.qubes-os.org> and
<https://deb.qubes-os.org>.
We collect the following types of data:
@ -27,36 +51,47 @@ We collect the following types of data:
- The number of requests from each IPv4 address
- Standard server access and error logs
We collect this data solely for the purpose of generating [Qubes userbase statistics](/statistics/).
The data is retained for up to two months so that we can re-calculate the previous month's statistics in case anything goes wrong.
After that, the data is permanently and securely destroyed.
We never sell the data to anyone or share it with any third party.
We collect this data solely for the purpose of generating [Qubes userbase
statistics](/statistics/). The data is retained for up to two months so that we
can re-calculate the previous month's statistics in case anything goes wrong.
After that, the data is permanently and securely destroyed. We never sell the
data to anyone or share it with any third party.
If you would like to hide your IP address from us, we strongly encourage it and are happy to help you do so!
Simply choose the Whonix option to route all of your updates over Tor [when installing Qubes OS](/doc/installation-guide/).
If you would like to hide your IP address from us, we strongly encourage it and
are happy to help you do so! Simply choose the Whonix option to route all of
your updates over Tor [when installing Qubes OS](/doc/installation-guide/).
## Onion Services
We provide an [onion service](http://www.qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion) for the website and onion service mirrors of the repositories.
Access to these servers is not logged.
We provide an [onion
service](http://www.qubesosfasa4zl44o4tws22di6kepyzfeqv3tg4e3ztknltfxqrymdad.onion)
for the website and onion service mirrors of the repositories. Access to these
servers is not logged.
## Download Mirrors
There are also other third-party [download mirrors](/downloads/#mirrors) hosted by volunteers.
We have no control over or access to data collected by these mirrors.
There are also other third-party [download mirrors](/downloads/#mirrors) hosted
by volunteers. We have no control over or access to data collected by these
mirrors.
## Qubes OS
We have specifically designed Qubes OS so that it is not possible to collect any data directly from Qubes OS installations.
In other words, Qubes OS does not have the ability to "phone home" and is intentionally architected to forbid that from happening.
This is mainly because we have ensured that dom0 has no network access.
We have specifically designed Qubes OS so that it is not possible to collect
any data directly from Qubes OS installations. In other words, Qubes OS does
not have the ability to "phone home" and is intentionally architected to forbid
that from happening. This is mainly because we have ensured that dom0 has no
network access.
We don't want the ability collect any data directly from Qubes OS installations, because if anyone has that power, then the system is not secure.
We all use Qubes OS ourselves as a daily driver for our work and personal lives, so our interests are aligned with yours.
We want privacy too!
Thankfully, Qubes OS is free and open-source software, so you don't have to take our word for it.
We don't want the ability collect any data directly from Qubes OS
installations, because if anyone has that power, then the system is not secure.
We all use Qubes OS ourselves as a daily driver for our work and personal
lives, so our interests are aligned with yours. We want privacy too!
Thankfully, Qubes OS is free and open-source software, so you don't have to
take our word for it.
Of course, third-party software (including other operating systems) running inside of qubes may not be as privacy-respecting, so please be mindful of what you install.
We have no control over such third-party software.
Of course, third-party software (including other operating systems) running
inside of qubes may not be as privacy-respecting, so please be mindful of what
you install. We have no control over such third-party software.
For more information, please see [FAQ: How does Qubes OS provide privacy?](/faq/#how-does-qubes-os-provide-privacy)
For more information, please see [FAQ: How does Qubes OS provide
privacy?](/faq/#how-does-qubes-os-provide-privacy)

211
introduction/reporting-bugs.md
View File

@ -15,125 +15,184 @@ ref: 121
title: Reporting Bugs and Other Issues
---
All issues pertaining to the Qubes OS Project (including auxiliary infrastructure such as the [website](/)) are tracked in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues), our GitHub issue tracker.
If you're looking for help, please see [Help, Support, Mailing Lists, and Forum](/support/).
All issues pertaining to the Qubes OS Project (including auxiliary
infrastructure such as the [website](/)) are tracked in
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues), our GitHub
issue tracker. If you're looking for help, please see [Help, Support, Mailing
Lists, and Forum](/support/).
## Important ##
- **To disclose a security issue confidentially, please see the [Security](/security/) page.**
- **In all other cases, please do not email individual developers about issues.**
- **Please note that many issues can be resolved by reading the [documentation](/doc/).**
- **If you see something that should be changed in the documentation, [submit a change](/doc/doc-guidelines/).**
- **To disclose a security issue confidentially, please see the
[Security](/security/) page.**
- **In all other cases, please do not email individual developers about
issues.**
- **Please note that many issues can be resolved by reading the
[documentation](/doc/).**
- **If you see something that should be changed in the documentation, [submit a
change](/doc/doc-guidelines/).**
## 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.).
Only Qubes team members can apply labels.
Every issue must have exactly one **type** (`T: bug`, `T: enhancement`, or `T: task`), exactly one **priority** (e.g., `P: major`), and at least one **component** (e.g., `C: core`).
Issues may have additional labels, if applicable (e.g., `crypto`, `ux`).
Only Qubes team members can apply labels. Every issue must have exactly one
**type** (`T: bug`, `T: enhancement`, or `T: task`), exactly one **priority**
(e.g., `P: major`), and at least one **component** (e.g., `C: core`). Issues
may have additional labels, if applicable (e.g., `crypto`, `ux`).
## Issue tracker 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.
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/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/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` 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`.
The Qubes team has its own roadmap and priorities, which will govern the manner and order in which open issues are addressed.
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`.
The Qubes team has its own roadmap and priorities, which will govern the manner
and order in which open issues are addressed.
## Following up afterward ##
If the Qubes developers make a code change that resolves your issue, then your GitHub issue will typically be closed from the relevant patch message.
After that, the package containing the fix 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 your bug, please leave a comment on your issue explaining the situation.
When you do, we will receive a notification and respond on your issue or reopen it (or both).
Please **do not** create a duplicate issue or attempt to contact the developers individually about your problem.
If the Qubes developers make a code change that resolves your issue, then your
GitHub issue will typically be closed from the relevant patch message. After
that, the package containing the fix 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 your bug, please leave a comment on your issue explaining the situation.
When you do, we will receive a notification and respond on your issue or reopen
it (or both). Please **do not** create a duplicate issue or attempt to contact
the developers individually about your problem.
In other cases, your 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 your reported bug was fixed or your requested enhancement was implemented.
In other cases, your 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 your reported bug was fixed or your requested enhancement was implemented.
## See also ##

7
project-security/bulletins-checklist.md
View File

@ -8,7 +8,6 @@ ref: 215
title: Security Bulletin Checklist
---
## Preparation
* Draft QSB and push to private repository
@ -19,6 +18,8 @@ title: Security Bulletin Checklist
* Upload packages to `security-testing` and `current-testing` repositories
* Push QSB to public repository
* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Publish a [news post](/news/) using the [QSB
Template](/security/bulletins/template/)
* Send the content of the news post to the appropriate [mailing
lists](/support/)
* Share link to news post on social media

8
project-security/bulletins.md
View File

@ -12,8 +12,10 @@ ref: 218
title: Qubes Security Bulletins (QSBs)
---
A **Qubes Security Bulletin (QSB)** is a security announcement issued by the [Qubes Security Team](/security/#the-qubes-security-team) through the [Qubes Security Pack](/security/pack/).
A QSB typically provides a summary and impact analysis of one or more recently-discovered software vulnerabilities, including details about patching to address them.
A **Qubes Security Bulletin (QSB)** is a security announcement issued by the
[Qubes Security Team](/security/#the-qubes-security-team) through the [Qubes
Security Pack](/security/pack/). A QSB typically provides a summary and impact
analysis of one or more recently-discovered software vulnerabilities, including
details about patching to address them.
## Full list

22
project-security/canaries.md
View File

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

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

@ -6,7 +6,6 @@ ref: 216
title: Canary Checklist
---
## Preparation
* Draft canary and push to private repository
@ -15,7 +14,9 @@ title: Canary Checklist
## Announcement
* Push canary to public repository
* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Publish a [news post](/news/) using the [Canary
Template](/security/canaries/template/)
* Send the content of the news post to the appropriate [mailing
lists](/support/)
* Share link to news post on social media
* Set a reminder for the next canary

5
project-security/security-pack.md
View File

@ -18,8 +18,8 @@ ref: 213
title: Qubes Security Pack (qubes-secpack)
---
The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains:
The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that
contains:
* [Qubes PGP keys](https://keys.qubes-os.org/keys/)
* [Qubes Security Bulletins (QSBs)](/security/bulletins/)
@ -32,7 +32,6 @@ official location is:
<https://github.com/QubesOS/qubes-secpack>
## How to obtain, verify, and read
The following example demonstrates one method of obtaining the `qubes-secpack`,

49
project-security/security.md
View File

@ -16,9 +16,10 @@ ref: 217
title: Qubes OS Project Security Center
---
This page provides a central hub for topics pertaining to the security of the Qubes OS Project.
For topics pertaining to software security *within* Qubes OS, see [Security in Qubes](/doc/#security-in-qubes).
The following is a list of important project security pages:
This page provides a central hub for topics pertaining to the security of the
Qubes OS Project. For topics pertaining to software security *within* Qubes OS,
see [Security in Qubes](/doc/#security-in-qubes). The following is a list of
important project security pages:
- [Qubes Security Pack (`qubes-secpack`)](/security/pack/)
- [Qubes Security Bulletins (QSBs)](/security/bulletins/)
@ -30,27 +31,40 @@ The following is a list of important project security pages:
## Reporting Security Issues in Qubes OS
If you believe you have found a security issue affecting Qubes OS, either directly or indirectly (e.g. the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you!
We promise to treat any reported issue seriously and, if the investigation confirms that it affects Qubes, to patch it within a reasonable time and release a public [Qubes Security Bulletin](/security/bulletins/) that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer.
If you believe you have found a security issue affecting Qubes OS, either
directly or indirectly (e.g. the issue affects Xen in a configuration that is
used in Qubes OS), then we would be more than happy to hear from you! We
promise to treat any reported issue seriously and, if the investigation
confirms that it affects Qubes, to patch it within a reasonable time and
release a public [Qubes Security Bulletin](/security/bulletins/) that describes
the issue, discusses the potential impact of the vulnerability, references
applicable patches or workarounds, and credits the discoverer.
## Security Updates
Qubes security updates are obtained by [Updating Qubes OS](/doc/updating-qubes-os/).
Qubes security updates are obtained by [Updating Qubes
OS](/doc/updating-qubes-os/).
## The Qubes Security Team
The Qubes Security Team (QST) is the subset of the [Qubes Team](/team/) that is responsible for ensuring the security of Qubes OS and the Qubes OS Project.
In particular, the QST is responsible for:
The Qubes Security Team (QST) is the subset of the [Qubes Team](/team/) that is
responsible for ensuring the security of Qubes OS and the Qubes OS Project. In
particular, the QST is responsible for:
- Responding to [reported security issues](#reporting-security-issues-in-qubes-os)
- Responding to [reported security
issues](#reporting-security-issues-in-qubes-os)
- Evaluating whether [XSAs](/security/xsa/) affect the security of Qubes OS
- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- Writing, applying, and/or distributing security patches to fix
vulnerabilities in Qubes OS
- Writing, signing, and publishing [Security Bulletins](/security/bulletins/)
- Writing, signing, and publishing [Canaries](/security/canaries/)
- Generating, safeguarding, and using the project's [PGP Keys](https://keys.qubes-os.org/keys/)
- Generating, safeguarding, and using the project's [PGP
Keys](https://keys.qubes-os.org/keys/)
As a security-oriented operating system, the QST is fundamentally important to Qubes, and every Qubes user implicitly trusts the members of the QST by virtue of the actions listed above.
The Qubes Security Team can be contacted via email at the following address:
As a security-oriented operating system, the QST is fundamentally important to
Qubes, and every Qubes user implicitly trusts the members of the QST by virtue
of the actions listed above. The Qubes Security Team can be contacted via email
at the following address:
```
security at qubes-os dot org
@ -58,9 +72,12 @@ security at qubes-os dot org
### Security Team PGP Key
Please use the [Security Team PGP Key](https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc) to encrypt all emails sent to this address.
This key is signed by the [Qubes Master Signing Key](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc).
Please see [Why and How to Verify Signatures](/security/verifying-signatures/) for information about how to verify these keys.
Please use the [Security Team PGP
Key](https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc) to encrypt
all emails sent to this address. This key is signed by the [Qubes Master
Signing Key](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc).
Please see [Why and How to Verify Signatures](/security/verifying-signatures/)
for information about how to verify these keys.
### Members of the Security Team

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

@ -11,71 +11,106 @@ ref: 211
title: Verifying Signatures
---
## What Digital Signatures Can and Cannot Prove
Most people --- even programmers --- are confused about the basic concepts underlying digital signatures.
Therefore, most people should read this section, even if it looks trivial at first sight.
Most people --- even programmers --- are confused about the basic concepts
underlying digital signatures. Therefore, most people should read this section,
even if it looks trivial at first sight.
Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty.
**Authenticity** ensures that a given file was indeed created by the person who signed it (i.e., that it was not forged by a third party).
**Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*).
Digital signatures can prove both **authenticity** and **integrity** to a
reasonable degree of certainty. **Authenticity** ensures that a given file was
indeed created by the person who signed it (i.e., that it was not forged by a
third party). **Integrity** ensures that the contents of the file have not been
tampered with (i.e., that a third party has not undetectably altered its
contents *en route*).
Digital signatures **cannot** prove any other property, e.g., that the signed file is not malicious.
In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality).
Digital signatures **cannot** prove any other property, e.g., that the signed
file is not malicious. In fact, there is nothing that could stop someone from
signing a malicious program (and it happens from time to time in reality).
The point is that we must decide who we will trust (e.g., Linus Torvalds, Microsoft, or the Qubes Project) and assume that if a given file was signed by a trusted party, then it should not be malicious or negligently buggy.
The decision of whether to trust any given party is beyond the scope of digital signatures.
It's more of a sociological and political decision.
The point is that we must decide who we will trust (e.g., Linus Torvalds,
Microsoft, or the Qubes Project) and assume that if a given file was signed by
a trusted party, then it should not be malicious or negligently buggy. The
decision of whether to trust any given party is beyond the scope of digital
signatures. It's more of a sociological and political decision.
Once we make the decision to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the bad things that can happen between us and them, e.g., server compromises (qubes-os.org will surely be compromised one day, so [don't blindly trust the live version of this site](/faq/#should-i-trust-this-website)), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
We call this philosophy [Distrusting the Infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure).
Once we make the decision to trust certain parties, digital signatures are
useful, because they make it possible for us to limit our trust only to those
few parties we choose and not to worry about all the bad things that can happen
between us and them, e.g., server compromises (qubes-os.org will surely be
compromised one day, so [don't blindly trust the live version of this
site](/faq/#should-i-trust-this-website)), dishonest IT staff at the hosting
company, dishonest staff at the ISPs, Wi-Fi attacks, etc. We call this
philosophy [Distrusting the
Infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure).
By verifying all the files we download that purport to be authored by a party we've chosen to trust, we eliminate concerns about the bad things discussed above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them).
By verifying all the files we download that purport to be authored by a party
we've chosen to trust, we eliminate concerns about the bad things discussed
above, since we can easily detect whether any files have been tampered with
(and subsequently choose to refrain from executing, installing, or opening
them).
However, for digital signatures to make any sense, we must ensure that the public keys we use for signature verification are indeed the original ones.
Anybody can generate a GPG key pair that purports to belong to "The Qubes Project," but of course only the key pair that we (i.e., the Qubes developers) generated is the legitimate one.
The next section explains how to verify the validity of the Qubes signing keys in the process of verifying a Qubes ISO.
(However, the same general principles apply to all cases in which you may wish to verify a PGP signature, such as [verifying repos](#how-to-verify-qubes-repos), not just verifying ISOs.)
However, for digital signatures to make any sense, we must ensure that the
public keys we use for signature verification are indeed the original ones.
Anybody can generate a GPG key pair that purports to belong to "The Qubes
Project," but of course only the key pair that we (i.e., the Qubes developers)
generated is the legitimate one. The next section explains how to verify the
validity of the Qubes signing keys in the process of verifying a Qubes ISO.
(However, the same general principles apply to all cases in which you may wish
to verify a PGP signature, such as [verifying
repos](#how-to-verify-qubes-repos), not just verifying ISOs.)
## How to Verify Qubes ISO Signatures
This section will guide you through the process of verifying a Qubes ISO by checking its PGP signature.
There are three basic steps in this process:
This section will guide you through the process of verifying a Qubes ISO by
checking its PGP signature. There are three basic steps in this process:
1. [Get the Qubes Master Signing Key and verify its authenticity](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)
1. [Get the Qubes Master Signing Key and verify its
authenticity](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)
2. [Get the Release Signing Key](#2-get-the-release-signing-key)
3. [Verify your Qubes ISO](#3-verify-your-qubes-iso)
If you run into any problems, please consult the [Troubleshooting FAQ](#troubleshooting-faq) below.
If you run into any problems, please consult the [Troubleshooting
FAQ](#troubleshooting-faq) below.
### Preparation
Before we begin, you'll need a program that can verify PGP signatures.
Any such program will do, but here are some examples for popular operating systems:
Before we begin, you'll need a program that can verify PGP signatures. Any such
program will do, but here are some examples for popular operating systems:
**Windows:** [Gpg4win](https://gpg4win.org/download.html) ([documentation](https://www.gpg4win.org/documentation.html)).
Use the Windows command line (`cmd.exe`) to enter commands.
**Windows:** [Gpg4win](https://gpg4win.org/download.html)
([documentation](https://www.gpg4win.org/documentation.html)). Use the Windows
command line (`cmd.exe`) to enter commands.
**Mac:** [GPG Suite](https://gpgtools.org/) ([documentation](https://gpgtools.tenderapp.com/kb)).
Open a terminal to enter commands.
**Mac:** [GPG Suite](https://gpgtools.org/)
([documentation](https://gpgtools.tenderapp.com/kb)). Open a terminal to enter
commands.
**Linux:** `gpg2` from your package manager or from [gnupg.org](https://gnupg.org/download/index.html) ([documentation](https://www.gnupg.org/documentation/)).
Open a terminal to enter commands.
**Linux:** `gpg2` from your package manager or from
[gnupg.org](https://gnupg.org/download/index.html)
([documentation](https://www.gnupg.org/documentation/)). Open a terminal to
enter commands.
The commands below will use `gpg2`, but if that doesn't work for you, try `gpg` instead.
If that still doesn't work, please consult the documentation for your specific program (see links above).
The commands below will use `gpg2`, but if that doesn't work for you, try `gpg`
instead. If that still doesn't work, please consult the documentation for your
specific program (see links above).
### 1. Get the Qubes Master Signing Key and verify its authenticity
Every file published by the Qubes Project (ISO, RPM, TGZ files and Git repositories) is digitally signed by one of the developer keys or Release Signing Keys.
Each such key is signed by the [Qubes Master Signing Key](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) (`0xDDFA1A3E36879494`).
The developer signing keys are set to expire after one year, while the Qubes Master Signing Key and Release Signing Keys have no expiration date.
This Qubes Master Signing Key was generated on and is kept only on a dedicated, air-gapped "vault" machine, and the private portion will (hopefully) never leave this isolated machine.
Every file published by the Qubes Project (ISO, RPM, TGZ files and Git
repositories) is digitally signed by one of the developer keys or Release
Signing Keys. Each such key is signed by the [Qubes Master Signing
Key](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)
(`0xDDFA1A3E36879494`). The developer signing keys are set to expire after one
year, while the Qubes Master Signing Key and Release Signing Keys have no
expiration date. This Qubes Master Signing Key was generated on and is kept
only on a dedicated, air-gapped "vault" machine, and the private portion will
(hopefully) never leave this isolated machine.
There are several ways to get the Qubes Master Signing Key.
- If you have access to an existing Qubes installation, it's available in every VM ([except dom0](https://github.com/QubesOS/qubes-issues/issues/2544)):
- If you have access to an existing Qubes installation, it's available in every
VM ([except dom0](https://github.com/QubesOS/qubes-issues/issues/2544)):
```shell_session
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc
@ -95,33 +130,47 @@ There are several ways to get the Qubes Master Signing Key.
$ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
```
- Download it as a [file](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc), then import it with GPG:
- Download it as a
[file](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc), then
import it with GPG:
```shell_session
$ gpg2 --import ./qubes-master-signing-key.asc
```
- Get it from a public [keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples) (specified on first use with `--keyserver <URI>` along with keyserver options to include key signatures), e.g.:
- Get it from a public
[keyserver](https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples)
(specified on first use with `--keyserver <URI>` along with keyserver options
to include key signatures), e.g.:
```shell_session
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
```
The Qubes Master Signing Key is also available in the [Qubes Security Pack](/security/pack/) and in the archives of the project's [developer](https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ) and [user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ) [mailing lists](/support/).
The Qubes Master Signing Key is also available in the [Qubes Security
Pack](/security/pack/) and in the archives of the project's
[developer](https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ)
and
[user](https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ)
[mailing lists](/support/).
Once you have obtained the Qubes Master Signing Key, you must verify that it is authentic rather than a forgery.
Anyone can create a PGP key with the name "Qubes Master Signing Key," so you cannot rely on the name alone.
You also should not rely on any single website, not even over HTTPS.
Once you have obtained the Qubes Master Signing Key, you must verify that it is
authentic rather than a forgery. Anyone can create a PGP key with the name
"Qubes Master Signing Key," so you cannot rely on the name alone. You also
should not rely on any single website, not even over HTTPS.
So, what *should* you do?
One option is to use the PGP [Web of Trust](https://en.wikipedia.org/wiki/Web_of_trust).
In addition, some operating systems include the means to acquire the Qubes Master Signing Key in a secure way.
For example, on Fedora, `dnf install distribution-gpg-keys` will get you the Qubes Master Signing Key along with several other Qubes keys.
On Debian, your keyring may already contain the necessary keys.
So, what *should* you do? One option is to use the PGP [Web of
Trust](https://en.wikipedia.org/wiki/Web_of_trust). In addition, some operating
systems include the means to acquire the Qubes Master Signing Key in a secure
way. For example, on Fedora, `dnf install distribution-gpg-keys` will get you
the Qubes Master Signing Key along with several other Qubes keys. On Debian,
your keyring may already contain the necessary keys.
Another option is to rely on the key's fingerprint.
Every PGP key has a fingerprint that uniquely identifies it among all PGP keys (viewable with `gpg2 --fingerprint <KEY_ID>`).
Therefore, if you know the genuine Qubes Master Signing Key fingerprint, then you always have an easy way to confirm whether any purported copy of it is authentic, simply by comparing the fingerprints.
Another option is to rely on the key's fingerprint. Every PGP key has a
fingerprint that uniquely identifies it among all PGP keys (viewable with `gpg2
--fingerprint <KEY_ID>`). Therefore, if you know the genuine Qubes Master
Signing Key fingerprint, then you always have an easy way to confirm whether
any purported copy of it is authentic, simply by comparing the fingerprints.
For example, here is the Qubes Master Signing Key fingerprint:
@ -131,27 +180,45 @@ pub 4096R/36879494 2010-04-01
uid Qubes Master Signing Key
```
But how do you know that this is the real fingerprint?
After all, [this website could be compromised](/faq/#should-i-trust-this-website), so the fingerprint you see here may not be genuine.
That's why we strongly suggest obtaining the fingerprint from *multiple, independent sources in several different ways*.
But how do you know that this is the real fingerprint? After all, [this website
could be compromised](/faq/#should-i-trust-this-website), so the fingerprint
you see here may not be genuine. That's why we strongly suggest obtaining the
fingerprint from *multiple, independent sources in several different ways*.
Here are some ideas for how to do that:
- Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- Check the fingerprint on various websites (e.g., [mailing
lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ),
[discussion
forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw),
[social](https://twitter.com/rootkovska/status/496976187491876864)
[media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/),
[personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- Check against PDFs, photographs, and videos in which the fingerprint appears
(e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
(e.g., [slides from a
talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a
[T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or
in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes
Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat
rooms.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- Text, email, call, video chat, snail mail, or meet up with people you know to
confirm the fingerprint.
- Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place.
Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match.
Once you've obtained the fingerprint from enough independent sources in enough
different ways that you feel confident that you know the genuine fingerprint,
keep it in a safe place. Every time you need to check whether a key claiming to
be the Qubes Master Signing Key is authentic, compare that key's fingerprint to
your trusted copy and confirm they match.
Now that you've imported the authentic Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
Now that you've imported the authentic Qubes Master Signing Key, set its trust
level to "ultimate" so that it can be used to automatically verify all the keys
signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
```
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
@ -194,11 +261,16 @@ unless you restart the program.
gpg> q
```
Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
Now, when you import any of the legitimate Qubes developer keys and Release
Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they
will already be trusted in virtue of being signed by the Qubes Master Signing
Key.
Before proceeding to the next step, make sure the Qubes Master Signing Key is in your keyring with the correct trust level.
(Note: We have already verified the authenticity of the key, so this final check is not about security.
Rather, it's just a sanity check to make sure that we've imported the key into our keyring correctly.)
Before proceeding to the next step, make sure the Qubes Master Signing Key is
in your keyring with the correct trust level. (Note: We have already verified
the authenticity of the key, so this final check is not about security. Rather,
it's just a sanity check to make sure that we've imported the key into our
keyring correctly.)
```
$ gpg2 -k "Qubes Master Signing Key"
@ -207,17 +279,23 @@ pub rsa4096 2010-04-01 [SC]
uid [ultimate] Qubes Master Signing Key
```
If you don't see the Qubes Master Signing Key here with a trust level of "ultimate," go back and follow the instructions in this section carefully.
If you don't see the Qubes Master Signing Key here with a trust level of
"ultimate," go back and follow the instructions in this section carefully.
### 2. Get the Release Signing Key
The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
There are several ways to get the Release Signing Key for your Qubes release.
The filename of the Release Signing Key for your version is usually
`qubes-release-X-signing-key.asc`, where `X` is the major version number of
your Qubes release. There are several ways to get the Release Signing Key for
your Qubes release.
- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
These can be [copied](/doc/how-to-copy-from-dom0/#copying-from-dom0) into other VMs for further use.
In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
- If you have access to an existing Qubes installation, the release keys are
available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`. These can be
[copied](/doc/how-to-copy-from-dom0/#copying-from-dom0) into other VMs for
further use. In addition, every other VM contains the release key
corresponding to that installation's release in
`/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`. If you wish to use one of these keys,
make sure to import it into your keyring, e.g.:
```
$ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
@ -229,10 +307,12 @@ There are several ways to get the Release Signing Key for your Qubes release.
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
```
- Download it as a file.
You can find the Release Signing Key for your Qubes version on the [Downloads](/downloads/) page.
You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack](/security/pack/) and the [Qubes OS Keyserver](https://keys.qubes-os.org/keys/).
Once you've downloaded your Release Signing Key, import it with GPG:
- Download it as a file. You can find the Release Signing Key for your Qubes
version on the [Downloads](/downloads/) page. You can also download all the
currently used developers' signing keys, Release Signing Keys, and the Qubes
Master Signing Key from the [Qubes Security Pack](/security/pack/) and the
[Qubes OS Keyserver](https://keys.qubes-os.org/keys/). Once you've downloaded
your Release Signing Key, import it with GPG:
```shell_session
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc
@ -251,13 +331,16 @@ sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key
gpg: 2 good signatures
```
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix.
This verifies the authenticity of the Release Signing Key.
Note that the `!` flag after the `sig` tag is important because it means that the key signature is valid.
A `sig-` prefix would indicate a bad signature and `sig%` would mean that gpg encountered an error while verifying the signature.
It is not necessary to independently verify the authenticity of the Release Signing Key, since you already verified the authenticity of the Qubes Master Signing Key.
Before proceeding to the next step, make sure the Release Signing Key is in your keyring:
This is just an example, so the output you receive will not look exactly the
same. What matters is the line that shows that this key is signed by the Qubes
Master Signing Key with a `sig!` prefix. This verifies the authenticity of the
Release Signing Key. Note that the `!` flag after the `sig` tag is important
because it means that the key signature is valid. A `sig-` prefix would
indicate a bad signature and `sig%` would mean that gpg encountered an error
while verifying the signature. It is not necessary to independently verify the
authenticity of the Release Signing Key, since you already verified the
authenticity of the Qubes Master Signing Key. Before proceeding to the next
step, make sure the Release Signing Key is in your keyring:
```
$ gpg2 -k "Qubes OS Release"
@ -266,17 +349,20 @@ pub rsa4096 2017-03-06 [SC]
uid [ full ] Qubes OS Release X Signing Key
```
If you don't see the correct Release Signing Key here, go back and follow the instructions in this section carefully.
If you don't see the correct Release Signing Key here, go back and follow the
instructions in this section carefully.
### 3. Verify your Qubes ISO
Every Qubes ISO is released with a detached PGP signature file, which you can find on the [Downloads](/downloads/) page alongside the ISO.
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the signature file for that ISO is `Qubes-RX-x86_64.iso.asc`, where `X` is a specific version of Qubes.
The signature filename is always the same as the ISO filename followed by `.asc`.
Every Qubes ISO is released with a detached PGP signature file, which you can
find on the [Downloads](/downloads/) page alongside the ISO. If the filename of
your ISO is `Qubes-RX-x86_64.iso`, then the name of the signature file for that
ISO is `Qubes-RX-x86_64.iso.asc`, where `X` is a specific version of Qubes. The
signature filename is always the same as the ISO filename followed by `.asc`.
Download both the ISO and its signature file.
Put both of them in the same directory, then navigate to that directory.
Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
Download both the ISO and its signature file. Put both of them in the same
directory, then navigate to that directory. Now, you can verify the ISO by
executing this GPG command in the directory that contains both files:
```shell_session
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
@ -287,22 +373,28 @@ gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
```
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`.
This confirms that the signature on the ISO is good.
This is just an example, so the output you receive will not look exactly the
same. What matters is the line that says `Good signature from "Qubes OS Release
X Signing Key"`. This confirms that the signature on the ISO is good.
## How to Verify Qubes ISO Digests
Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`.
This file contains the output of running several different cryptographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests" or "hash values."
These hash values are provided as an alternative verification method to PGP signatures (though the digest file is itself also PGP-signed --- see below).
If you've already verified the signatures on the ISO directly, then verifying digests is not necessary.
You can find the `.DIGESTS` for your ISO on the [Downloads](/downloads/) page, and you can always find all the digest files for every Qubes ISO in the [Qubes Security Pack](/security/pack/).
This file contains the output of running several different cryptographic hash
functions on the ISO in order to obtain alphanumeric outputs known as "digests"
or "hash values." These hash values are provided as an alternative verification
method to PGP signatures (though the digest file is itself also PGP-signed ---
see below). If you've already verified the signatures on the ISO directly, then
verifying digests is not necessary. You can find the `.DIGESTS` for your ISO on
the [Downloads](/downloads/) page, and you can always find all the digest files
for every Qubes ISO in the [Qubes Security Pack](/security/pack/).
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the digest file for that ISO is `Qubes-RX-x86_64.iso.DIGESTS`, where `X` is a specific version of Qubes.
The digest filename is always the same as the ISO filename followed by `.DIGESTS`.
Since the digest file is a plain text file, you can open it with any text editor.
Inside, you should find text that looks similar to this:
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the
digest file for that ISO is `Qubes-RX-x86_64.iso.DIGESTS`, where `X` is a
specific version of Qubes. The digest filename is always the same as the ISO
filename followed by `.DIGESTS`. Since the digest file is a plain text file,
you can open it with any text editor. Inside, you should find text that looks
similar to this:
```
-----BEGIN PGP SIGNED MESSAGE-----
@ -331,9 +423,10 @@ g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
-----END PGP SIGNATURE-----
```
Four digests have been computed for this ISO.
The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512.
One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs:
Four digests have been computed for this ISO. The hash functions used, in order
from top to bottom, are MD5, SHA1, SHA256, and SHA512. One way to verify that
the ISO you downloaded matches any of these hash values is by using the
respective `*sum` programs:
```shell_session
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
@ -350,13 +443,16 @@ Qubes-RX-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted
```
The `OK` response tells us that the hash value for that particular hash function matches.
The program also warns us that there are 23 improperly formatted lines, but this is to be expected.
This is because each file contains lines for several different hash values (as mentioned above), but each `*sum` program verifies only the line for its own hash function.
In addition, there are lines for the PGP signature that the `*sum` programs do not know how to read.
Therefore, it is safe to ignore these warning lines.
The `OK` response tells us that the hash value for that particular hash
function matches. The program also warns us that there are 23 improperly
formatted lines, but this is to be expected. This is because each file contains
lines for several different hash values (as mentioned above), but each `*sum`
program verifies only the line for its own hash function. In addition, there
are lines for the PGP signature that the `*sum` programs do not know how to
read. Therefore, it is safe to ignore these warning lines.
Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.:
Another way is to use `openssl` to compute each hash value, then compare them
to the contents of the digest file.:
```shell_session
$ openssl dgst -md5 Qubes-RX-x86_64.iso
@ -371,11 +467,15 @@ SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4
(Notice that the outputs match the values from the digest file.)
However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a malicious ISO, computed the hash values for that malicious ISO, and replaced the values in `Qubes-RX-x86_64.iso.DIGESTS` with his own set of values.
However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a
malicious ISO, computed the hash values for that malicious ISO, and replaced
the values in `Qubes-RX-x86_64.iso.DIGESTS` with his own set of values.
Therefore, we should also verify the authenticity of the listed hash values.
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG
to verify it from the command line:
1. [Get the Qubes Master Signing Key and verify its authenticity](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)
1. [Get the Qubes Master Signing Key and verify its
authenticity](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)
2. [Get the Release Signing Key](#2-get-the-release-signing-key)
3. Verify the signature in the digest file:
@ -390,16 +490,22 @@ Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to
gpg: textmode signature, digest algorithm SHA256
```
The signature is good.
If our copy of the `Qubes OS Release X Signing Key` is being validated by the authentic Qubes Master Signing Key (see [above](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)), we can be confident that these hash values came from the Qubes devs.
The signature is good. If our copy of the `Qubes OS Release X Signing Key` is
being validated by the authentic Qubes Master Signing Key (see
[above](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)), we
can be confident that these hash values came from the Qubes devs.
## How to Verify Qubes Repos
Whenever you use one of the [Qubes repositories](https://github.com/QubesOS), you should verify the PGP signature in a tag on the latest commit or on the latest commit itself.
(One or both may be present, but only one is required.)
If there is no trusted signed tag or commit on top, any commits after the latest trusted signed tag or commit should **not** be trusted.
If you come across a repo with any unsigned commits, you should not add any of your own signed tags or commits on top of them unless you personally vouch for the trustworthiness of the unsigned commits.
Instead, ask the person who pushed the unsigned commits to sign them.
Whenever you use one of the [Qubes repositories](https://github.com/QubesOS),
you should verify the PGP signature in a tag on the latest commit or on the
latest commit itself. (One or both may be present, but only one is required.)
If there is no trusted signed tag or commit on top, any commits after the
latest trusted signed tag or commit should **not** be trusted. If you come
across a repo with any unsigned commits, you should not add any of your own
signed tags or commits on top of them unless you personally vouch for the
trustworthiness of the unsigned commits. Instead, ask the person who pushed the
unsigned commits to sign them.
To verify a signature on a Git tag:
@ -425,89 +531,118 @@ or
$ git verify-commit <commit ID>
```
You should always perform this verification on a trusted local machine with properly validated keys (which are available in the [Qubes Security Pack](/security/pack/)) rather than relying on a third party, such as GitHub.
While the GitHub interface may claim that a commit has a verified signature from a member of the Qubes team, this is only trustworthy if GitHub has performed the signature check correctly, the account identity is authentic, the user's key has not been replaced by an admin, GitHub's servers have not been compromised, and so on.
Since there's no way for you to be certain that all such conditions hold, you're much better off verifying signatures yourself.
You should always perform this verification on a trusted local machine with
properly validated keys (which are available in the [Qubes Security
Pack](/security/pack/)) rather than relying on a third party, such as GitHub.
While the GitHub interface may claim that a commit has a verified signature
from a member of the Qubes team, this is only trustworthy if GitHub has
performed the signature check correctly, the account identity is authentic, the
user's key has not been replaced by an admin, GitHub's servers have not been
compromised, and so on. Since there's no way for you to be certain that all
such conditions hold, you're much better off verifying signatures yourself.
Also see: [Distrusting the Infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure)
Also see: [Distrusting the
Infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure)
## Troubleshooting FAQ
### Why am I getting "Can't check signature: public key not found"?
You don't have the correct [Release Signing Key](#2-get-the-release-signing-key).
You don't have the correct [Release Signing
Key](#2-get-the-release-signing-key).
### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"?
The problem could be one or more of the following:
- You're trying to verify the wrong file(s).
Read this page again carefully.
- You're using the wrong GPG command.
Follow the examples in [Verify your Qubes ISO](#3-verify-your-qubes-iso) carefully.
- The ISO or [signature file](#3-verify-your-qubes-iso) is bad (e.g., incomplete or corrupt download).
Try downloading the signature file again from a different source, then try verifying again.
If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
- You're trying to verify the wrong file(s). Read this page again carefully.
- You're using the wrong GPG command. Follow the examples in [Verify your Qubes
ISO](#3-verify-your-qubes-iso) carefully.
- The ISO or [signature file](#3-verify-your-qubes-iso) is bad (e.g.,
incomplete or corrupt download). Try downloading the signature file again
from a different source, then try verifying again. If you still get the same
result, try downloading the ISO again from a different source, then try
verifying again.
### Why am I getting "bash: gpg2: command not found"?
You don't have `gpg2` installed.
Please install it using the method appropriate for your environment (e.g., via your package manager).
You don't have `gpg2` installed. Please install it using the method appropriate
for your environment (e.g., via your package manager).
### Why am I getting "No such file or directory"?
Your working directory does not contain the required files.
Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory.
Your working directory does not contain the required files. Go back and follow
the instructions more carefully, making sure that you put all required files in
the same directory *and* navigate to that directory.
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash
datafile: file open error"?
The correct ISO is not in your working directory.
### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"?
### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures
failed: file open error"?
The correct [signature file](#3-verify-your-qubes-iso) is not in your working directory.
The correct [signature file](#3-verify-your-qubes-iso) is not in your working
directory.
### Why am I getting "no valid OpenPGP data found"?
Either you don't have the correct [signature file](#3-verify-your-qubes-iso), or you inverted the arguments to `gpg2`.
([The signature file goes first.](#3-verify-your-qubes-iso))
Either you don't have the correct [signature file](#3-verify-your-qubes-iso),
or you inverted the arguments to `gpg2`. ([The signature file goes
first.](#3-verify-your-qubes-iso))
### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
### Why am I getting "WARNING: This key is not certified with a trusted
signature! There is no indication that the signature belongs to the owner."?
Either you don't have the [Qubes Master Signing Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity), or you didn't [set its trust level correctly](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity).
Either you don't have the [Qubes Master Signing
Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity), or you
didn't [set its trust level
correctly](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity).
### Why am I getting "X signature not checked due to a missing key"?
You don't have the keys that created those signatures in your keyring.
For present purposes, you don't need them as long as you have the [Qubes Master Signing Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity) and the [Release Signing Key](#2-get-the-release-signing-key) for your Qubes version.
You don't have the keys that created those signatures in your keyring. For
present purposes, you don't need them as long as you have the [Qubes Master
Signing Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity)
and the [Release Signing Key](#2-get-the-release-signing-key) for your Qubes
version.
### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key?
### Why am I seeing additional signatures on a key with "[User ID not found]"
or from a revoked key?
This is just a basic part of how OpenPGP works.
Anyone can sign anyone else's public key and upload the signed public key to keyservers.
Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
This has no impact on verifying Qubes ISOs, code, or keys.
This is just a basic part of how OpenPGP works. Anyone can sign anyone else's
public key and upload the signed public key to keyservers. Everyone is also
free to revoke their own keys at any time (assuming they possess or can create
a revocation certificate). This has no impact on verifying Qubes ISOs, code, or
keys.
### Why am I getting "verify signatures failed: unexpected data"?
You're not verifying against the correct [signature file](#3-verify-your-qubes-iso).
You're not verifying against the correct [signature
file](#3-verify-your-qubes-iso).
### Why am I getting "not a detached signature"?
You're not verifying against the correct [signature file](#3-verify-your-qubes-iso).
You're not verifying against the correct [signature
file](#3-verify-your-qubes-iso).
### Why am I getting "CRC error; [...] no signature found [...]"?
You're not verifying against the correct [signature file](#3-verify-your-qubes-iso), or the signature file has been modified.
Try downloading it again or from a different source.
You're not verifying against the correct [signature
file](#3-verify-your-qubes-iso), or the signature file has been modified. Try
downloading it again or from a different source.
### Do I have to verify the ISO against both the [signature file](#3-verify-your-qubes-iso) and the [digest file](#how-to-verify-qubes-iso-digests)?
### Do I have to verify the ISO against both the [signature
file](#3-verify-your-qubes-iso) and the [digest
file](#how-to-verify-qubes-iso-digests)?
No, either method is sufficient by itself.
### Why am I getting "no properly formatted X checksum lines found"?
You're not checking the correct [digest file](#how-to-verify-qubes-iso-digests).
You're not checking the correct [digest
file](#how-to-verify-qubes-iso-digests).
### Why am I getting "WARNING: X lines are improperly formatted"?
@ -519,9 +654,14 @@ The correct ISO is not in your working directory.
### I have another problem that isn't mentioned here.
Carefully read this page again to be certain that you didn't skip any steps.
In particular, make sure you have the [Qubes Master Signing Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity), the [Release Signing Key](#2-get-the-release-signing-key), *and* the [signature file](#3-verify-your-qubes-iso) and/or [digest file](#how-to-verify-qubes-iso-digests) all for the *correct* Qubes OS version.
If your question is about GPG, please see the [GPG documentation](https://www.gnupg.org/documentation/).
Still have question?
Please see [Help, Support, Mailing Lists, and Forum](/support/) for places where you can ask!
Carefully read this page again to be certain that you didn't skip any steps. In
particular, make sure you have the [Qubes Master Signing
Key](#1-get-the-qubes-master-signing-key-and-verify-its-authenticity), the
[Release Signing Key](#2-get-the-release-signing-key), *and* the [signature
file](#3-verify-your-qubes-iso) and/or [digest
file](#how-to-verify-qubes-iso-digests) all for the *correct* Qubes OS version.
If your question is about GPG, please see the [GPG
documentation](https://www.gnupg.org/documentation/). Still have question?
Please see [Help, Support, Mailing Lists, and Forum](/support/) for places
where you can ask!

41
project-security/xsa.md
View File

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

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

@ -4,341 +4,400 @@ layout: doc
permalink: /doc/installation-guide/
redirect_from:
- /en/doc/installation-guide/
- /doc/InstallationGuide/
- /wiki/InstallationGuide/
- /doc/InstallationGuideR1/
- /doc/InstallationGuideR2B1/
- /doc/InstallationGuideR2B2/
- /doc/InstallationGuideR2B3/
- /doc/InstallationGuideR2rc1/
- /doc/InstallationGuideR2rc2/
- /doc/InstallationGuideR3.0rc1/
- /doc/InstallationGuideR3.0rc2/
- /doc/installationguide/
- /wiki/installationguide/
- /doc/installationguider1/
- /doc/installationguider2b1/
- /doc/installationguider2b2/
- /doc/installationguider2b3/
- /doc/installationguider2rc1/
- /doc/installationguider2rc2/
- /doc/installationguider3.0rc1/
- /doc/installationguider3.0rc2/
- /doc/live-usb/
ref: 153
title: Installation Guide
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
## pre-installation
### Hardware requirements
### hardware requirements
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Qubes has no control over what happens on your computer before you install it.
No software can provide security if it is installed on compromised hardware.
Do not install Qubes on a computer you don't trust.
See <a href="/doc/install-security/">installation security</a> for more information.
<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.
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, 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 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. 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, 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 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
### copying the iso onto the installation medium
Start by [downloading](/downloads/) a Qubes ISO.
start by [downloading](/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 dual-layer DVD, a Blu-ray disc, or a USB drive.
The size of each Qubes ISO is available on the [downloads](/downloads/) page by hovering over the download button.
once the iso has been verified as authentic, you should copy it onto the
installation medium of your choice, such as a dual-layer dvd, a blu-ray disc,
or a usb drive. the size of each qubes iso is available on the
[downloads](/downloads/) page by hovering over the download button.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> There are important <a href="/doc/install-security/">security considerations</a> to keep in mind when choosing an installation medium.
<b>note:</b> there are important <a href="/doc/install-security/">security
considerations</a> to keep in mind when choosing an installation medium.
</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>
If you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
if you choose to use a usb drive, copy the iso onto the usb device, e.g. using
`dd`:
```
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
$ sudo dd if=qubes-rx-x86_64.iso of=/dev/sdy status=progress bs=1048576 && sync
```
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`).
On Windows, you can use the [Rufus](https://rufus.akeo.ie/) tool to write the ISO to a USB key.
MediaTest is not recommended.
Be sure to select "DD image" mode (*after* selecting the Qubes ISO):
on windows, you can use the [rufus](https://rufus.akeo.ie/) tool to write the
iso to a usb key. mediatest is not recommended. be sure to select "dd image"
mode (*after* selecting the qubes iso):
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> If you do this on Windows 10, you can only install Qubes without MediaTest, which is not recommended.
<b>note:</b> if you do this on windows 10, you can only install qubes
without mediatest, which is not recommended.
</div>
![Rufus menu](/attachment/doc/rufus-menu.png)
![rufus menu](/attachment/doc/rufus-menu.png)
![Rufus DD image mode](/attachment/doc/rufus-dd-image-mode.png)
![rufus dd image mode](/attachment/doc/rufus-dd-image-mode.png)
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.
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.
## Installation
## installation
This section will demonstrate a simple installation using mostly default settings.
this section will demonstrate a simple installation using mostly default
settings.
### Getting to the boot screen
### getting to the boot screen
Just after you power on your machine, make the Qubes OS medium available to the computer by inserting your DVD or USB drive.
Shortly after the Power-on self-test (POST) is completed, you should be greeted with the Qubes OS boot screen.
just after you power on your machine, make the qubes os medium available to the
computer by inserting your dvd or usb drive. shortly after the power-on
self-test (post) is completed, you should be greeted with the qubes os boot
screen.
![Boot screen](/attachment/doc/boot-screen.png)
![boot screen](/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.
<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
* Troubleshooting
* install qubes os
* test this media and install qubes os
* troubleshooting
Select the option to test this media and install Qubes OS.
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).
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).
After the POST, you may have a chance to choose a boot device.
You may wish to select the USB drive or DVD drive as a temporary boot option so that the next time you boot, your internal storage device will be selected first.
after the post, you may have a chance to choose a boot device. you may wish to
select the usb drive or dvd drive as a temporary boot option so that the next
time you boot, your internal storage device will be selected first.
![Boot order](/attachment/doc/boot-order.png)
![boot order](/attachment/doc/boot-order.png)
### The installer home screen
### 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)
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)
![unsupported hardware detected](/attachment/doc/unsupported-hardware-detected.png)
Do not panic.
It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS.
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. 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
### 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)
![installation summary not ready](/attachment/doc/installation-summary-not-ready.png)
### Localization
### 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)
![keyboard layout selection](/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)
![language support selection](/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.
don't forget to select your time and date by clicking on the time & date entry.
![Time and date](/attachment/doc/time-and-date.png)
![time and date](/attachment/doc/time-and-date.png)
### Software
### software
![Add-ons](/attachment/doc/add-ons.png)
![add-ons](/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](/doc/whonix/) 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](/doc/whonix/) 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.
press **done** to go back to the installation summary screen.
### Installation destination
### 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)
![select storage device](/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> qubes os uses full-disk aes encryption (fde) via luks by
default.
</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)
![select storage passhprase](/attachment/doc/select-storage-passphrase.png)
When you're ready, press **Begin Installation**.
when you're ready, press **begin installation**.
![Installation summary ready](/attachment/doc/installation-summary-ready.png)
![installation summary ready](/attachment/doc/installation-summary-ready.png)
### Create your user account
### 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)
![account name and password](/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
## post-installation
### First boot
### 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)
![grub boot menu](/attachment/doc/grub-boot-menu.png)
Just after this screen, you will be asked to enter your encryption passphrase.
just after this screen, you will be asked to enter your encryption passphrase.
![Unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)
![unlock storage device screen](/attachment/doc/unlock-storage-device-screen.png)
### Initial Setup
### 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)
![initial setup menu](/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)
![initial setup menu configuration](/attachment/doc/initial-setup-menu-configuration.png)
Let's briefly go over the options:
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.
* **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.
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)
@ -350,46 +409,68 @@ Congratulations, you are now ready to use Qubes OS!
### Updating
Next, [update](/doc/updating-qubes-os/) 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/bulletins/) 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/bulletins/) 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/canaries/), 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/canaries/), 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/backup-restore/) 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/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/hcl/#generating-and-submitting-new-reports).
### Get Started
[Get Started](/doc/how-to-get-started/) with Qubes, check out the [How-to Guides](/doc/#how-to-guides), and learn about [Templates](/doc/#templates).
See [How to Get Started](/doc/how-to-get-started/) with Qubes, check out the
[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/doc-guidelines/) 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/doc-guidelines/) 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.

105
user/downloading-installing-upgrading/supported-versions.md
View File

@ -6,15 +6,16 @@ ref: 154
title: Supported Versions
---
This page details the level and period of support for versions of operating systems in the Qubes ecosystem.
This page details the level and period of support for versions of operating
systems in the Qubes ecosystem.
## Qubes OS
Qubes OS releases are supported for **six months** after each subsequent major
or minor release (see [Version Scheme](/doc/version-scheme/)). The current release and past major
releases are always available on the [Downloads](/downloads/) page, while all ISOs, including
past minor releases, are available from our [download mirrors](/downloads/#mirrors).
or minor release (see [Version Scheme](/doc/version-scheme/)). The current
release and past major releases are always available on the
[Downloads](/downloads/) page, while all ISOs, including past minor releases,
are available from our [download mirrors](/downloads/#mirrors).
| Qubes OS | Start Date | End Date | Status |
| ----------- | ---------- | ---------- | --------------------- |
@ -28,10 +29,12 @@ past minor releases, are available from our [download mirrors](/downloads/#mirro
### Note on point releases
Please note that point releases, such as 3.2.1 and 4.0.1, do not designate separate, new versions of Qubes OS.
Rather, they designate their respective major or minor releases, such as 3.2 and 4.0, inclusive of all package updates up to a certain point.
For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1.
Therefore, point releases are not displayed as separate rows on any of the tables on this page.
Please note that point releases, such as 3.2.1 and 4.0.1, do not designate
separate, new versions of Qubes OS. Rather, they designate their respective
major or minor releases, such as 3.2 and 4.0, inclusive of all package updates
up to a certain point. For example, installing Release 4.0 and fully updating
it results in the same system as installing Release 4.0.1. Therefore, point
releases are not displayed as separate rows on any of the tables on this page.
## Dom0
@ -49,51 +52,81 @@ The table below shows the OS used for dom0 in each Qubes OS release.
### Note on dom0 and EOL
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.).
These components are [security-critical](/doc/security-critical-code/), and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as
Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM),
and Qubes tools (gui-daemon, qrexec-daemon, etc.). These components are
[security-critical](/doc/security-critical-code/), and we provide updates for
all of them (when necessary), regardless of the support status of the base
distribution. For this reason, we consider it safe to continue using a given
base distribution in dom0 even after it has reached end-of-life (EOL).
## Templates
The following table shows select [template](/doc/templates/) versions that are currently supported.
Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) templates are officially supported by the Qubes OS Project.
[Whonix](/doc/whonix/) templates are supported by our partner, the [Whonix Project](https://www.whonix.org/).
Qubes support for each template ends when that upstream release reaches end-of-life (EOL).
Please see below for distribution-specific notes.
The following table shows select [template](/doc/templates/) versions that are
currently supported. Currently, only [Fedora](/doc/templates/fedora/) and
[Debian](/doc/templates/debian/) templates are officially supported by the
Qubes OS Project. [Whonix](/doc/whonix/) templates are supported by our
partner, the [Whonix Project](https://www.whonix.org/). Qubes support for each
template ends when that upstream release reaches end-of-life (EOL). Please see
below for distribution-specific notes.
It is the responsibility of each distribution to clearly notify its users in advance of its own EOL dates, and it is users' responsibility to heed these notices by upgrading to supported releases.
As a courtesy to Qubes users, we attempt to pass along any upstream EOL notices we receive for officially-supported templates, but our ability to do this reliably is dependent on the upstream distribution's practices.
If a distribution provides a mailing list similar to [qubes-announce](/support/#qubes-announce), which allows us to receive only very important, infrequent messages, including EOL announcements, we are much more likely to be able to pass along EOL notices to Qubes users reliably.
Qubes users can always check the EOL status of an upstream release on the upstream distribution's website (see [Fedora EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian Releases](https://wiki.debian.org/DebianReleases)).
It is the responsibility of each distribution to clearly notify its users in
advance of its own EOL dates, and it is users' responsibility to heed these
notices by upgrading to supported releases. As a courtesy to Qubes users, we
attempt to pass along any upstream EOL notices we receive for
officially-supported templates, but our ability to do this reliably is
dependent on the upstream distribution's practices. If a distribution provides
a mailing list similar to [qubes-announce](/support/#qubes-announce), which
allows us to receive only very important, infrequent messages, including EOL
announcements, we are much more likely to be able to pass along EOL notices to
Qubes users reliably. Qubes users can always check the EOL status of an
upstream release on the upstream distribution's website (see [Fedora
EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian
Releases](https://wiki.debian.org/DebianReleases)).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ---------------------------------------- | ------ |
| Release 4.0 | 33 | 9 ("stretch"),<sup>*</sup> 10 ("buster") | 15 |
| Release 4.1 | 33 | 10 ("buster") | 15 |
<sup>\*</sup> Although Debian 9 has reached regular EOL and is now in [LTS](https://wiki.debian.org/LTS), we continue to support it for Qubes R4.0.
This is a *temporary* exception to our [policy](#note-on-debian-support) of ending Qubes support at each Debian release's *regular* (not LTS) EOL date, since this policy was introduced after the release of Qubes R4.0.
In Qubes R4.1 and beyond, Qubes support for each Debian release will end when that release reaches regular EOL and will not extend into LTS.
<sup>\*</sup> Although Debian 9 has reached regular EOL and is now in
[LTS](https://wiki.debian.org/LTS), we continue to support it for Qubes R4.0.
This is a *temporary* exception to our [policy](#note-on-debian-support) of
ending Qubes support at each Debian release's *regular* (not LTS) EOL date,
since this policy was introduced after the release of Qubes R4.0. In Qubes R4.1
and beyond, Qubes support for each Debian release will end when that release
reaches regular EOL and will not extend into LTS.
### Note on Debian support
Debian releases have two EOL dates: regular and [long-term support (LTS)](https://wiki.debian.org/LTS).
See [Debian Production Releases](https://wiki.debian.org/DebianReleases#Production_Releases) for a chart that illustrates this.
Qubes support ends at the *regular* EOL date, *not* the LTS EOL date, unless a specific exception has been made.
Debian releases have two EOL dates: regular and [long-term support
(LTS)](https://wiki.debian.org/LTS). See [Debian Production
Releases](https://wiki.debian.org/DebianReleases#Production_Releases) for a
chart that illustrates this. Qubes support ends at the *regular* EOL date,
*not* the LTS EOL date, unless a specific exception has been made.
### Note on Whonix support
[Whonix](/doc/whonix/) 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.
[Whonix](/doc/whonix/) 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 versions of Qubes OS and Whonix templates within a month of their respective releases.
To be precise:
This policy requires Whonix template users to stay reasonably close to the
cutting edge by upgrading to new stable versions 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 version 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 version within one month of its release.
* One month after a new stable version of Qubes OS is released, Whonix
templates will no longer be supported on any older version 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 version within one month of its
release.
* One month after new stable versions of Whonix templates are released, older versions 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 versions within one month of their release.
* One month after new stable versions of Whonix templates are released, older
versions 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 versions 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.
We aim to announce both types of events one month in advance in order to remind
users to upgrade.

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

@ -11,13 +11,16 @@ ref: 142
title: System Requirements
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Notice:</b>
The system requirements on this page are <em>necessary, but not sufficient,</em> for Qubes compatibility at a minimal or recommended level.
In other words, just because a computer satisfies these requirements doesn't mean that Qubes will successfully install and run on it.
We strongly recommend consulting the <a href="/hcl/">Hardware Compatibility List</a> to verify that Qubes can install and run on your specific model in the ways you need it to.
The system requirements on this page are <em>necessary, but not
sufficient,</em> for Qubes compatibility at a minimal or recommended level.
In other words, just because a computer satisfies these requirements doesn't
mean that Qubes will successfully install and run on it. We strongly
recommend consulting the <a href="/hcl/">Hardware Compatibility List</a> to
verify that Qubes can install and run on your specific model in the ways you
need it to.
</div>
## Minimum
@ -37,32 +40,48 @@ title: System Requirements
- **Storage:** 128 GB free space
- High-speed solid-state drive strongly recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant [troubleshooting](/doc/install-nvidia-driver/)
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and earlier) generally work well
- Nvidia GPUs may require significant
[troubleshooting](/doc/install-nvidia-driver/)
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and
earlier) generally work well
- **Peripherals:** A non-USB keyboard or multiple USB controllers
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for [Anti Evil Maid](/doc/anti-evil-maid/))
- **Other:** Satisfaction of all [hardware certification requirements for Qubes 4.x](/news/2016/07/21/new-hw-certification-for-q4/)
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for
[Anti Evil Maid](/doc/anti-evil-maid/))
- **Other:** Satisfaction of all [hardware certification requirements for Qubes
4.x](/news/2016/07/21/new-hw-certification-for-q4/)
## Choosing Hardware
- Please see the [Hardware Compatibility List](/hcl/) for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here](/doc/hcl/).)
- Please see the [Hardware Compatibility List](/hcl/) for a compilation of
hardware reports generated and submitted by users across various Qubes
versions. (For more information about the HCL itself, see [here](/doc/hcl/).)
- See the [Certified Hardware](/doc/certified-hardware/) page.
- See the [Hardware Testing](/doc/hardware-testing/) page.
## Important Notes
- **Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).**
- Qubes **can** be installed on systems which do not meet the recommended requirements.
Such systems will still offer significant security improvements over traditional operating systems, since things like GUI isolation and kernel protection do not require special hardware.
- Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this.
(As a reminder, its capacity must be at least 32 GiB.)
Simply plug the flash drive into the computer before booting into the Qubes installer from a separate installation medium, choose the flash drive as the target installation disk, and proceed with the installation normally.
After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes.
In addition to the convenience of having a portable copy of Qubes, this allows users to test for hardware compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase.
(See [hcl-report](/doc/hcl/#generating-and-submitting-new-reports) for advice on hardware compatibility testing.)
Remember to change the devices assigned to your NetVM and USB VM if you move between different machines.
- [Advice on finding a VT-d capable notebook](https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J).
- You can check whether an Intel processor has VT-x and VT-d on [ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
- **Installing Qubes in a virtual machine is not recommended, as it uses its
own bare-metal hypervisor (Xen).**
- Qubes **can** be installed on systems which do not meet the recommended
requirements. Such systems will still offer significant security improvements
over traditional operating systems, since things like GUI isolation and
kernel protection do not require special hardware.
- Qubes **can** be installed on a USB flash drive or external disk, and testing
has shown that this works very well. A fast USB 3.0 flash drive is
recommended for this. (As a reminder, its capacity must be at least 32 GiB.)
Simply plug the flash drive into the computer before booting into the Qubes
installer from a separate installation medium, choose the flash drive as the
target installation disk, and proceed with the installation normally. After
Qubes has been installed on the flash drive, it can then be plugged into
other computers in order to boot into Qubes. In addition to the convenience
of having a portable copy of Qubes, this allows users to test for hardware
compatibility on multiple machines (e.g., at a brick-and-mortar computer
store) before deciding on which computer to purchase. (See
[hcl-report](/doc/hcl/#generating-and-submitting-new-reports) for advice on
hardware compatibility testing.) Remember to change the devices assigned to
your NetVM and USB VM if you move between different machines.
- [Advice on finding a VT-d capable
notebook](https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J).
- You can check whether an Intel processor has VT-x and VT-d on
[ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).

28
user/how-to-guides/backup-emergency-restore-v4.md
View File

@ -21,21 +21,22 @@ any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt](https://www.tarsnap.com/scrypt.html). You
will need a copy of this utility in order to access your data. Since `scrypt`
is not pre-installed on every GNU/Linux system, it is strongly recommended that
you store a copy of it with your backups. If your distribution has `scrypt`
packaged (e.g., Debian), you can install the package in the standard way using
your distribution's package manager. Otherwise, you'll need to obtain a
compiled binary (instructions below) or compile the program from source
yourself. (Don't forget to [verify signatures](/security/verifying-signatures) first!) Note that versions of
`scrypt` up to 1.2.0 (inclusive) do not support the `-P` option for easier
scripting, which means you'll need to enter the passphrase for each file
In Qubes 4.X, backups are encrypted and integrity-protected with
[scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
utility in order to access your data. Since `scrypt` is not pre-installed on
every GNU/Linux system, it is strongly recommended that you store a copy of it
with your backups. If your distribution has `scrypt` packaged (e.g., Debian),
you can install the package in the standard way using your distribution's
package manager. Otherwise, you'll need to obtain a compiled binary
(instructions below) or compile the program from source yourself. (Don't forget
to [verify signatures](/security/verifying-signatures) first!) Note that
versions of `scrypt` up to 1.2.0 (inclusive) do not support the `-P` option for
easier scripting, which means you'll need to enter the passphrase for each file
separately, instead of using `echo ... | scrypt`.
Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work on
any GNU/Linux system.
uses an RPM-based system (Fedora), but the same general procedure should work
on any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key](/security/verifying-signatures/#2-get-the-release-signing-key).
2. If you're not on Qubes 4.X, import the Release 4 Signing Key.
@ -143,7 +144,8 @@ Emergency Recovery Instructions
[user@restore ~]$ backup_id=20161020T123455-1234
6. Verify the integrity of your data, decrypt, decompress, and extract `private.img`:
6. Verify the integrity of your data, decrypt, decompress, and extract
`private.img`:
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \

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

@ -11,23 +11,27 @@ ref: 199
title: How to Back Up, Restore, and Migrate
---
With Qubes, it's easy and secure to back up and restore your whole system, as
well as to migrate between two physical machines.
With Qubes, it's easy and secure to back up and restore your whole system, as well as to migrate between two physical machines.
These functions are integrated into the Qube Manager. There are also two
command-line tools available that perform the same functions: `qvm-backup` and
`qvm-backup-restore`.
These functions are integrated into the Qube Manager.
There are also two command-line tools available that perform the same functions: `qvm-backup` and `qvm-backup-restore`.
It's extremely important to make regular backups of all the data you care about.
This is true of all computing, not just the use of Qubes.
Data loss can and does occur in myriad and unexpected ways.
A standard recommendation is to make backups at least weekly: three copies in two different formats, one off-site.
It's extremely important to make regular backups of all the data you care
about. This is true of all computing, not just the use of Qubes. Data loss can
and does occur in myriad and unexpected ways. A standard recommendation is to
make backups at least weekly: three copies in two different formats, one
off-site.
Backing up changes to dom0
--------------------------
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up.
Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup.
Here is an example of how to back up Qubes config files and RPC policies:
When backing up dom0 using the Qubes backup tool (explained below), only the
home directory is backed up. Therefore, if there are files outside of the home
directory you wish to save, you should copy them into the home directory prior
to creating a backup. Here is an example of how to back up Qubes config files
and RPC policies:
```
$ mkdir -p ~/backup/etc/qubes/
@ -36,106 +40,149 @@ $ mkdir ~/backup/etc/qubes-rpc/
$ cp -a /etc/qubes-rpc/* ~/systemfiles/etc/qubes-rpc/
```
To restore these files, move them from the restored directory in dom0's home back to their appropriate locations in `/etc/`.
Please note that any packages installed via the package manager in dom0 will not be backed up.
Such packages will have to be reinstalled through the package manager when restoring on a fresh installation.
To restore these files, move them from the restored directory in dom0's home
back to their appropriate locations in `/etc/`. Please note that any packages
installed via the package manager in dom0 will not be backed up. Such packages
will have to be reinstalled through the package manager when restoring on a
fresh installation.
Creating a backup
-----------------
1. Go to **Applications menu -> System Tools -> Backup Qubes**.
This brings up the **Qubes Backup VMs** window.
1. Go to **Applications menu -> System Tools -> Backup Qubes**. This brings up
the **Qubes Backup VMs** window.
2. Move the VMs that you want to back up to the right-hand **Selected** column.
VMs in the left-hand **Available** column will not be backed up.
You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
Normally this should be left on unless you have a specific reason otherwise.
You may choose whether to compress backups by checking or unchecking the
**Compress the backup** box. Normally this should be left on unless you have
a specific reason otherwise.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target app qube**.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
If you wish to send your backup to a (currently running) VM, select the VM
in the drop-down box next to **Target app qube**. If you wish to send your
backup to a [USB mass storage device](/doc/usb/), you can use the directory
selection widget to mount a connected device (under "Other locations" item
on the left); or first mount the device in a VM, then select the mount point
inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
This destination directory must already exist.
If it does not exist, you must create it manually prior to backing up.
You must also specify a directory on the device or in the VM, or a command
to be executed in the VM as a destination for your backup. For example, if
you wish to send your backup to the `~/backups` folder in the target VM, you
would simply browse to it using the convenient directory selection dialog
(`...`) at the right. This destination directory must already exist. If it
does not exist, you must create it manually prior to backing up.
By specifying the appropriate directory as the destination in a VM, it is possible to send the backup directly to, e.g., a USB mass storage device attached to the VM.
Likewise, it is possible to enter any command as a backup target by specifying the command as the destination in the VM.
This can be used to send your backup directly to, e.g., a remote server using SSH.
By specifying the appropriate directory as the destination in a VM, it is
possible to send the backup directly to, e.g., a USB mass storage device
attached to the VM. Likewise, it is possible to enter any command as a
backup target by specifying the command as the destination in the VM. This
can be used to send your backup directly to, e.g., a remote server using
SSH.
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
**Note:** The supplied passphrase is used for **both** encryption/decryption
and integrity verification.
At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box.
At this point, you may also choose whether to save your settings by checking
or unchecking the **Save settings as default backup profile** box.
**Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
**Warning: Saving the settings will result in your backup passphrase being
saved in plaintext in dom0, so consider your threat model before checking
this box.**
4. You will now see the summary of VMs to be backed up.
If there are any issues preventing the backup, they will be listed here and the **Next** button grayed out.
4. You will now see the summary of VMs to be backed up. If there are any issues
preventing the backup, they will be listed here and the **Next** button
grayed out.
5. When you are ready, click **Next**.
Qubes will proceed to create your backup.
Once the progress bar has completed, you may click **Finish**.
5. When you are ready, click **Next**. Qubes will proceed to create your
backup. Once the progress bar has completed, you may click **Finish**.
6. Test restore your backup.
Follow the [restore procedure](#restoring-from-a-backup), selecting **Verify backup integrity, do not restore the data**.
This step is optional but strongly recommended.
A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
6. Test restore your backup. Follow the [restore
procedure](#restoring-from-a-backup), selecting **Verify backup integrity,
do not restore the data**. This step is optional but strongly recommended. A
backup is useless if you can't restore your data from it, and you can't be
sure that your backup is good until you try to restore.
Restoring from a backup
-----------------------
1. Go to **Applications menu -> System Tools -> Restore Backup**.
This brings up the **Qubes Restore VMs** window.
1. Go to **Applications menu -> System Tools -> Restore Backup**. This brings
up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **app qube**.
- If your backup is located on a [USB mass storage device](/doc/usb/),
attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in
the drop-down box next to **app qube**.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click it or select it and hit **OK**.
You must also specify the directory and filename of the backup (or a command
to be executed in a VM) in the **Backup file** field. If you followed the
instructions in the previous section, "Creating a Backup," then your backup
is most likely in the location you chose as the destination in step 3. For
example, if you had chosen the `~/backups` directory of a VM as your
destination in step 3, you would now select the same VM and again browse to
(using `...`) the `backups` folder. Once you've located the backup file,
double-click it or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or template that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file.
See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
1. **ignore missing templates and net VMs**: If any of the VMs in your
backup depended upon a NetVM or template that is not present in (i.e.,
"missing from") the current system, checking this box will ignore the fact
that they are missing and restore the VMs anyway and set them to use the
default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration
of dom0's home directory. If your backup was created on a Qubes system which
had a different dom0 username than the dom0 username of the current system,
then checking this box will ignore the mismatch between the two usernames
and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the
backup file for corrupted data. However, it does not currently detect if it
is missing data as long as it is a correctly structured, non-corrupted
backup file. See [issue
#3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more
details.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
4. If your backup is encrypted, you must check the **Encrypted backup** box. If
a passphrase was supplied during the creation of your backup (regardless of
whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created is used for **both** encryption/decryption and integrity verification.
If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
All backups made from a Qubes R4.0 system will be encrypted.
**Note:** The passphrase which was supplied when the backup was created is
used for **both** encryption/decryption and integrity verification. If the
backup was not encrypted, the supplied passphrase is used only for integrity
verification. All backups made from a Qubes R4.0 system will be encrypted.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
5. You will now see the summary of VMs to be restored. If there are any issues
preventing the restore, they will be listed here and the **Next** button grayed
out.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
6. When you are ready, click **Next**. Qubes will proceed to restore from your
backup. Once the progress bar has completed, you may click **Finish**.
**Note:** When restoring from a dom0 backup, a new directory will be created in the current dom0 home directory, and the contents from the backup will be placed inside this new directory.
This is intentional, as it allows users to have explicit control over which files and settings get applied in dom0.
If the contents from the dom0 backup were instead to overwrite the existing files in dom0's home directory, unexpected and undesired configuration changes could 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 in dom0, depending on exactly which files you're adding and replacing.
**Note:** When restoring from a dom0 backup, a new directory will be created in
the current dom0 home directory, and the contents from the backup will be
placed inside this new directory. This is intentional, as it allows users to
have explicit control over which files and settings get applied in dom0. If the
contents from the dom0 backup were instead to overwrite the existing files in
dom0's home directory, unexpected and undesired configuration changes could
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
in dom0, depending on exactly which files you're adding and replacing.
Emergency backup recovery without qubes
---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind.
No special Qubes-specific tools are required to access data backed up by Qubes.
In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
The Qubes backup system has been designed with emergency disaster recovery in
mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure.
Refer to the following for emergency restore of a backup created on:
@ -146,25 +193,37 @@ Refer to the following for emergency restore of a backup created on:
Migrating between two physical machines
---------------------------------------
In order to migrate your Qubes system from one physical machine to another, simply follow the backup procedure on the old machine, [install Qubes](/downloads/) on the new machine, and follow the restoration procedure on the new machine.
All of your settings and data will be preserved!
In order to migrate your Qubes system from one physical machine to another,
simply follow the backup procedure on the old machine, [install
Qubes](/downloads/) on the new machine, and follow the restoration procedure on
the new machine. All of your settings and data will be preserved!
Choosing a backup passphrase
----------------------------
Here are some things to consider when selecting a passphrase for your backups:
- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
If your system drive decryption passphrase is already sufficiently strong, it may not.)
- An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
- If you plan to store the backup for a long time or on third-party servers,
you should make sure to use a very long, high-entropy passphrase. (Depending
on the decryption passphrase you use for your system drive, this may
necessitate selecting a stronger passphrase. If your system drive decryption
passphrase is already sufficiently strong, it may not.)
- An adversary who has access to your backups may try to substitute one backup
for another. For example, when you attempt to retrieve a recent backup, the
adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a
different passphrase for each backup, e.g., by appending a number or date to
the passphrase.
- If you're forced to enter your system drive decryption passphrase in plain
view of others (where it can be shoulder-surfed), then you may want to use a
different passphrase for your backups (even if your system drive decryption
passphrase is already maximally strong). On the other hand, if you're careful
to avoid shoulder-surfing and/or have a passphrase that's difficult to detect
via shoulder-surfing, then this may not be a problem for you.
Notes
-----
Notes -----
- For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
- If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).
- For the technical details of the backup system, please refer to [this
thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
- If working with symlinks, note the issues described in [this
thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

182
user/how-to-guides/how-to-get-started.md
View File

@ -12,68 +12,140 @@ ref: 190
title: How to Get Started
---
After [downloading](/downloads/) and [installing](/doc/installation-guide/) Qubes OS, it's time to dive in and get to work!
After [downloading](/downloads/) and [installing](/doc/installation-guide/)
Qubes OS, it's time to dive in and get to work!
## The Basics
Qubes OS is an operating system built out of securely-isolated compartments called **qubes**. For example, you might have a work qube, a personal qube, a banking qube, a web browsing qube, and so on. You can have as many qubes as you want!
Most of the time, you'll be using an **app qube**, which is a qube intended for running software programs like web browsers, email clients, and word processors. Each app qube is based on a **template qube**. More than one qube can be based on the same template. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is successful, the damage is limited to a single qube.
Qubes OS is an operating system built out of securely-isolated compartments
called **qubes**. For example, you might have a work qube, a personal qube, a
banking qube, a web browsing qube, and so on. You can have as many qubes as you
want! Most of the time, you'll be using an **app qube**, which is a qube
intended for running software programs like web browsers, email clients, and
word processors. Each app qube is based on a **template qube**. More than one
qube can be based on the same template. Importantly, a qube cannot modify its
template in any way. This means that, if a qube is ever compromised, its
template and any other qubes based on that template will remain safe. This is
what makes Qubes OS so secure. Even if an attack is successful, the damage is
limited to a single qube.
Suppose you want to use your favorite web browser in several different qubes. You'd install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only have to install the web browser a single time, and updating the template serves to update all the qubes based on it. This elegant design saves time and space while enhancing security.
Suppose you want to use your favorite web browser in several different qubes.
You'd install the web browser in a template, then every qube based on that
template would be able to run the web browser software (while still being
forbidden from modifying the template and any other qubes). This way, you only
have to install the web browser a single time, and updating the template serves
to update all the qubes based on it. This elegant design saves time and space
while enhancing security.
There are also some "helper" qubes in your system. Each qube that connects to the Internet does so through a network-providing **service qube**. If you need to access USB devices, another service qube will do that. There's also a **management qube** that automatically handles a lot of background housekeeping. For the most part, you won't have to worry about it, but it's nice to know that it's there.
As with app qubes, service qubes and management qubes are also based on templates. Templates are usually named after their operating system (often a [Linux distribution](https://en.wikipedia.org/wiki/Linux_distribution)) and corresponding version number. There are many ready-to-use [templates](/doc/templates) to choose from, and you can download and have as many as you like.
There are also some "helper" qubes in your system. Each qube that connects to
the Internet does so through a network-providing **service qube**. If you need
to access USB devices, another service qube will do that. There's also a
**management qube** that automatically handles a lot of background
housekeeping. For the most part, you won't have to worry about it, but it's
nice to know that it's there. As with app qubes, service qubes and management
qubes are also based on templates. Templates are usually named after their
operating system (often a [Linux
distribution](https://en.wikipedia.org/wiki/Linux_distribution)) and
corresponding version number. There are many ready-to-use
[templates](/doc/templates) to choose from, and you can download and have as
many as you like.
Last but not least, there's a very special **admin qube** which, as the name suggests, is used to administer your entire system. There's only one admin qube, and it's called **dom0**. You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. Dom0 is more trusted than any other qube. If dom0 were ever compromised, it would be "game over." The entire system would effectively be compromised. That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't happen.
Due to its overarching importance, dom0 has no network connectivity and is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications in dom0. (That's what your app qubes are for!)
Last but not least, there's a very special **admin qube** which, as the name
suggests, is used to administer your entire system. There's only one admin
qube, and it's called **dom0**. You can think of it as the master qube, holding
ultimate power over everything that happens in Qubes OS. Dom0 is more trusted
than any other qube. If dom0 were ever compromised, it would be "game over."
The entire system would effectively be compromised. That's why everything in
Qubes OS is specifically designed to protect dom0 and ensure that doesn't
happen. Due to its overarching importance, dom0 has no network connectivity and
is used only for running the [desktop
environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window
manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be
used for anything else. In particular, you should never run user applications
in dom0. (That's what your app qubes are for!)
### Color & Security
You'll choose a **color** for each of your qubes out of a predefined set of colors. Each window on your desktop will have its frame colored according to the color of that qube. These colored frames help you keep track of which qube each window belongs to and how trustworthy it is. This is especially helpful when you have the same app running in multiple qubes at the same time. For example, if you're logged in to your bank account in one qube while doing some random web surfing in a different qube, you wouldn't want to accidentally enter your banking password in the latter! The colored frames help to avoid such mistakes.
You'll choose a **color** for each of your qubes out of a predefined set of
colors. Each window on your desktop will have its frame colored according to
the color of that qube. These colored frames help you keep track of which qube
each window belongs to and how trustworthy it is. This is especially helpful
when you have the same app running in multiple qubes at the same time. For
example, if you're logged in to your bank account in one qube while doing some
random web surfing in a different qube, you wouldn't want to accidentally enter
your banking password in the latter! The colored frames help to avoid such
mistakes.
[![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png)
Most Qubes users associate red with what's untrusted and dangerous (like a red light: stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle. This color scheme also extends to include blue and black, which are usually interpreted as indicating progressively more trusted domains than green, with black being ultimately trusted.
Color and associated meanings are ultimately up to you, however. The system itself does not treat the colors differently. If you create two identical qubes --- black and red, say --- they'll be the same until you start using them differently. Feel free to use the colors in whatever way is most useful to you. For example, you might decide to use three or four qubes for work activities and give them all the same color --- or all different colors. It's entirely up to you.
Most Qubes users associate red with what's untrusted and dangerous (like a red
light: stop! danger!), green with what's safe and trusted, and yellow and
orange with things in the middle. This color scheme also extends to include
blue and black, which are usually interpreted as indicating progressively more
trusted domains than green, with black being ultimately trusted. Color and
associated meanings are ultimately up to you, however. The system itself does
not treat the colors differently. If you create two identical qubes --- black
and red, say --- they'll be the same until you start using them differently.
Feel free to use the colors in whatever way is most useful to you. For example,
you might decide to use three or four qubes for work activities and give them
all the same color --- or all different colors. It's entirely up to you.
### User Interface
On operating systems like Windows and macOS, the desktop environment is unchangeable and part of that operating system. With Linux, any of a number of desktop environments are an option. Qubes OS is installed with XFCE as its default desktop environment, but it also supports KDE, as well as the i3 and awesome window managers.
On operating systems like Windows and macOS, the desktop environment is
unchangeable and part of that operating system. With Linux, any of a number of
desktop environments are an option. Qubes OS is installed with XFCE as its
default desktop environment, but it also supports KDE, as well as the i3 and
awesome window managers.
[![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png)
The bar at the top of your screen in Qubes 4.0 includes the following XFCE component areas:
The bar at the top of your screen in Qubes 4.0 includes the following XFCE
component areas:
- The **Tray**, where many functional widgets live.
- **Spaces**, an interface for [virtual desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things.
- **Spaces**, an interface for [virtual
desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops
do not have any inherent security isolation properties, but some users find
them useful for organizing things.
- The **Task Bar** where buttons for open and hidden windows live.
- The **App Menu**, where you go to open an application within a qube, to open a dom0 terminal, to access administrative UI tools such as the Qube Manager, or to access settings panels for your desktop environment.
- The **App Menu**, where you go to open an application within a qube, to open
a dom0 terminal, to access administrative UI tools such as the Qube Manager,
or to access settings panels for your desktop environment.
To learn more about how to customize your desktop environment, we recommend you spend some time going through [XFCE's documentation](https://docs.xfce.org/).
To learn more about how to customize your desktop environment, we recommend you
spend some time going through [XFCE's documentation](https://docs.xfce.org/).
There are several Tray widgets that are custom to Qubes OS:
- The **Qubes Domains** widget allows you to manage running qubes, turn them on and off, and monitor memory usage.
- The **Qubes Devices** widget allows you to attach and detach devices --- such as USB drives and cameras --- to qubes.
- The **Qubes Disk Space Monitor** will notify you if you're ever running out of disk space.
- The **Qubes Domains** widget allows you to manage running qubes, turn them
on and off, and monitor memory usage.
- The **Qubes Devices** widget allows you to attach and detach devices ---
such as USB drives and cameras --- to qubes.
- The **Qubes Disk Space Monitor** will notify you if you're ever running out
of disk space.
- The **Qubes Update** tool will inform you when updates are available.
[![q40_widgets.png](/attachment/doc/r4.0-q40_widgets.png)](/attachment/doc/r4.0-q40_widgets.png)
To see all of your qubes at the same time, you can use the **Qube Manager** (go to the App Menu → System Tools → Qube Manager), which displays the states of all the qubes in your system, even the ones that aren't running.
To see all of your qubes at the same time, you can use the **Qube Manager** (go
to the App Menu → System Tools → Qube Manager), which displays the states of
all the qubes in your system, even the ones that aren't running.
[![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png)
#### Command-line interface
All aspects of Qubes OS can be controlled using command-line tools. Opening a terminal emulator in dom0 can be done in several ways:
All aspects of Qubes OS can be controlled using command-line tools. Opening a
terminal emulator in dom0 can be done in several ways:
- Go to the App Menu and select **Terminal Emulator** at the top.
- Press <kbd>Alt</kbd>+<kbd>F3</kbd> and search for `xfce terminal`.
- Right-click on the desktop and select **Open Terminal Here**.
Terminal emulators can also be run in other qubes as normal programs.
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Terminal emulators can also be run in other qubes as normal programs. Various
command-line tools are described as part of this guide, and the whole reference
can be found [here](/doc/tools/).
## First boot
@ -82,13 +154,23 @@ When you install Qubes OS, a number of qubes are pre-configured for you:
- **Templates:** `fedora-XX` (`XX` being the version number)
- **Admin qube:** `dom0`
- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`
- **App qubes** configured to prioritize security by compartmentalizing tasks and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is nothing special about these qubes. If you were to create a black qube and name it `vault`, it would be the same as the pre-configured `vault` qube. They're just suggestions to get you started. )
- **App qubes** configured to prioritize security by compartmentalizing tasks
and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is
nothing special about these qubes. If you were to create a black qube and
name it `vault`, it would be the same as the pre-configured `vault` qube.
They're just suggestions to get you started. )
A variety of open-source applications such as file managers, command-line terminals, printer managers, text editors, and "applets" used to configure different things like audio or parts of the user interface are also installed by default—most within the templates. Most are bundled with each template.
A variety of open-source applications such as file managers, command-line
terminals, printer managers, text editors, and "applets" used to configure
different things like audio or parts of the user interface are also installed
by default—most within the templates. Most are bundled with each template.
### Adding, removing, and listing qubes
You can easily create a new qube with the **Create Qubes VM** option in the App Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add** and **Remove** buttons. You can also add, remove, and list qubes from the command line using the following tools:
You can easily create a new qube with the **Create Qubes VM** option in the App
Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add**
and **Remove** buttons. You can also add, remove, and list qubes from the
command line using the following tools:
- `qvm-create`
- `qvm-remove`
@ -96,21 +178,39 @@ You can easily create a new qube with the **Create Qubes VM** option in the App
### How many qubes do I need?
That's a great question, but there's no one-size-fits-all answer. It depends on the structure of your digital life, and this is at least a little different for everyone. If you plan on using your system for work, then it also depends on what kind of job you do.
That's a great question, but there's no one-size-fits-all answer. It depends on
the structure of your digital life, and this is at least a little different for
everyone. If you plan on using your system for work, then it also depends on
what kind of job you do.
It's a good idea to start out with the qubes created automatically by the installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it. You'll also be able to easily [copy any files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
It's a good idea to start out with the qubes created automatically by the
installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start
to feel that some activity just doesn't fit into any of your existing qubes, or
you want to partition some part of your life, you can easily create a new qube
for it. You'll also be able to easily [copy any
files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
Still not sure? You might find it helpful to read [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html), which describes how one of the Qubes OS architects partitioned her digital life into security domains.
Still not sure? You might find it helpful to read [this
article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html),
which describes how one of the Qubes OS architects partitioned her digital life
into security domains.
## Secure Habits
It is *very important* to [keep Qubes updated](/doc/how-to-update/) to ensure you have the latest security updates. Frequently updating is one of the best ways to remain secure against new threats.
It is *very important* to [keep Qubes updated](/doc/how-to-update/) to ensure
you have the latest security updates. Frequently updating is one of the best
ways to remain secure against new threats.
It's also *very 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's also *very 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.
## How-to Guides
Here are some basic tasks you're likely to want to perform often that are unique to Qubes as a multi-environment system. A full list is available in the [How-to Guides](/doc/#how-to-guides) section in the docs.
Here are some basic tasks you're likely to want to perform often that are
unique to Qubes as a multi-environment system. A full list is available in the
[How-to Guides](/doc/#how-to-guides) section in the docs.
- [How to Update](/doc/how-to-update/)
- [How to Back Up, Restore, and Migrate](/doc/how-to-back-up-restore-and-migrate/)
@ -120,16 +220,26 @@ Here are some basic tasks you're likely to want to perform often that are unique
- [How to Install Software](/doc/how-to-install-software/)
- [How to Use Devices (block storage, USB, and PCI devices)](/doc/how-to-use-devices/)
If you encounter any problems, please visit the [Help, Support, Mailing Lists, and Forum](/support/) page.
If you encounter any problems, please visit the [Help, Support, Mailing Lists,
and Forum](/support/) page.
## Compatible Hardware
Make sure your hardware satisfies the [system requirements](/doc/system-requirements/), as Qubes OS cannot run on every type of computer. You may also want to check out [Qubes-certified Hardware](/doc/certified-hardware/) and take a look at the [Hardware Compatibility List (HCL)](/hcl/).
Make sure your hardware satisfies the [system
requirements](/doc/system-requirements/), as Qubes OS cannot run on every type
of computer. You may also want to check out [Qubes-certified
Hardware](/doc/certified-hardware/) and take a look at the [Hardware
Compatibility List (HCL)](/hcl/).
## Downloads
[Download an ISO](/downloads/), learn how to [verify its authenticity](/doc/verifying-signatures/), and follow our [guide to install Qubes OS](/doc/installation-guide/). Looking for the [source code](/doc/source-code/)? You'll find it [on GitHub](https://github.com/QubesOS).
[Download an ISO](/downloads/), learn how to [verify its
authenticity](/doc/verifying-signatures/), and follow our [guide to install
Qubes OS](/doc/installation-guide/). Looking for the [source
code](/doc/source-code/)? You'll find it [on
GitHub](https://github.com/QubesOS).
## Documentation
Peruse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)!
Peruse our extensive library of [documentation](/doc/) for users and developers
of Qubes OS. You can even [help us improve it](/doc/doc-guidelines/)!

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

@ -8,27 +8,38 @@ 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-versions/#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-versions/#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/).*
<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>
## 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/bulletins/) 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.
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/bulletins/) 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](#security-updates), as well as the latest
non-security enhancements and bug fixes.
Fully updating your Qubes OS system means updating:
@ -40,35 +51,62 @@ You can accomplish this using the **Qubes Update** tool.
[![Qubes Update](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)
By default, the Qubes Update tool will appear as an icon in the Notification Area when updates are available.
By default, the Qubes Update tool will appear as an icon in the Notification
Area when updates are available.
[![Qube Updates Available](/attachment/doc/r4.0-qube-updates-available.png)](/attachment/doc/r4.0-qube-updates-available.png)
However, you can also start the tool manually by selecting it in the Applications Menu under "System Tools."
Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting "Enable updates for qubes without known available updates," then selecting all desired items from the list and clicking "Next."
However, you can also start the tool manually by selecting it in the
Applications Menu under "System Tools." Even if no updates have been detected,
you can use this tool to check for updates manually at any time by selecting
"Enable updates for qubes without known available updates," then selecting all
desired items from the list and clicking "Next."
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Advanced users and developers:</b> For the command-line equivalents of using the <b>Qubes Update</b> tool, see the Salt formulae <a href="/doc/salt/#updatequbes-dom0"><code>update.qubes-dom0</code></a> and <a href="/doc/salt/#updatequbes-vm"><code>update.qubes-vm</code></a>. For enabling testing repos, see <a href="/doc/testing/">Testing new releases and updates</a>.
<b>Advanced users and developers:</b> For the command-line equivalents of
using the <b>Qubes Update</b> tool, see the Salt formulae <a
href="/doc/salt/#updatequbes-dom0"><code>update.qubes-dom0</code></a> and <a
href="/doc/salt/#updatequbes-vm"><code>update.qubes-vm</code></a>. For
enabling testing repos, see <a href="/doc/testing/">Testing new releases and
updates</a>.
</div>
## Upgrading to stay on a supported release
The above covers updating *within* a given operating system release.
Eventually, however, most operating system releases will reach [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life), after which point they will no longer be supported.
This applies to [Qubes OS itself](/doc/supported-versions/#qubes-os) as well as operating systems used for templates and standalones, such as [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/).
It is very important to use only supported releases, since generally only supported releases receive security updates.
This means that you must periodically upgrade to a newer release before your current release reaches EOL.
Eventually, however, most operating system releases will reach [end-of-life
(EOL)](https://fedoraproject.org/wiki/End_of_life), after which point they will
no longer be supported. This applies to [Qubes OS
itself](/doc/supported-versions/#qubes-os) as well as operating systems used
for templates and standalones, such as [Fedora](/doc/templates/fedora/) and
[Debian](/doc/templates/debian/). It is very important to use only supported
releases, since generally only supported releases receive security updates.
This means that you must periodically upgrade to a newer release before your
current release reaches EOL.
In the case of Qubes OS itself, we will always [announce](/news/categories/#releases) when a given Qubes OS release is approaching and has reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
Again, you can always see the current support status for all Qubes OS releases [here](/doc/supported-versions/#qubes-os).
In the case of Qubes OS itself, we will always
[announce](/news/categories/#releases) when a given Qubes OS release is
approaching and has reached EOL, and we will provide [instructions for
upgrading to the next stable supported Qubes OS release](/doc/upgrade/). Again,
you can always see the current support status for all Qubes OS releases
[here](/doc/supported-versions/#qubes-os).
Periodic upgrades are also important for templates and standalones.
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 operating system reaches EOL from the upstream project that maintains it, but we also make EOL [announcements](/news/categories/#announcements) and publish guides for official template operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides](/doc/templates/fedora/#upgrading) and the [Debian upgrade guides](/doc/templates/debian/#upgrading)).
Periodic upgrades are also important for templates and standalones. 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
operating system reaches EOL from the upstream project that maintains it, but
we also make EOL [announcements](/news/categories/#announcements) and publish
guides for official template operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a
supported version of that operating system (see the [Fedora upgrade
guides](/doc/templates/fedora/#upgrading) and the [Debian upgrade
guides](/doc/templates/debian/#upgrading)).
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-versions/#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-versions/#note-on-dom0-and-eol).

173
user/reference/glossary.md
View File

@ -10,127 +10,140 @@ ref: 140
title: Glossary
---
app qube
--------
## app qube
Any [qube](#qube) that depends on a [template](#template) for its root filesystem.
Any [qube](#qube) that depends on a [template](#template) for its root
filesystem.
* Historical note: This term originally meant "a qube intended for running user software applications" (hence the name "app").
* Historical note: This term originally meant "a qube intended for running user
software applications" (hence the name "app").
* Historical note: This is the preferred term replacing the deprecated term "app qube."
* Historical note: This is the preferred term replacing the deprecated term
"app qube."
disposable
----------
## disposable
See [Dispoables](/doc/how-to-use-disposables/).
A temporary [app qube](#app-qube) based on a [disposable template](#disposable-template) that can quickly be created, used, and destroyed.
See [Dispoables](/doc/how-to-use-disposables/). A temporary [app
qube](#app-qube) based on a [disposable template](#disposable-template) that
can quickly be created, used, and destroyed.
disposable template
-------------------
## disposable template
A type of [app qube](#app-qube) on which [disposables](#disposable) are based.
(Not to be confused with the concept of a [template](#template) that is itself disposable, which does not exist in Qubes OS.)
(Not to be confused with the concept of a [template](#template) that is itself
disposable, which does not exist in Qubes OS.)
Disposable templates are not [templates](#template), since (being app qubes) they do not have root filesystems of their own to provide to other qubes.
Rather, disposable templates are complementary to templates insofar as disposable templates provide their own user filesystems to the disposables based on them.
Disposable templates are not [templates](#template), since (being app qubes)
they do not have root filesystems of their own to provide to other qubes.
Rather, disposable templates are complementary to templates insofar as
disposable templates provide their own user filesystems to the disposables
based on them.
dom0
----
## dom0
[Domain](#domain) Zero.
Also known as the **host** domain, dom0 is the initial qube started by the Xen hypervisor on boot.
Dom0 runs the Xen management toolstack and has special privileges relative to other domains, such as direct access to most hardware.
[Domain](#domain) Zero. Also known as the **host** domain, dom0 is the initial
qube started by the Xen hypervisor on boot. Dom0 runs the Xen management
toolstack and has special privileges relative to other domains, such as direct
access to most hardware.
* The term "dom0" is not a proper noun and should not be capitalized (unless it's the first word in a sentence, for example).
* The term "dom0" is not a proper noun and should not be capitalized (unless
it's the first word in a sentence, for example).
* The use of [domain](#domain) as a synonym for [VM](#vm) is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).
* The use of [domain](#domain) as a synonym for [VM](#vm) is specific to Xen.
Qubes diverges from this practice. See: [domain](#domain).
domain
------
## domain
_This term is deprecated in the context of Qubes OS._
In Xen, a synonym for [VM](#vm). See ["domain" on the Xen Wiki](https://wiki.xenproject.org/wiki/Domain).
In Xen, a synonym for [VM](#vm). See ["domain" on the Xen
Wiki](https://wiki.xenproject.org/wiki/Domain).
domU
----
## domU
Unprivileged [domain](#domain).
Also known as **guest** domains, domUs are the counterparts to dom0.
In Xen, all VMs except dom0 are domUs.
By default, most domUs lack direct hardware access.
Unprivileged [domain](#domain). Also known as **guest** domains, domUs are the
counterparts to dom0. In Xen, all VMs except dom0 are domUs. By default, most
domUs lack direct hardware access.
* The term "domU" is not a proper noun and should not be capitalized unless it is the first word in a sentence.
* The term "domU" is not a proper noun and should not be capitalized unless it
is the first word in a sentence.
* The use of [domain](#domain) as a synonym for [VM](#vm) is specific to Xen. Qubes diverges from this practice. See: [domain](#domain).
* The use of [domain](#domain) as a synonym for [VM](#vm) is specific to Xen.
Qubes diverges from this practice. See: [domain](#domain).
HVM
---
## HVM
[Hardware-assisted Virtual Machine](/doc/standalones-and-HVM/).
Any fully virtualized, or hardware-assisted, [VM](#vm) utilizing the virtualization extensions of the host CPU.
Although HVMs are typically slower than paravirtualized qubes due to the required emulation, HVMs allow the user to create domains based on any operating system.
[Hardware-assisted Virtual Machine](/doc/standalones-and-HVM/). Any fully
virtualized, or hardware-assisted, [VM](#vm) utilizing the virtualization
extensions of the host CPU. Although HVMs are typically slower than
paravirtualized qubes due to the required emulation, HVMs allow the user to
create domains based on any operating system.
qube
----
## qube
A secure compartment in Qubes OS.
Currently, qubes are implemented as Xen [VMs](#vm), but Qubes OS is independent of its underlying compartmentalization technology.
VMs could be replaced with a different technology, and qubes would still be called "qubes."
A secure compartment in Qubes OS. Currently, qubes are implemented as Xen
[VMs](#vm), but Qubes OS is independent of its underlying compartmentalization
technology. VMs could be replaced with a different technology, and qubes would
still be called "qubes."
* **Important:** The term "qube" should be lowercase unless it is the first word in a sentence. 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 collection of qubes or [Qubes OS](#qubes-os).
* **Important:** The term "qube" should be lowercase unless it is the first
word in a sentence. 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 collection of qubes or [Qubes OS](#qubes-os).
* Example usage: "In Qubes OS, you do your banking in your 'banking' qube and your web surfing in your 'untrusted' qube. That way, if your 'untrusted' qube is compromised, your banking activities will remain secure."
* 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
is compromised, your banking activities will remain secure."
* Historical note: The term "qube" was originally invented as an alternative to "VM" intended to make it easier for less technical users to understand Qubes OS and learn how to use it.
* Historical note: The term "qube" was originally invented as an alternative to
"VM" intended to make it easier for less technical users to understand Qubes
OS and learn how to use it.
Qubes OS
--------
## Qubes OS
A security-oriented operating system (OS).
The main principle of Qubes OS is security by compartmentalization (or isolation), in which activities are compartmentalized (or isolated) in separate [qubes](#qube).
A security-oriented operating system (OS). The main principle of Qubes OS is
security by compartmentalization (or isolation), in which activities are
compartmentalized (or isolated) in separate [qubes](#qube).
* **Important:** The official name is "Qubes OS" (note the capitalization and the space between "Qubes" and "OS").
However, in casual conversation this is often shortened to "Qubes."
Only in technical contexts where spaces are not permitted (e.g., usernames) may the space be omitted, as in `@QubesOS`.
* **Important:** The official name is "Qubes OS" (note the capitalization and
the space between "Qubes" and "OS"). However, in casual conversation this is
often shortened to "Qubes." Only in technical contexts where spaces are not
permitted (e.g., usernames) may the space be omitted, as in `@QubesOS`.
Qubes Windows Tools
-------------------
## Qubes Windows Tools
[Qubes Windows Tools (QWT)](/doc/windows-tools/) are a set of programs and drivers that provide integration of Windows qubes with the rest of the Qubes OS system.
Also see [Windows](/doc/windows/).
[Qubes Windows Tools (QWT)](/doc/windows-tools/) are a set of programs and
drivers that provide integration of Windows qubes with the rest of the Qubes OS
system. Also see [Windows](/doc/windows/).
service qube
------------
## service qube
A [qube](#qube) the primary purpose of which is to provide a service or services to other qubes.
`sys-net` and `sys-firewall` are examples of service qubes.
A [qube](#qube) the primary purpose of which is to provide a service or
services to other qubes. `sys-net` and `sys-firewall` are examples of service
qubes.
standalone
----------
## standalone
See [Standalones and HVMs](/doc/standalone-and-hvm/).
A type of [qube](#qube) that does not depend on any other qube for its root filesystem.
The opposite of an app qube.
A standalone is created by cloning a template.
Unlike templates, however, standalones do not supply their root filesystems to other qubes.
See [Standalones and HVMs](/doc/standalone-and-hvm/). A type of [qube](#qube)
that does not depend on any other qube for its root filesystem. The opposite of
an app qube. A standalone is created by cloning a template. Unlike templates,
however, standalones do not supply their root filesystems to other qubes.
template
--------
## template
See [Templates](/doc/templates/).
Any [qube](#qube) that supplies its root filesystem to another qube.
Templates are intended for installing and updating software applications, but not for running them.
See [Templates](/doc/templates/). Any [qube](#qube) that supplies its root
filesystem to another qube. Templates are intended for installing and updating
software applications, but not for running them.
* Since every template supplies its *own* root filesystem to at least one other qube, no template can be based on another template.
In other words, no template is an [app qube](#app-qube).
* Since every template supplies its *own* root filesystem to at least one other
qube, no template can be based on another template. In other words, no
template is an [app qube](#app-qube).
* Since every template supplies its *root* filesystem to at least one other qube, no [disposable template](#disposable-template) is a template.
* Since every template supplies its *root* filesystem to at least one other
qube, no [disposable template](#disposable-template) is a template.
VM
--
## VM
An abbreviation for "virtual machine."
A software implementation of a machine (for example, a computer) that executes programs like a physical machine.
An abbreviation for "virtual machine." A software implementation of a machine
(for example, a computer) that executes programs like a physical machine.