Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'tokideveloper-md-refactoring-links'

Browse Source
This commit is contained in:
Andrew David Wong 2021-04-15 09:02:25 -07:00
commit ec2af6a488
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
72 changed files with 733 additions and 1481 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CONTRIBUTING.md
View File

@ -3,8 +3,7 @@ Contributing to `qubes-doc`
Thank you for your interest in contributing to `qubes-doc`, the Qubes OS
Project's dedicated documentation repository! Please take a moment to read our
[Documentation Guidelines] before you begin writing. These guidelines are
[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before you begin writing. These guidelines are
important to maintaining high quality documentation, and following them will
increase the likelihood that your contribution will be accepted.
[Documentation Guidelines]: https://www.qubes-os.org/doc/doc-guidelines/

8
README.md
View File

@ -3,15 +3,11 @@ Qubes OS Documentation
Canonical URL: https://www.qubes-os.org/doc/
All [Qubes OS Project] documentation pages are stored as plain text
All [Qubes OS Project](https://github.com/QubesOS) documentation pages are stored as plain text
files in this dedicated 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.
For more information about the documentation, including how to contribute,
please see the [Documentation Guidelines].
[Qubes OS Project]: https://github.com/QubesOS
[documentation guidelines]: https://www.qubes-os.org/doc/doc-guidelines/
please see the [Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/).

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

@ -323,7 +323,7 @@ current and current-testing).
### RPM packages - yum repo
In source VM, grab [linux-yum] repository (below is assumed you've made it in
In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
`~/repo-yum-upload` directory) and replace `update_repo.sh` script with:
~~~
@ -339,7 +339,7 @@ find -type f -name '*.rpm' -delete
qrexec-client-vm $VMNAME local.UpdateYum
~~~
In target VM, setup actual yum repository (also based on [linux-yum], this time
In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time
without modifications). You will also need to setup some gpg key for signing
packages (it is possible to force yum to install unsigned packages, but it
isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
@ -387,7 +387,7 @@ Of course you will also need to setup qrexec policy in dom0
If you want to access the repository from network, you need to setup HTTP
server serving it, and configure the system to let other machines actually
reach this HTTP server. You can use for example using [port
forwarding][port-forwarding] or setting up Tor hidden service. Configuration
forwarding](/doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world) or setting up Tor hidden service. Configuration
details of those services are outside of the scope of this page.
Usage: setup `builder.conf` in source VM to use your dummy-uploader repository:
@ -419,7 +419,7 @@ Remember to also import gpg public key using `rpm --import`.
Steps are mostly the same as in the case of yum repo. The only details that differ:
- use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
- use different `update_repo.sh` script in source VM (below)
- use `local.UpdateApt` qrexec service in target VM (code below)
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
@ -539,6 +539,3 @@ Usage: add this line to `/etc/apt/sources.list` on test machine (adjust host and
deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main
~~~
[port-forwarding]: /doc/firewall/#port-forwarding-to-a-qube-from-the-outside-world
[linux-yum]: https://github.com/QubesOS/qubes-linux-yum
[linux-deb]: https://github.com/QubesOS/qubes-linux-deb

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

@ -8,13 +8,13 @@ title: Code Signing
# Code Signing
All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key.
All contributions to the Qubes OS [source code](/doc/source-code/) must be cryptographically signed by the author's PGP key.
## Generating a Key
(Note: If you already have a PGP key, you may skip this step.)
Alex Cabal has written an excellent [guide] on creating a PGP keypair.
Alex Cabal has written an excellent [guide](https://alexcabal.com/creating-the-perfect-gpg-keypair/) on creating a PGP keypair.
Below, we reproduce just the minimum steps in generating a keypair using GnuPG.
Please read Cabal's full guide for further important details.
@ -143,13 +143,12 @@ your Git commits.
GitHub shows a green `Verified` label indicating that the GPG signature could be
verified using any of the contributor’s GPG keys uploaded to GitHub. You can
upload your public key on GitHub by adding your public GPG key on the [New GPG
key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
page].
key](https://github.com/settings/gpg/new) under the [SSH GPG keys page](https://github.com/settings/keys).
## Code Signature Checks
The [signature-checker] checks if code contributions are signed.
Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed:
The [signature-checker](https://github.com/marmarek/signature-checker) checks if code contributions are signed.
Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker](https://github.com/marmarek/signature-checker) uses this algorithm to check if a commit is correctly signed:
1. Is the commit signed?
If the commit is not signed, you can see the message
@ -194,21 +193,14 @@ In this case, you have several options to sign the commit:
> policy/qubesos/code-signing — Unable to verify (no valid key found)
This means that the [signature-checker] has found a signature for the commit
This means that the [signature-checker](https://github.com/marmarek/signature-checker) has found a signature for the commit
but is not able to verify it using the any key available.
This might be that you forgot to upload the key to a key server.
Please upload it.
## Using PGP with Email
If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key.
One good way to do this is with a program like [Enigmail].
If you're submitting a patch by emailing the [developer mailing list](/support/#qubes-devel), simply sign your email with your PGP key.
One good way to do this is with a program like [Enigmail](https://www.enigmail.net/).
Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[source code]: /doc/source-code/
[developer mailing list]: /support/#qubes-devel
[Enigmail]: https://www.enigmail.net/
[signature-checker]: https://github.com/marmarek/signature-checker
[GitHub New GPG key]: https://github.com/settings/gpg/new
[GitHub SSH GPG keys page]: https://github.com/settings/keys

21
developer/code/source-code.md
View File

@ -23,7 +23,7 @@ several components, each of which has its own separate repository, for example:
* `linux-template-builder.git` -- Scripts and other files used to create Qubes
template images.
All of our repositories are available under the [QubesOS GitHub account].
All of our repositories are available under the [QubesOS GitHub account](https://github.com/QubesOS/).
To clone a repository:
@ -38,7 +38,7 @@ git clone https://github.com/QubesOS/qubes-core-admin.git core-admin
~~~
To build Qubes you do not need to download all these repositories.
If you use [qubes builder] you can specify *what* you want to build, and download only the repositories needed to build that target.
If you use [qubes builder](/doc/QubesBuilder/) you can specify *what* you want to build, and download only the repositories needed to build that target.
If you really do want to clone **all** of the repositories, you can use these commands:
@ -58,17 +58,17 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
How to Send Patches
-------------------
If you want to [contribute code] to the project, there are two ways. Whichever
method you choose, you must [sign your code] before it can be accepted.
If you want to [contribute code](/doc/contributing/#contributing-code) to the project, there are two ways. Whichever
method you choose, you must [sign your code](/doc/code-signing/) before it can be accepted.
* **Preferred**: Use GitHub's [fork & pull requests].
* **Preferred**: Use GitHub's [fork & pull requests](https://guides.github.com/activities/forking/).
Opening a pull request on GitHub greatly eases the code review and tracking
process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list] in order to notify people who
a message to the [qubes-devel mailing list](/support/#qubes-devel) in order to notify people who
do not receive GitHub notifications.
* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
* Send a patch to the [qubes-devel mailing list](/support/#qubes-devel) (`git format-patch`).
1. Make all the changes in your working directory, i.e. edit files, move them
around (you can use 'git mv' for this), etc.
@ -84,10 +84,3 @@ method you choose, you must [sign your code] before it can be accepted.
5. Send your patch to `qubes-devel`. Start the message subject with
`[PATCH]`.
[QubesOS GitHub account]: https://github.com/QubesOS/
[contribute code]: /doc/contributing/#contributing-code
[sign your code]: /doc/code-signing/
[fork & pull requests]: https://guides.github.com/activities/forking/
[qubes-devel mailing list]: /support/#qubes-devel
[qubes builder]: /doc/QubesBuilder/

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

@ -13,7 +13,7 @@ title: Automated Tests
## Unit and Integration Tests
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS.
Starting with Qubes R3 we use [python unittest](https://docs.python.org/3/library/unittest.html) to perform automatic tests of Qubes OS.
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
The main purpose is, of course, to deliver much more stable releases.
@ -123,7 +123,7 @@ Tests are also compatible with nose2 test runner, so you can use this instead:
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
```
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA](http://open.qa/).
### Unit testing inside a VM
@ -251,7 +251,7 @@ class SomeTestCase(unittest.TestCase):
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
Manually testing the installation of Qubes OS is a time-consuming process.
We use [openQA] to automate this process.
We use [OpenQA](http://open.qa/) to automate this process.
It works by installing Qubes in KVM and interacting with it as a user would, including simulating mouse clicks and keyboard presses.
Then, it checks the output to see whether various tests were passed, e.g. by comparing the virtual screen output to screenshots of a successful installation.
@ -262,5 +262,3 @@ Nonetheless, PV works well, which is sufficient for automated installation testi
Thanks to an anonymous donor, our openQA system is hosted in a datacenter on hardware that meets these requirements.
[unittest]: https://docs.python.org/3/library/unittest.html
[OpenQA]: http://open.qa/

3
developer/debugging/mount-lvm-image.md
View File

@ -53,6 +53,5 @@ From the GUI, or from the command line:
# References
Please consult this issue's [comment].
Please consult this issue's [comment](https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625).
[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625

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

@ -12,17 +12,17 @@ title: Documentation Guidelines
# Documentation guidelines
All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc] repository.
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][contribute]!
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 against [qubes-doc] must pass review prior to be merged, except in the case of [external documentation] (see [#4693]).
All pull requests 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.
@ -36,9 +36,9 @@ In cases in which another reviewer is not required, the documentation maintainer
## 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] the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
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
@ -50,17 +50,17 @@ 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][issue] for it first so that we can make sure we're on the same page before significant works begins.
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 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][qubes-doc] hosted on [GitHub].
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][gh-fork] the [qubes-doc] repo, make your changes, then [submit a pull request][gh-pull].)
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.
@ -84,7 +84,7 @@ This step is only needed the first time you make a contribution.
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're making formatting changes, please [render the site locally] to verify that everything looks correct before submitting any changes.
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/wiki/doc-edit/06-edit.png)](/attachment/wiki/doc-edit/06-edit.png)
@ -121,7 +121,7 @@ This will make the image a hyperlink to the image file, allowing the reader to c
[![Image Title](/attachment/wiki/page-title/image-filename.png)](/attachment/wiki/page-title/image-filename.png)
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename.
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.
@ -140,11 +140,11 @@ There are some exceptions to this policy (e.g., information that is certain not
### Core vs. external documentation
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc].
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].
If you've written a piece of documentation that is not appropriate for [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] is perfectly fine.
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 [this file](https://github.com/QubesOS/qubesos.github.io/blob/master/_data/index.yml) 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.
@ -275,11 +275,11 @@ 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][version-thread].
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]. Use these
* 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:
@ -304,11 +304,11 @@ When making contributions, please try to observe the following style conventions
* 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] (see [instructions above](#how-to-add-images)).
* 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] and [Canaries]
* 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`
* Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
@ -353,30 +353,10 @@ 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][md] 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][git-commit].
[instructions in our coding style guidelines](/doc/coding-style/#commit-message-guidelines).
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[issue]: /doc/reporting-bugs/
[contribute]: #how-to-contribute
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[gh-fork]: https://guides.github.com/activities/forking/
[gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/
[support]: /support/
[version-example]: /doc/template/fedora/upgrade-25-to-26/
[version-thread]: https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion
[QSBs]: /security/bulletins/
[Canaries]: /security/canaries/
[News]: /news/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines
[render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions
[qubes-attachment]: https://github.com/QubesOS/qubes-attachment
[external documentation]: /doc/#external-documentation
[#4693]: https://github.com/QubesOS/qubes-issues/issues/4693

40
developer/general/gsoc.md
View File

@ -11,28 +11,28 @@ title: Google Summer of Code
================
## Information for Students
Thank you for your interest in participating in the [Google Summer of Code program][gsoc-qubes] with the [Qubes OS team][team]. You can read more about the Google Summer of Code program at the [official website][gsoc] and the [official FAQ][gsoc-faq].
Thank you for your interest in participating in the [Google Summer of Code program](https://summerofcode.withgoogle.com/organizations/4675790572093440/) with the [Qubes OS team](/team/). You can read more about the Google Summer of Code program at the [official website](https://summerofcode.withgoogle.com/) and the [official FAQ](https://developers.google.com/open-source/gsoc/faq).
Being accepted as a Google Summer of Code student is quite competitive. Students wishing to participate in the Summer of Code must be aware that you will be required to produce code for Qubes OS for 3 months. Your mentors, Qubes developers, will dedicate a portion of their time towards mentoring you. Therefore, we seek candidates who are committed to helping Qubes long-term and are willing to do quality work and be proactive in communicating with your mentor.
You don't have to be a proven developer -- in fact, this whole program is meant to facilitate joining Qubes and other free and open source communities. The Qubes community maintains information about [contributing to Qubes development][contributing] and [how to send patches][patches]. In order to contribute code to the Qubes project, you must be able to [sign your code][code-signing].
You don't have to be a proven developer -- in fact, this whole program is meant to facilitate joining Qubes and other free and open source communities. The Qubes community maintains information about [contributing to Qubes development](/doc/contributing/#contributing-code) and [how to send patches](/doc/source-code/#how-to-send-patches). In order to contribute code to the Qubes project, you must be able to [sign your code](/doc/code-signing/).
You should start learning the components that you plan on working on before the start date. Qubes developers are available on the [mailing lists][ml-devel] for help. The GSoC timeline reserves a lot of time for bonding with the project -- use that time wisely. Good communication is key, you should plan to communicate with your team daily and formally report progress and plans weekly. Students who neglect active communication will be failed.
You should start learning the components that you plan on working on before the start date. Qubes developers are available on the [mailing lists](/support/#qubes-devel) for help. The GSoC timeline reserves a lot of time for bonding with the project -- use that time wisely. Good communication is key, you should plan to communicate with your team daily and formally report progress and plans weekly. Students who neglect active communication will be failed.
### Overview of Steps
- Join the [qubes-devel list][ml-devel] and introduce yourself, and meet your fellow developers
- Read [Google's instructions for participating][gsoc-participate] and the [GSoC Student Manual][gsoc-student]
- Join the [qubes-devel list](/support/#qubes-devel) and introduce yourself, and meet your fellow developers
- Read [Google's instructions for participating](https://developers.google.com/open-source/gsoc/) and the [GSoC Student Manual](https://developers.google.com/open-source/gsoc/resources/manual#student_manual)
- Take a look at the list of ideas below
- Come up with a project that you are interested in (and feel free to propose your own! Don't feel limited by the list below.)
- Read the Student Proposal guidelines below
- Write a first draft proposal and send it to the qubes-devel mailing list for review
- Submit proposal using [Google's web interface][gsoc-submit] ahead of the deadline (this requires a Google Account!)
- Submit proposal using [Google's web interface](https://summerofcode.withgoogle.com/) ahead of the deadline (this requires a Google Account!)
- Submit proof of enrollment well ahead of the deadline
Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from students who have already started to act like free and open source developers.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues][qubes-issues] (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"][qubes-issues-suggested] (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder][qubes-builder], our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
### Student proposal guidelines
@ -75,7 +75,7 @@ Other things to think about:
## Project Ideas
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the [qubes-devel mailing list][ml-devel] and associated GitHub issue to learn more about the idea.
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the [qubes-devel mailing list](/support/#qubes-devel) and associated GitHub issue to learn more about the idea.
```
### Adding a Proposal
@ -463,7 +463,7 @@ Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
**Knowledge prerequisite**:
**Mentor**: Inquire on [qubes-devel][ml-devel].
**Mentor**: Inquire on [qubes-devel](/support/#qubes-devel).
### Admin API Fuzzer
@ -487,7 +487,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
- some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os))
- a hacker's curiosity
**Mentor**: Inquire on [qubes-devel][ml-devel].
**Mentor**: Inquire on [qubes-devel](/support/#qubes-devel).
### Secure Boot support
@ -525,7 +525,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
## Past Projects
You can view the projects we had in 2017 in the [GSoC 2017 archive][2017-archive]. We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive][2020-archive].
You can view the projects we had in 2017 in the [GSoC 2017 archive](https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/). We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive](https://summerofcode.withgoogle.com/archive/2020/organizations/4924517870206976/).
Here are some successful projects which have been implemented in the past by Google Summer of Code participants.
@ -588,21 +588,3 @@ would override all the user changes there). More details:
We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC).
[2017-archive]: https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/
[2020-archive]: https://summerofcode.withgoogle.com/archive/2020/organizations/4924517870206976/
[gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/4675790572093440/
[gsoc]: https://summerofcode.withgoogle.com/
[team]: /team/
[gsoc-faq]: https://developers.google.com/open-source/gsoc/faq
[contributing]: /doc/contributing/#contributing-code
[patches]: /doc/source-code/#how-to-send-patches
[code-signing]: /doc/code-signing/
[ml-devel]: /support/#qubes-devel
[gsoc-participate]: https://developers.google.com/open-source/gsoc/
[gsoc-student]: https://developers.google.com/open-source/gsoc/resources/manual#student_manual
[how-to-gsoc]: http://teom.org/blog/kde/how-to-write-a-kick-ass-proposal-for-google-summer-of-code/
[gsoc-submit]: https://summerofcode.withgoogle.com/
[mailing-lists]: /support/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-issues-suggested]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22
[qubes-builder]: /doc/qubes-builder/

39
developer/general/gsod.md
View File

@ -8,7 +8,7 @@ title: Google Season of Docs
# 2021 Google Season of Docs
Thank you for your interest in participating in the [2021 Google Season of Docs][gsod] program with the [Qubes OS team][team]. You can read more about the Google Season of Docs in the official [guides][gsod-doc] and [FAQ][gsod-faq].
Thank you for your interest in participating in the [2021 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
## 2021 Project Idea
@ -83,9 +83,9 @@ within the times allotted. The past Google Season of Docs projects have given us
## Past Projects
You can view the project we had in 2019 in the [2019 GSoD archive][2019-qubes-gsod] and the [2019 writer's report][2019-qubes-report].
You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
You can also view the project we had in 2020 in the [2020 GSoD archive][2020-qubes-gsod] and the [2020 writer's report][2020-qubes-report].
You can also view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
@ -99,14 +99,14 @@ This could be helped by writing consolidated guide with with a clear list of sym
**Expected results**:
- Review existing [troubleshooting guides](/doc/#troubleshooting)
- Review [issues][doc-issues] containing common troubleshooting steps (checking specific logs etc)
- Review [issues](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+doc%22) containing common troubleshooting steps (checking specific logs etc)
- Propose updated, consolidated troubleshooting documentation, including its layout
**Knowledge prerequisite**:
- [Markdown][markdown]
- [Markdown](https://daringfireball.net/projects/markdown/)
**Mentor**: [Marek Marczykowski-Górecki][team]
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Improve Getting Started page
@ -122,9 +122,9 @@ This could be helped by writing consolidated guide with with a clear list of sym
**Knowledge prerequisite**:
- basic Qubes OS knowledge
- [Markdown][markdown]
- [Markdown](https://daringfireball.net/projects/markdown/)
**Mentor**: [Michael Carbone][team]
**Mentor**: [Michael Carbone](/team/)
### Rewrite qrexec documentation
@ -143,26 +143,7 @@ Fixing this last point may require very close cooperation with developers, as th
**Knowledge prerequisite**:
- [Markdown][markdown]
- [Markdown](https://daringfireball.net/projects/markdown/)
**Mentor**: [Marek Marczykowski-Górecki][team]
**Mentor**: [Marek Marczykowski-Górecki](/team/)
[gsod]: https://developers.google.com/season-of-docs/
[team]: /team/
[gsod-doc]: https://developers.google.com/season-of-docs/docs/
[gsod-faq]: https://developers.google.com/season-of-docs/docs/faq
[gsod.md]: https://github.com/QubesOS/qubes-doc/blob/master/developer/general/gsod.md
[gsod-2020-thread]: https://groups.google.com/d/msgid/qubes-project/aac9b148-4081-ebd8-cb9d-9a9191033484%40qubes-os.org
[Documentation Guidelines]: /doc/doc-guidelines/
[Help, Support, and Mailing Lists]: /support/
[intro]: /intro/
[getting started]: /getting-started/
[markdown]: https://daringfireball.net/projects/markdown/
[doc-issues]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+doc%22
[2019-qubes-gsod]: https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes
[2019-qubes-report]: https://refre.ch/report-qubesos/
[2020-qubes-gsod]: https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0
[2020-qubes-report]: https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733
[existing installation guide]: https://www.youtube.com/watch?v=mATI8Lht0Js
[virtual box issue]: https://www.virtualbox.org/ticket/16771

57
developer/general/package-contributions.md
View File

@ -10,7 +10,7 @@ Package Contributions
=====================
_This page is for developers who wish to contribute packages.
If you want to install contributed packages, please see [installing contributed packages]._
If you want to install contributed packages, please see [installing contributed packages](/doc/installing-contributed-packages/)._
We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS.
This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved.
@ -21,8 +21,8 @@ Inclusion Criteria
In order to be accepted, packages must:
* In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines].
* Be published under an open-source license (read about the [Qubes OS License](/doc/license/)).
* Follow our [coding guidelines](/doc/coding-style/).
* Be thoroughly tested.
* Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review.
@ -32,13 +32,13 @@ In order to be accepted, packages must:
Contribution Procedure
----------------------
Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list].
Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list](/support/#qubes-devel).
Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
1. Ensure that your package satisfies the [Inclusion Criteria](#inclusion-criteria).
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton](https://github.com/QubesOS-contrib/qubes-skeleton).
3. If you haven't already, [sign your code](/doc/code-signing/).
4. Create an issue in [qubes-issues](https://github.com/QubesOS/qubes-issues/issues/) with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
Please note that the Qubes core developers are very busy.
If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
@ -46,7 +46,7 @@ Once you have a package that's ready to become part of Qubes OS, please follow t
If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month).
We appreciate your understanding!
5. You may be asked followup questions.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib](https://github.com/QubesOS-contrib) organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure](#review-procedure)), and [QubesOS-contrib](https://github.com/QubesOS-contrib) will fork your repo.
If we decide not to accept your contribution, we will state the reason and close the issue.
Update Procedure
@ -55,16 +55,16 @@ Update Procedure
*Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package!
The update procedure is the same for everyone, including the original package contributor.
If you would like to update an already-contributed package (specifically, a fork owned by [QubesOS-contrib]), please submit a [signed][sig], fast-forwardable pull request to that repo with your changes.
Please note that your pull request **must** be both [signed][sig] and fast-forwardable, or else it will be closed without further review.
If you would like to update an already-contributed package (specifically, a fork owned by [QubesOS-contrib](https://github.com/QubesOS-contrib)), please submit a [signed](/doc/code-signing/), fast-forwardable pull request to that repo with your changes.
Please note that your pull request **must** be both [signed](/doc/code-signing/) and fast-forwardable, or else it will be closed without further review.
One or more reviewers may post comments on your pull request.
Please be prepared to read and respond to these comments.
Review Procedure
----------------
This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]).
All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
This review procedure covers both original package contributions (see [Contribution Procedure](#contribution-procedure)) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure](#update-procedure)).
All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer](#package-maintainers) (PM).
In all cases, the QCR will be a core Qubes developer.
In some cases, the QCR and the PM will be the same person.
For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
@ -72,25 +72,25 @@ For example, if someone contributes a package, then disappears, and no suitable
The review procedure is as follows:
1. Someone, S, wishes to make a change to a package, P.
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib].
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib](https://github.com/QubesOS-contrib).
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
If the the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed](/doc/code-signing/) *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed](/doc/code-signing/) tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.
In all the cases, the first condition to be validated by the QCR's review is to ensure that the contribution **will not** hijack any core packages of [QubesOS] and of course, none of the [QubesOS-contrib] packages too. More precisely, particular attention to the whole build pipeline will be made with a specific review of:
In all the cases, the first condition to be validated by the QCR's review is to ensure that the contribution **will not** hijack any core packages of [QubesOS](https://github.com/QubesOS) and of course, none of the [QubesOS-contrib](https://github.com/QubesOS-contrib) packages too. More precisely, particular attention to the whole build pipeline will be made with a specific review of:
* Package dependencies,
* Build scripts (including downloaded ones),
* All downloaded components should be verified against static hash,
* RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
* Makefiles,
* Package build [reproducible]
* Package build [reproducible](https://reproducible-builds.org/)
and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called [qubes-skeleton].
and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called [qubes-skeleton](https://github.com/QubesOS-contrib/qubes-skeleton).
Package Maintainers
-------------------
@ -98,24 +98,9 @@ Package Maintainers
If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise.
As the maintainer of the package, it is your privilege and responsibility to:
* [Review][Review Procedure] each pull request made against the package.
* [Review](#review-procedure) each pull request made against the package.
* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
If you do not wish to be the maintainer of your package, please let us know.
If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
[installing contributed packages]: /doc/installing-contributed-packages/
[Inclusion Criteria]: #inclusion-criteria
[Contribution Procedure]: #contribution-procedure
[Update Procedure]: #update-procedure
[Review Procedure]: #review-procedure
[Package Maintainer]: #package-maintainers
[Qubes OS License]: /doc/license/
[sig]: /doc/code-signing/
[coding guidelines]: /doc/coding-style/
[qubes-devel mailing list]: /support/#qubes-devel
[QubesOS]: https://github.com/QubesOS
[QubesOS-contrib]: https://github.com/QubesOS-contrib
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues/
[reproducible]: https://reproducible-builds.org/
[qubes-skeleton]: https://github.com/QubesOS-contrib/qubes-skeleton

12
developer/releases/3_1/release-notes.md
View File

@ -10,18 +10,18 @@ title: Qubes R3.1 release notes
## New features since 3.0
* Management Stack based of Salt Stack in dom0 - [documentation][salt-doc]
* Management Stack based of Salt Stack in dom0 - [documentation](/doc/salt/)
* Out of the box Whonix setup
* UEFI support
* LIVE edition (still alpha, not part of R3.1-rc1)
* Updated GPU drivers in dom0
* Colorful window application icons (instead of just colorful lock icon)
* PV Grub support ([documentation][pvgrub-doc])
* Out of the box USB VM setup, including [handling USB mouse][input-proxy]
* PV Grub support ([documentation](/doc/managing-vm-kernel/))
* Out of the box USB VM setup, including [handling USB mouse](https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md)
* Xen upgraded to 4.6, for better hardware support (especially Skylake platform)
* Improve updates proxy flexibility - especially repositories served over HTTPS
You can get detailed description in [completed github issues][github-release-notes]
You can get detailed description in [completed github issues](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed)
## Known issues
@ -66,7 +66,3 @@ Alternatively you can [upgrade to R3.0
using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the
instructions above. This will be time consuming process.
[salt-doc]: /doc/salt/
[pvgrub-doc]: /doc/managing-vm-kernel/
[input-proxy]: https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed

27
developer/releases/3_2/release-notes.md
View File

@ -10,16 +10,16 @@ title: Qubes R3.2 release notes
## New features since 3.1
* Management Stack extended to support in-VM configuration - [documentation][salt-doc]
* PV USB - [documentation][usb]
* Management Stack extended to support in-VM configuration - [documentation](/doc/salt/)
* PV USB - [documentation](/doc/usb/)
* Dom0 update to Fedora 23 for better hardware support
* Kernel 4.4.x
* Default desktop environment switched to Xfce4
* KDE 5 support (but it is no longer the default one)
* Tiling window managers support: awesome, [i3][i3]
* More flexible Qubes RPC services - [related ticket][qrexec-argument], [documentation][qrexec-doc]
* Tiling window managers support: awesome, [i3](/doc/i3/)
* More flexible Qubes RPC services - [related ticket](https://github.com/QubesOS/qubes-issues/issues/1876), [documentation](/doc/qrexec/#service-policies-with-arguments)
You can get detailed description in [completed github issues][github-release-notes]
You can get detailed description in [completed github issues](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed)
## Known issues
@ -47,27 +47,18 @@ After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-u
### From R3.1
The easiest and safest way to upgrade to Qubes R3.2 is to install it from
scratch and use [qubes backup and restore tools][backup] for
scratch and use [qubes backup and restore tools](/doc/backup-restore/) for
migrating of all of the user VMs.
Users of Qubes R3.1 can also upgrade using [this
procedure][upgrade].
procedure](/doc/upgrade-to-r3.2/).
### From R3.0 or earlier
When upgrading from earlier versions the easiest and safest way is to install
it from scratch and use [qubes backup and restore tools][backup]
it from scratch and use [qubes backup and restore tools](/doc/backup-restore/)
for migrating of all of the user VMs.
Alternatively you can [upgrade to R3.1 using][upgrade-r3.1] first, then follow
Alternatively you can [upgrade to R3.1 using](/doc/releases/3.1/release-notes/#upgrading) first, then follow
the instructions above. This will be time consuming process.
[salt-doc]: /doc/salt/
[usb]: /doc/usb/
[i3]: /doc/i3/
[upgrade]: /doc/upgrade-to-r3.2/
[upgrade-r3.1]: /doc/releases/3.1/release-notes/#upgrading
[backup]: /doc/backup-restore/
[qrexec-argument]: https://github.com/QubesOS/qubes-issues/issues/1876
[qrexec-doc]: /doc/qrexec/#service-policies-with-arguments
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.2%22+label%3Arelease-notes+is%3Aclosed

63
developer/releases/4_0/release-notes.md
View File

@ -12,36 +12,36 @@ Qubes R4.0 release notes
New features since 3.2
----------------------
* Core management scripts rewrite with better structure and extensibility, [API documentation][api-doc]
* [Admin API][admin-api] allowing strictly controlled managing from non-dom0
* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)
* [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0
* All `qvm-*` command-line tools rewritten, some options have changed
* Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM
* Use [PVH][qsb-37] and [HVM][hvm-switch] by default to [mitigate Meltdown & Spectre][qsb-37] and lower the [attack surface on Xen][qsb-24]
* Use [PVH](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt) and [HVM](https://github.com/QubesOS/qubes-issues/issues/2185) by default to [mitigate Meltdown & Spectre](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt) and lower the [attack surface on Xen](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt)
* Create USB VM by default
* [Multiple DisposableVMs templates support][dispvm-ticket]
* New [backup format][backup-format] using scrypt key-derivation function
* [Multiple DisposableVMs templates support](https://github.com/QubesOS/qubes-issues/issues/2253)
* New [backup format](/doc/backup-emergency-restore-v4/) using scrypt key-derivation function
* Non-encrypted backups no longer supported
* [split VM packages][packages-split], for better support minimal, specialized templates
* [Qubes Manager decomposition][manager-ticket] - domains and devices widgets instead of full Qubes Manager; devices widget support also USB
* [More flexible firewall interface][vm-interface] for ease unikernel integration
* Template VMs do not have network interface by default, [qrexec-based updates proxy][qrexec-proxy] is used instead
* More flexible IP addressing for VMs - [custom IP][custom-ip], [hidden from the IP][hide-ip]
* More flexible Qubes RPC policy - [related ticket][qrexec-policy-keywords], [documentation][qrexec-doc]
* [New Qubes RPC confirmation window][qrexec-confirm], including option to specify destination VM
* [New storage subsystem design][storage]
* [split VM packages](https://github.com/QubesOS/qubes-issues/issues/2771), for better support minimal, specialized templates
* [Qubes Manager decomposition](https://github.com/QubesOS/qubes-issues/issues/2132) - domains and devices widgets instead of full Qubes Manager; devices widget support also USB
* [More flexible firewall interface](/doc/vm-interface/) for ease unikernel integration
* Template VMs do not have network interface by default, [qrexec-based updates proxy](https://github.com/QubesOS/qubes-issues/issues/1854) is used instead
* More flexible IP addressing for VMs - [custom IP](https://github.com/QubesOS/qubes-issues/issues/1477), [hidden from the IP](https://github.com/QubesOS/qubes-issues/issues/1143)
* More flexible Qubes RPC policy - [related ticket](https://github.com/QubesOS/qubes-issues/issues/865), [documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc)
* [New Qubes RPC confirmation window](https://github.com/QubesOS/qubes-issues/issues/910), including option to specify destination VM
* [New storage subsystem design](https://github.com/QubesOS/qubes-issues/issues/1842)
* Dom0 update to Fedora 25 for better hardware support
* Kernel 4.9.x
You can get detailed description in [completed github issues][github-release-notes]
You can get detailed description in [completed github issues](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed)
Security Notes
--------------
* PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see [QSB #37][qsb-37]).
* PV VMs migrated from 3.2 to 4.0-rc4 or later are automatically set to PVH mode in order to protect against Meltdown (see [QSB #37](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt)).
However, PV VMs migrated from any earlier 4.0 release candidate (RC1, RC2, or RC3) are not automatically set to PVH mode.
These must be set manually.
* The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]).
* The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737](https://github.com/QubesOS/qubes-issues/issues/3737)).
Steps for dom0 updates:
@ -77,9 +77,9 @@ Security Notes
Known issues
------------
* Locale using coma as decimal separator [crashes qubesd][locale-bug]. Either install with different locale (English (United States) for example), or manually apply fix explained in that issue.
* Locale using coma as decimal separator [crashes qubesd](https://github.com/QubesOS/qubes-issues/issues/3753). Either install with different locale (English (United States) for example), or manually apply fix explained in that issue.
* In the middle of installation, [keyboard layout reset to US][keyboard-layout-bug]. Be careful what is the current layout while setting default user password (see upper right screen corner).
* In the middle of installation, [keyboard layout reset to US](https://github.com/QubesOS/qubes-issues/issues/3352). Be careful what is the current layout while setting default user password (see upper right screen corner).
* On some laptops (for example Librem 15v2), touchpad do not work directly after installation. Reboot the system to fix the issue.
@ -106,29 +106,6 @@ Upgrading
There is no in-place upgrade path from earlier Qubes versions. The only
supported option to upgrade to Qubes R4.0 is to install it from scratch and use
[qubes backup and restore tools][backup] for migrating of all of the user VMs.
We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
[qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs.
We also provide [detailed instruction](/doc/upgrade-to-r4.0/) for this procedure.
[backup]: /doc/backup-restore/
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed
[custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477
[hide-ip]: https://github.com/QubesOS/qubes-issues/issues/1143
[packages-split]: https://github.com/QubesOS/qubes-issues/issues/2771
[hvm-switch]: https://github.com/QubesOS/qubes-issues/issues/2185
[manager-ticket]: https://github.com/QubesOS/qubes-issues/issues/2132
[dispvm-ticket]: https://github.com/QubesOS/qubes-issues/issues/2253
[qrexec-proxy]: https://github.com/QubesOS/qubes-issues/issues/1854
[qrexec-policy-keywords]: https://github.com/QubesOS/qubes-issues/issues/865
[qrexec-confirm]: https://github.com/QubesOS/qubes-issues/issues/910
[qrexec-doc]: /doc/qrexec/#specifying-vms-tags-types-targets-etc
[storage]: https://github.com/QubesOS/qubes-issues/issues/1842
[vm-interface]: /doc/vm-interface/
[admin-api]: /news/2017/06/27/qubes-admin-api/
[qsb-24]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-024-2016.txt
[qsb-37]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-037-2018.txt
[backup-format]: /doc/backup-emergency-restore-v4/
[api-doc]: https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/
[upgrade-to-r4.0]: /doc/upgrade-to-r4.0/
[locale-bug]: https://github.com/QubesOS/qubes-issues/issues/3753
[keyboard-layout-bug]: https://github.com/QubesOS/qubes-issues/issues/3352
[#3737]: https://github.com/QubesOS/qubes-issues/issues/3737

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

@ -38,7 +38,7 @@ TBD
## Components
![Admin API Architecture][admin-api-architecture]
![Admin API Architecture](/attachment/wiki/AdminAPI/admin-api-architecture.svg)
A central entity in the Qubes Admin API system is a `qubesd` daemon, which
holds information about all domains in the system and mediates all actions (like
@ -355,4 +355,3 @@ In addition, there is a mechanism to prevent concurrent modifications of the pol
<!-- vim: set ts=4 sts=4 sw=4 et : -->
[admin-api-architecture]: /attachment/wiki/AdminAPI/admin-api-architecture.svg

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

@ -21,7 +21,7 @@ One of the main goals of the project is to keep the TCB to an absolute minimum.
The size of the current TCB is on the order order of hundreds of thousands of lines of C code, which is several orders of magnitude less than other OSes.
(In Windows, Linux, and Mac OSes, the amount of trusted code is typically on the order of tens of *millions* of lines of C code.)
For more information, see [Qubes Security Goals].
For more information, see [Qubes Security Goals](/security/goals/).
Security-critical Qubes-specific Components
-------------------------------------------
@ -69,9 +69,6 @@ In that case, only network-isolated domains would be somewhat trustworthy.
This means that we must trust at least some of the vendors that supply the code we run inside our domains.
(We don't have to trust *all* of them, but we at least have to trust the few that provide the apps we use in the most critical domains.)
In practice, we trust the software provided by the [Fedora Project].
In practice, we trust the software provided by the [Fedora Project](https://getfedora.org/).
This software is signed by Fedora distribution keys, so it is also critical that the tools used in domains for software updates (`dnf` and `rpm`) are trustworthy.
[Qubes Security Goals]: /security/goals/
[Fedora Project]: https://getfedora.org/
[Understanding and Preventing Data Leaks]: /doc/data-leaks/

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

@ -12,7 +12,7 @@ This Code of Conduct is a collaborative, evolving document that attempts to tran
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] to this document and the [discussion] leading to its creation.
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
@ -33,11 +33,11 @@ Examples of unacceptable behavior by participants include:
- 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]
- 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].)
(Please also see our [discussion guidelines](/support/#discussion-guidelines).)
## Our Responsibilities
@ -49,7 +49,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
## 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], [Andrew David Wong], and [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.
@ -61,15 +61,5 @@ Please try not to get offended if you perceive your contributions as being met w
## Attribution
The initial published version of this Code of Conduct was adapted from the [Contributor Covenant, version 1.4] and the [Rust Code of Conduct].
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).
[history of changes]: https://github.com/QubesOS/qubes-doc/commits/master/about/code-of-conduct.md
[discussion]: https://github.com/QubesOS/qubes-issues/issues/2163
[Citizen Code of Conduct]: http://citizencodeofconduct.org/
[discussion guidelines]: /support/#discussion-guidelines
[Contributor Covenant, version 1.4]: https://contributor-covenant.org/version/1/4
[Rust Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
[Marek Marczykowski-Górecki]: /team/#marek-marczykowski-g%C3%B3recki
[Andrew David Wong]: /team/#andrew-david-wong
[Michael Carbone]: /team/#michael-carbone

65
introduction/contributing.md
View File

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

177
introduction/faq.md
View File

@ -58,33 +58,33 @@ securely isolated compartments called *qubes*.
This approach allows you to keep the different things you do on your computer securely separated from each other in isolated qubes so that one qube getting compromised won't affect the others.
For example, you might have one qube for visiting untrusted websites and a different qube for doing online banking.
This way, if your untrusted browsing qube gets compromised by a malware-laden website, your online banking activities won't be at risk.
Similarly, if you're concerned about malicious email attachments, Qubes can make it so that every attachment gets opened in its own single-use [disposable qube].
Similarly, if you're concerned about malicious email attachments, Qubes can make it so that every attachment gets opened in its own single-use [disposable qube](/doc/dispvm/).
In this way, Qubes allows you to do everything on the same physical computer without having to worry about a single successful cyberattack taking down your entire digital life in one fell swoop.
Moreover, all of these isolated qubes are integrated into a single, usable system.
Programs are isolated in their own separate qubes, but all windows are displayed in a single, unified desktop environment with unforgeable colored window borders so that you can easily identify windows from different security levels.
Common attack vectors like network cards and USB controllers are isolated in their own hardware qubes while their functionality is preserved through secure [networking][network], [firewalls], and [USB device management][USB].
Integrated [file] and [clipboard] copy and paste operations make it easy to work across various qubes without compromising security.
The innovative [Template] system separates software installation from software use, allowing qubes to share a root filesystem without sacrificing security (and saving disk space, to boot).
Common attack vectors like network cards and USB controllers are isolated in their own hardware qubes while their functionality is preserved through secure [networking](/doc/networking/), [firewalls](/doc/firewall), and [USB device management](/doc/usb-devices).
Integrated [file](/doc/copying-files) and [clipboard](/doc/copy-paste) copy and paste operations make it easy to work across various qubes without compromising security.
The innovative [Template](/doc/template-implementation) system separates software installation from software use, allowing qubes to share a root filesystem without sacrificing security (and saving disk space, to boot).
Qubes even allows you to sanitize PDFs and images in a few clicks.
Those concerned about physical hardware attacks will benefit from [Anti Evil Maid].
Those concerned about physical hardware attacks will benefit from [Anti Evil Maid](/doc/anti-evil-maid/).
### How does Qubes OS provide privacy?
There can be no privacy without security, since security vulnerabilities allow privacy measures to be circumvented.
This makes Qubes exceptionally well-suited for implementing effective privacy tools.
Users concerned about privacy will appreciate the integration of [Whonix][Qubes-Whonix] into Qubes, which makes it easy to use [Tor] securely.
For more information about how to use this powerful tool correctly and safely, please see [Whonix][Qubes-Whonix].
Users concerned about privacy will appreciate the integration of [Whonix](/doc/whonix/) into Qubes, which makes it easy to use [Tor](https://www.torproject.org/) securely.
For more information about how to use this powerful tool correctly and safely, please see [Whonix](/doc/whonix/).
### What about privacy in non-Whonix qubes?
Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-[Whonix][Qubes-Whonix] qubes.
This includes [DisposableVMs][disposable].
Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-[Whonix](/doc/whonix/) qubes.
This includes [DisposableVMs](/doc/disposablevm/).
For example, a standard [Fedora](/doc/templates/fedora/) qube is expected to have basically the same privacy properties as that upstream Fedora distribution, enhanced to some degree by the control Qubes provides over that qube.
For most users, this level of privacy may be good enough for many common activities.
However, users seeking more advanced privacy features should use [Whonix][Qubes-Whonix] qubes.
However, users seeking more advanced privacy features should use [Whonix](/doc/whonix/) qubes.
Privacy is far more difficult than is commonly understood.
In addition to the [web browser](https://www.torproject.org/projects/torbrowser/design/), there is also [VM fingerprinting](https://www.whonix.org/wiki/VM_Fingerprinting) and [advanced deanonymization attacks](https://www.whonix.org/wiki/Advanced_Deanonymization_Attacks) that most users have never considered (and this is just to mention a few examples).
@ -101,7 +101,7 @@ Read the [documentation](https://www.whonix.org/wiki/Documentation) thoroughly a
### How does Qubes OS compare to using a "live CD" OS?
Booting your computer from a live CD (or DVD) when you need to perform sensitive activities can certainly be more secure than simply using your main OS, but this method still preserves many of the risks of conventional OSes.
For example, popular live OSes (such as [Tails] and other Linux distributions) are still **monolithic** in the sense that all software is still running in the same OS.
For example, popular live OSes (such as [Tails](https://tails.boum.org/) and other Linux distributions) are still **monolithic** in the sense that all software is still running in the same OS.
This means, once again, that if your session is compromised, then all the data and activities performed within that same session are also potentially compromised.
### How does Qubes OS compare to running VMs in a conventional OS?
@ -114,7 +114,7 @@ These programs are popular because they're designed primarily to be easy to use
However, the fact that Type 2 hypervisors run under the host OS means that they're really only as secure as the host OS itself.
If the host OS is ever compromised, then any VMs it hosts are also effectively compromised.
By contrast, Qubes uses a "Type 1" or "bare metal" hypervisor called [Xen].
By contrast, Qubes uses a "Type 1" or "bare metal" hypervisor called [Xen](https://www.xenproject.org/).
Instead of running inside an OS, Type 1 hypervisors run directly on the "bare metal" of the hardware.
This means that an attacker must be capable of subverting the hypervisor itself in order to compromise the entire system, which is vastly more difficult.
@ -145,7 +145,7 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
- Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature.
- Malware which can bridge air gaps has existed for several years now and is becoming increasingly common.
(For more on this topic, please see the paper [Software compartmentalization vs. physical separation][paper-compart].)
(For more on this topic, please see the paper [Software compartmentalization vs. physical separation](https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf).)
### What is the main concept behind Qubes?
@ -153,12 +153,12 @@ To build security on the "Security by Compartmentalization (or Isolation)" princ
### What about other approaches to security?
The other two popular [approaches] are “Security by Correctness” and “Security by Obscurity.”
The other two popular [approaches](https://blog.invisiblethings.org/2008/09/02/three-approaches-to-computer-security.html) are “Security by Correctness” and “Security by Obscurity.”
We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### How is Qubes different from other security solutions?
Please see this [article] for a thorough discussion.
Please see this [article](https://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html) for a thorough discussion.
### Is Qubes just another Linux distribution?
@ -170,7 +170,7 @@ It also has a very unique GUI virtualization infrastructure.
### What about safe languages and formally verified microkernels?
In short: these are non-realistic solutions today.
We discuss this in further depth in our [Architecture Specification document].
We discuss this in further depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### Why does Qubes use virtualization?
@ -180,12 +180,12 @@ We believe that this is currently the only practically viable approach to implem
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [LUKS]/[dm-crypt].
You can even [manually configure your encryption parameters][custom_config] if you like!
Specifically, we use [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)/[dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt).
You can even [manually configure your encryption parameters](/doc/custom-install/) if you like!
### What do all these terms mean?
All Qubes-specific terms are defined in the [glossary]
All Qubes-specific terms are defined in the [glossary](/doc/glossary/)
### Does Qubes run every app in a separate VM?
@ -197,11 +197,11 @@ Very paranoid users, or those who are high-profile targets, might use a dozen or
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).
We discuss this in much greater depth in our [Architecture Specification document].
We discuss this in much greater depth in our [Architecture Specification document](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf).
### How is Qubes affected by Xen Security Advisories (XSAs)?
See the [XSA Tracker].
See the [XSA Tracker](/security/xsa/).
### What about this other/new (micro)kernel/hypervisor?
@ -247,38 +247,38 @@ At the same time, due to the smart use of Xen shared memory, our GUI implementat
### Why passwordless sudo?
Please refer to [this page].
Please refer to [this page](/doc/vm-sudo/).
### Why is dom0 so old?
Please see:
- [Installing and updating software in dom0]
- [Note on dom0 and EOL]
- [Installing and updating software in dom0](/doc/software-update-dom0/)
- [Note on dom0 and EOL](/doc/supported-versions/#note-on-dom0-and-eol)
### Do you recommend coreboot as an alternative to vendor BIOS?
Yes, where it is possible to use it an open source boot firmware ought to be more trustable than a closed source implementation.
[coreboot] is as a result a requirement for [Qubes Certified Hardware].
[coreboot](https://www.coreboot.org/) is as a result a requirement for [Qubes Certified Hardware](/news/2016/07/21/new-hw-certification-for-q4/).
The number of machines coreboot currently supports is limited and the use of some vendor supplied blobs is generally still required.
Where coreboot does support your machine and is not already installed, you will generally need additional hardware to flash it.
Please see the coreboot website / their IRC channel for further information.
### How should I report documentation issues?
Please see the [documentation guidelines].
Please see the [documentation guidelines](/doc/doc-guidelines).
### Will Qubes seek to get certified under the GNU Free System Distribution Guidelines (GNU FSDG)?
Not currently, for the same reasons that [Debian is not certified].
Not currently, for the same reasons that [Debian is not certified](https://www.gnu.org/distros/common-distros.en.html).
### Should I trust this website?
This website is hosted on [GitHub Pages][] ([why?][]).
This website is hosted on [GitHub Pages](https://pages.github.com/) ([why?](#why-do-you-use-github)).
Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure].
We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure).
For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web.
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo], [verify the PGP signatures on the commits and/or tags] signed by the [doc-signing keys] (which indicates that the content has undergone review per our [documentation guidelines]), then either [render the site on your local machine][render] or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason][Markdown].
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone review per our [documentation guidelines](/doc/doc-guidelines)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/doc-guidelines/#markdown-conventions).
We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
### What does it mean to "distrust the infrastructure"?
@ -292,28 +292,28 @@ Therefore, we believe the best solution is not to attempt to make the infrastruc
We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users.
Since we don't want to encourage or endorse this, we make our distrust of the infrastructure explicit.
Also see: [Should I trust this website?]
Also see: [Should I trust this website?](#should-i-trust-this-website)
### Why do you use GitHub?
Three main reasons:
1. We [distrust the infrastructure] including GitHub (though there are aspects we're still [working on](https://github.com/QubesOS/qubes-issues/issues/3958)).
1. We [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure) including GitHub (though there are aspects we're still [working on](https://github.com/QubesOS/qubes-issues/issues/3958)).
2. It's free (as in beer). We'd have to spend either time or money to implement a solution ourselves or pay someone to do so, and we can't spare either one right now.
3. It has low admin/overhead requirements, which is very important, given how little time we have to spare.
Also see: [Should I trust this website?]
Also see: [Should I trust this website?](#should-i-trust-this-website)
### Why doesn't this website have security feature X?
Although we caution users against [placing undue trust in this website][Should I trust this website?] because we [distrust the infrastructure], we have no objection to enabling website security features when doing so is relatively costless and provides some marginal benefit to website visitors.
Although we caution users against [placing undue trust in this website](#should-i-trust-this-website) because we [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure), we have no objection to enabling website security features when doing so is relatively costless and provides some marginal benefit to website visitors.
So, if feature X isn't enabled, it's most likely for one of three reasons:
1. Our GitHub Pages platform doesn't support it.
2. Our platform supports it, but we've decided not to enable it.
3. Our platform supports it, but we're not aware that we can enable it or have forgotten to do so.
If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]!
If it seems like a feature that we can and should enable, please [let us know](/doc/reporting-bugs/)!
## Users
@ -331,8 +331,8 @@ AppVMs use a software-only (CPU-based) implementation of OpenGL, which may be go
For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads:
- [GPU passing to HVM]
- [Clarifications on GPU security]
- [GPU passing to HVM](https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&)
- [Clarifications on GPU security](https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&)
### Is Qubes a multi-user system?
@ -340,22 +340,22 @@ No.
Qubes does not pretend to be a multi-user system.
Qubes assumes that the user who controls Dom0 controls the whole system.
It is very difficult to **securely** implement multi-user support.
See [here] for details.
See [here](https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06) for details.
However, in Qubes 4.x we will be implementing management functionality.
See [Admin API] and [Core Stack] for more details.
See [Admin API](/news/2017/06/27/qubes-admin-api/) and [Core Stack](/news/2017/10/03/core3/) for more details.
### What are the system requirements for Qubes OS?
See the [system requirements].
See the [system requirements](/doc/system-requirements/).
### Is there a list of hardware that is compatible with Qubes OS?
See the [Hardware Compatibility List].
See the [Hardware Compatibility List](/hcl/).
### Is there any certified hardware for Qubes OS?
See [Certified Hardware].
See [Certified Hardware](/doc/certified-hardware/).
### How much disk space does each qube require?
@ -366,11 +366,11 @@ This also means that it is possible to update the software for several qubes sim
### How much memory is recommended for Qubes?
Please see the [system requirements].
Please see the [system requirements](/doc/system-requirements/).
### Can I install Qubes on a system without VT-x/AMD-V or VT-d/ADM-Vi/AMD IOMMU?
Please see the [system requirements] for the latest information.
Please see the [system requirements](/doc/system-requirements/) for the latest information.
If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration.
You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation.
For more information, see [Qubes-certified hardware](/doc/certified-hardware/).
@ -405,7 +405,7 @@ Most attacks on the NetVM and USB VM (but not all of them!) require being somewh
### Can I use AMD-v instead of VT-x?
Yes, and see [this message].
Yes, and see [this message](https://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5).
### Can I install Qubes in a virtual machine (e.g., on VMware)?
@ -415,11 +415,11 @@ Qubes should be installed bare-metal.
### What is a terminal?
A [terminal emulator], nowadays often referred to as just a *terminal*, is a program which provides a text window.
Inside that window, a [shell] is typically running in it.
A shell provides a [command-line interface] where the user can enter and run [commands].
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator), nowadays often referred to as just a *terminal*, is a program which provides a text window.
Inside that window, a [shell](https://en.wikipedia.org/wiki/Shell_(computing)) is typically running in it.
A shell provides a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) where the user can enter and run [commands](https://en.wikipedia.org/wiki/Command_(computing)).
See introductions on Wikibooks: [here][intro1], [here][intro2] and [here][intro3].
See introductions on Wikibooks: [here](https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics), [here](https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix) and [here](https://en.wikibooks.org/wiki/Bash_Shell_Scripting).
### Why does my network adapter not work?
@ -432,12 +432,12 @@ You have to restart the NetVM after the TemplateVM has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it poses a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting].
But if you understand the risk and accept it, read [documentation on multibooting](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md).
It begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running?
See [here][version].
See [here](/doc/version-scheme/#check-installed-version).
### My qubes lost internet access after a TemplateVM update. What should I do?
@ -483,7 +483,7 @@ or
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
```
See also [here][assign_devices].
See also [here](/doc/assigning-devices/).
### How do I install Flash in a Debian qube?
@ -518,7 +518,7 @@ For Debian:
For Fedora:
1. (Recommended) Clone an existing Fedora TemplateVM
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM][Enable RPMFusion].
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM](/doc/software-update-domu/#rpmfusion-for-fedora-templatevms).
3. Install VLC in that TemplateVM:
```bash_session
@ -540,7 +540,7 @@ From the top part of the list, click on the drive you want to attach, then selec
Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface.
Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube.
See [Block (Storage) Devices][storage](/doc/block-devices/) for more information.
See [Block (Storage) Devices](/doc/block-devices/) for more information.
### My encrypted drive doesn't appear in Debian qube.
@ -686,8 +686,6 @@ No. Unlike many other virtualization systems, Qubes takes special effort to keep
This has been achieved thanks to the careful use of Xen's stub domain feature.
For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html).
[force_usb2]: https://www.systutorials.com/qa/1908/how-to-force-a-usb-3-0-port-to-work-in-usb-2-0-mode-in-linux
### Is Secure Boot supported?
UEFI Secure Boot is not supported out of the box as UEFI support in Xen is very basic.
@ -704,70 +702,7 @@ If you need to support not-fully-updated systems, check for the existence of `/u
### Is there a way to automate tasks for continuous integration or DevOps?
Yes, Qubes natively supports automation via [Salt (SaltStack)][Salt].
There is also the unofficial [ansible-qubes toolkit][ansible].
Yes, Qubes natively supports automation via [Salt (SaltStack)](/doc/salt/).
There is also the unofficial [ansible-qubes toolkit](https://github.com/Rudd-O/ansible-qubes).
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
[4.x System Requirements]: /doc/system-requirements/#qubes-release-4x
[Admin API]: /news/2017/06/27/qubes-admin-api/
[ansible]: https://github.com/Rudd-O/ansible-qubes
[Anti Evil Maid]: /doc/anti-evil-maid/
[approaches]: https://blog.invisiblethings.org/2008/09/02/three-approaches-to-computer-security.html
[Architecture Specification document]: /attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf
[article]: https://blog.invisiblethings.org/2012/09/12/how-is-qubes-os-different-from.html
[assign_devices]: /doc/assigning-devices/
[Certified Hardware]: /doc/certified-hardware/
[Clarifications on GPU security]: https://groups.google.com/group/qubes-devel/browse_frm/thread/31e2d8a47c8b4474?scoring=d&q=GPU&
[clipboard]: /doc/copy-paste
[command-line interface]: https://en.wikipedia.org/wiki/Command-line_interface
[commands]: https://en.wikipedia.org/wiki/Command_(computing)
[coreboot]: https://www.coreboot.org/
[Core Stack]: /news/2017/10/03/core3/
[custom_config]: /doc/custom-install/
[Debian is not certified]: https://www.gnu.org/distros/common-distros.en.html
[disposable]: /doc/disposablevm/
[disposable qube]: /doc/dispvm/
[distrust the infrastructure]: #what-does-it-mean-to-distrust-the-infrastructure
[dm-crypt]: https://en.wikipedia.org/wiki/Dm-crypt
[doc-signing keys]: https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing
[documentation guidelines]: /doc/doc-guidelines
[documentation on multibooting]: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
[Enable RPMFusion]: /doc/software-update-domu/#rpmfusion-for-fedora-templatevms
[file]: /doc/copying-files
[firewalls]: /doc/firewall
[GitHub Pages]: https://pages.github.com/
[glossary]: /doc/glossary/
[GPU passing to HVM]: https://groups.google.com/group/qubes-devel/browse_frm/thread/31f1f2da39978573?scoring=d&q=GPU&
[Hardware Compatibility List]: /hcl/
[here]: https://groups.google.com/group/qubes-devel/msg/899f6f3efc4d9a06
[Installing and updating software in dom0]: /doc/software-update-dom0/
[intro1]: https://en.wikibooks.org/wiki/Fedora_And_Red_Hat_System_Administration/Shell_Basics
[intro2]: https://en.wikibooks.org/wiki/A_Quick_Introduction_to_Unix
[intro3]: https://en.wikibooks.org/wiki/Bash_Shell_Scripting
[LUKS]: https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup
[Markdown]: /doc/doc-guidelines/#markdown-conventions
[network]: /doc/networking/
[Note on dom0 and EOL]: /doc/supported-versions/#note-on-dom0-and-eol
[paper-compart]: https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf
[Qubes Certified Hardware]: /news/2016/07/21/new-hw-certification-for-q4/
[Qubes-Whonix]: /doc/whonix/
[render]: https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions
[Salt]: /doc/salt/
[shell]: https://en.wikipedia.org/wiki/Shell_(computing)
[Should I trust this website?]: #should-i-trust-this-website
[storage]: /doc/block-devices/
[system requirements]: /doc/system-requirements/
[Tails]: https://tails.boum.org/
[Template]: /doc/template-implementation
[terminal emulator]: https://en.wikipedia.org/wiki/Terminal_emulator
[this message]: https://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5
[this page]: /doc/vm-sudo/
[Tor]: https://www.torproject.org/
[USB]: /doc/usb-devices
[verify the PGP signatures on the commits and/or tags]: /security/verifying-signatures/#how-to-verify-qubes-repos
[version]: /doc/version-scheme/#check-installed-version
[website repo]: https://github.com/QubesOS/qubesos.github.io
[why?]: #why-do-you-use-github
[Xen]: https://www.xenproject.org/
[XSA Tracker]: /security/xsa/
[reporting-bugs]: /doc/reporting-bugs/

72
introduction/reporting-bugs.md
View File

@ -17,24 +17,24 @@ title: Reporting bugs and other issues
# 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], our GitHub issue tracker.
If you're looking for help, please see [Help, Support, Mailing Lists, and Forum].
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] page.**
- **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].**
- **If you see something that should be changed in the documentation, [submit a change][Documentation Guidelines].**
- **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.][qubes-issues-all]
[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][qubes-issues-bug-up-desc].
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.][qubes-issues-labels]
For example, you can search issues by priority ([blocker], [critical], [major], etc.) and by component ([core], [manager/widget], [Xen], 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`).
@ -46,19 +46,19 @@ Issues may have additional labels, if applicable (e.g., `crypto`, `ux`).
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]).
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.
### Do not submit questions ###
[qubes-issues] is not the place to ask 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] for appropriate place to ask questions.
By contrast, [qubes-issues] is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
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.
### Every issue must be about a single, actionable thing ###
If your issue is not actionable, please see [Help, Support, Mailing Lists, and Forum] for the appropriate place to post it.
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.
### New issues should not be duplicates of existing issues ###
@ -82,11 +82,11 @@ 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]).
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/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][hcl-howto], then linking to it in your issue.
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] repository, please reference the appropriate issue in the [updates-status] repository.
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!
@ -112,8 +112,8 @@ The Qubes team has its own roadmap and priorities, which will govern the manner
## 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] repository, then to the appropriate stable repository.
If you so choose, you can test the fix while it's in the [testing] repository, or you can wait for it to land in the stable repository.
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.
@ -125,32 +125,10 @@ If the issue is closed without one of these specific resolutions, then it means,
## See also ##
- [Help, Support, Mailing Lists, and Forum]
- [Testing New Releases and Updates][testing]
- [How to Contribute]
- [Contributing Code]
- [Package Contributions]
- [Documentation Guidelines]
- [Help, Support, Mailing Lists, and Forum](/support/)
- [Testing New Releases and Updates](/doc/testing/)
- [How to Contribute](/doc/contributing/)
- [Contributing Code](/doc/contributing/#contributing-code)
- [Package Contributions](/doc/package-contributions/)
- [Documentation Guidelines](/doc/doc-guidelines/)
[qubes-issues-all]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue
[qubes-issues-bug-up-desc]: https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc
[qubes-issues-labels]: https://github.com/QubesOS/qubes-issues/labels
[blocker]: https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker
[critical]: https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical
[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
[major]: https://github.com/QubesOS/qubes-issues/labels/P%3A%20major
[Security]: /security/
[documentation]: /doc/
[website]: /
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[Help, Support, Mailing Lists, and Forum]: /support/
[updates-status]: https://github.com/QubesOS/updates-status/issues
[how to copy information out of dom0]: /doc/copy-from-dom0/
[testing]: /doc/testing/
[How to Contribute]: /doc/contributing/
[Contributing Code]: /doc/contributing/#contributing-code
[Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

12
introduction/statistics.md
View File

@ -26,7 +26,7 @@ Since the graph is updated daily, the bar for the current month will be very low
### How is the userbase estimated?
We simply count the number of unique IPv4 addresses that connect to the Qubes update servers each month (except for Tor connections; see [below][tor-methodology]).
We simply count the number of unique IPv4 addresses that connect to the Qubes update servers each month (except for Tor connections; see [below](#how-has-the-methodology-for-counting-tor-users-changed)).
### How has the methodology for counting Tor users changed?
@ -46,7 +46,7 @@ Where:
- `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month.
- `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month.
We cross-reference the list of connecting IP addresses with [TorDNSEL's exit lists] in order to distinguish Tor and clearnet IPs and requests.
We cross-reference the list of connecting IP addresses with [TorDNSEL's exit lists](https://metrics.torproject.org/collector.html#type-tordnsel) in order to distinguish Tor and clearnet IPs and requests.
For this purpose, we count an IP address as belonging to a Tor exit node if there was a Tor exit node active for that address within the 24-hour periods before or after it connected to the Qubes update servers.
### What kinds of data do you collect about Qubes users?
@ -61,12 +61,8 @@ We do not collect any other kinds of data about Qubes users.
### Where can I find the raw data and source code?
The raw data is available [here][raw-data].
The raw data is available [here](https://tools.qubes-os.org/counter/stats.json).
(This does not include any personally-identifying user data.)
Please note that the format of this data is not documented and may change any time if the developers feel the need to include something else.
The source code is available [here][source-code].
The source code is available [here](https://github.com/woju/qubes-stats).
[tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed
[TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel
[raw-data]: https://tools.qubes-os.org/counter/stats.json
[source-code]: https://github.com/woju/qubes-stats

143
introduction/support.md
View File

@ -17,14 +17,14 @@ title: Help, Support, Mailing Lists, and Forum
# Help, Support, Mailing Lists, and Forum
Help and support for Qubes OS is available from the [documentation], the
[mailing lists], and our [forum] which are explained below. The Qubes OS
Help and support for Qubes OS is available from the [documentation](/doc/), the
[mailing lists](#mailing-lists), and our [forum](#forum) which are explained below. The Qubes OS
Project does not offer paid support services.
If you're looking for known issues or would like to file a bug report, please
see the [issue tracker]. These issues are constantly being updated and may
see the [issue tracker](/doc/reporting-bugs/). These issues are constantly being updated and may
contain workarounds for problems that you're experiencing, so it's worth
[searching the issue tracker] as a first step. However, please note that
[searching the issue tracker](/doc/reporting-bugs/#search-tips) as a first step. However, please note that
[the issue tracker is not a discussion forum](/doc/reporting-bugs/#the-issue-tracker-is-not-a-discussion-forum).
## Staying safe
@ -39,35 +39,35 @@ The Qubes community includes people from all walks of life and from around the
world. Individuals differ in areas of experience and technical expertise. You
will come into contact with others whose views and agendas differ from your own.
Everyone is free to write what they please, as long as it doesn't violate our
[Code of Conduct][coc]. Be friendly and open, but do not believe everything you
[Code of Conduct](/code-of-conduct/). Be friendly and open, but do not believe everything you
read. Use good judgment, and be especially careful when following instructions
(e.g., copying commands) given by others on the lists.
All official announcements from the [Qubes team] to a mailing list will be
All official announcements from the [Qubes team](/team/) to a mailing list will be
signed by the PGP key belonging to the team member who sends the announcement.
However, anyone on a mailing list can choose to sign their messages, so the
presence of a PGP signature does not indicate authority. How, then, should you
sort the good advice from the bad?
This is up to each individual to decide, but it helps to know that many members
of our community have proven themselves knowledgeable through their
[contributions] to the project. Typically, these individuals sign their messages
[contributions](/doc/contributing/) to the project. Typically, these individuals sign their messages
with the same key as (or another key authenticated by) the one they use to
[sign their contributions][code-signing].
[sign their contributions](/doc/code-signing/).
For example, you might find it easier to trust advice from someone who has a
proven track record of [contributing software packages] or [contributing to the
documentation]. It's unlikely that individuals who have worked hard to build
proven track record of [contributing software packages](/doc/package-contributions/) or [contributing to the
documentation](/doc/doc-guidelines/). It's unlikely that individuals who have worked hard to build
good reputations for themselves through their contributions over the years would
risk giving malicious advice in signed messages to public mailing lists. Since
every contribution to the Qubes OS Project is publicly visible and
cryptographically signed, anyone would be in a position to [verify] that these
cryptographically signed, anyone would be in a position to [verify](/security/verifying-signatures/) that these
came from the same keyholder.
## Discussion guidelines
Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our
[forum], all of which are explained below. Most questions should be directed to
`qubes-users` or the [forum]. **Please do not send questions to individual
[forum](#forum), all of which are explained below. Most questions should be directed to
`qubes-users` or the [forum](#forum). **Please do not send questions to individual
Qubes developers.** By sending a message to the appropriate mailing list, you
are not only giving others a chance to help you, but you may also be helping
others by starting a public discussion about a shared problem or interest.
@ -104,8 +104,8 @@ documentation pages you've already read. Put yourself in your readers' shoes.
What essential information would they require in order to be able to help
you? Make sure to include that information in your message. A great way to
provide your hardware details is by [generating and submitting a Hardware
Compatibility List (HCL) report][hcl-howto], then linking to it in your
message. [Ask questions the smart way.][smart-questions]
Compatibility List (HCL) report](/doc/hcl/#generating-and-submitting-new-reports), then linking to it in your
message. [Ask questions the smart way.](http://www.catb.org/esr/faqs/smart-questions.html)
### Be patient
@ -131,24 +131,24 @@ to earn the good will of others. This does not mean that you will not receive
help. On the contrary, we are fortunate to have such a helpful and
understanding community that many of them spend hours of their personal time
helping complete strangers, including many who post anonymously. (Given the
integration of Qubes with [Whonix], we understand better than most the
integration of Qubes with [Whonix](/doc/whonix/), we understand better than most the
complexities of privacy and anonymity, and we know that many users have no
other choice but to post anonymously.) You can read our project's [Code of
Conduct][coc] for more information.
Conduct](/code-of-conduct/) for more information.
### Report issues and submit changes in the right places
The mailing lists and [forum] are good places to ask questions and discuss
The mailing lists and [forum](#forum) are good places to ask questions and discuss
things. However, if you're submitting a more formal report, we'd prefer that
you submit it to our [issue tracker] so that it doesn't get overlooked.
you submit it to our [issue tracker](/doc/reporting-bugs/) so that it doesn't get overlooked.
(However, please remember that [the issue tracker is not a discussion forum](/doc/reporting-bugs/#the-issue-tracker-is-not-a-discussion-forum).)
Likewise, if you see that something in the documentation should be changed,
don't simply point it out in a discussion venue. Instead, [submit the
change][contributing to the documentation].
change](/doc/doc-guidelines/).
### Moderation
The moderation team aims to enforce our [Code of Conduct][coc].
The moderation team aims to enforce our [Code of Conduct](/code-of-conduct/).
Beyond this, users should not expect any specific action from the moderation team.
Specifically, users should not request that posts or messages be deleted or edited by a moderator.
Users are reminded that, in most venues, anything posted will be sent out as an email to other others, and these emails cannot be deleted from others' inboxes.
@ -162,10 +162,10 @@ which list is correct for your message.
#### Do not top-post
[Top-posting] is placing your reply above the quoted message to which you're
replying. Please refrain from doing this. Instead, either [interleave] your
[Top-posting](https://en.wikipedia.org/wiki/Posting_style#Top-posting) is placing your reply above the quoted message to which you're
replying. Please refrain from doing this. Instead, either [interleave](https://en.wikipedia.org/wiki/Posting_style#Interleaved_style) your
reply by placing parts of your message immediately below each quoted portion
to which it is replying, or [bottom-post] by placing your entire reply below
to which it is replying, or [bottom-post](https://en.wikipedia.org/wiki/Posting_style#Bottom-posting) by placing your entire reply below
the quoted message to which you're replying.
#### Use proper subject lines
@ -212,7 +212,7 @@ will ask for clarification if needed.
#### Suggestions
While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
note that we already have a pretty well defined [roadmap](https://github.com/QubesOS/qubes-issues/milestones), and it's rather
unlikely that we will change our schedule in order to accommodate your
request. If there's a particular feature you'd like to see in Qubes, a much
more effective way to make it happen is to contribute a patch that implements
@ -226,37 +226,37 @@ something that we may not be able or willing to accept.
While the mailing lists are implemented as Google Group web forums, a Google
account is in no way required, expected, or encouraged. Many discussants
(including most members of the Qubes team) treat these lists as conventional
[mailing lists][wiki-ml], interacting with them solely through plain text email
with [MUAs] like [Thunderbird] and [Mutt]. The Google Groups service is just
free infrastructure, and we [distrust the infrastructure]. This is why, for
example, we encourage discussants to use [Split GPG] to sign all of their
[mailing lists](https://en.wikipedia.org/wiki/Electronic_mailing_list), interacting with them solely through plain text email
with [MUAs](https://en.wikipedia.org/wiki/Email_client) like [Thunderbird](https://www.thunderbird.net/) and [Mutt](http://www.mutt.org/). The Google Groups service is just
free infrastructure, and we [distrust the infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure). This is why, for
example, we encourage discussants to use [Split GPG](/doc/split-gpg/) to sign all of their
messages to the lists, but we do not endorse the use of these Google Groups
as web forums. For that, we have a separate, dedicated [forum].
as web forums. For that, we have a separate, dedicated [forum](#forum).
## Mailing lists
This section covers each of our individual [mailing lists][wiki-ml], with
This section covers each of our individual [mailing lists](https://en.wikipedia.org/wiki/Electronic_mailing_list), with
details about the purpose of each list and how to use it.
### qubes-announce
This is a read-only list for those who wish to receive only very important,
infrequent messages. Only the core Qubes team can post to this list. Only
[Qubes Security Bulletins (QSBs)][qsb], new stable releases, and end-of-life
[Qubes Security Bulletins (QSBs)](/security/bulletins/), new stable releases, and end-of-life
notices are announced here.
To subscribe, send a blank email to
`qubes-announce+subscribe@googlegroups.com`. (Note: A Google account is *not*
required. Any email address will work.) To unsubscribe, send a blank email to
`qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional
[Google Groups web interface][qubes-announce-web].
[Google Groups web interface](https://groups.google.com/group/qubes-announce).
### qubes-users
This list is for helping users solve various daily problems with Qubes OS.
Examples of topics or questions suitable for this list include:
* [HCL] reports
* [HCL](/doc/hcl/) reports
* Installation problems
* Hardware compatibility problems
* Questions of the form: "How do I...?"
@ -266,10 +266,10 @@ lists before sending a question. In addition, please make sure that you have
read and understood the following basic documentation prior to posting to the
list:
* The [Installation Guide], [System Requirements], and [HCL] (for problems
* The [Installation Guide](/doc/installation-guide/), [System Requirements](/doc/system-requirements/), and [HCL](/doc/hcl/) (for problems
related to installing Qubes OS)
* The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS)
* The [User FAQ](/faq/#users)
* The [documentation](/doc/) (for questions about how to use Qubes OS)
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
@ -279,8 +279,8 @@ email to `qubes-users+subscribe@googlegroups.com`. (Note: A Google account is
address your email to `qubes-users@googlegroups.com`. If your post does not
appear immediately, please allow time for moderation to occur. To unsubscribe,
send a blank email to `qubes-users+unsubscribe@googlegroups.com`. This list
also has an optional [Google Groups web interface][qubes-users-web] and
[traditional mail archive][qubes-users-archive].
also has an optional [Google Groups web interface](https://groups.google.com/group/qubes-users) and
[traditional mail archive](https://www.mail-archive.com/qubes-users@googlegroups.com/).
### qubes-devel
@ -302,8 +302,8 @@ account is *not* required. Any email address will work.) To post a message to
the list, address your email to `qubes-devel@googlegroups.com`. If your post
does not appear immediately, please allow time for moderation to occur. To
unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-devel-web]
and [traditional mail archive][qubes-devel-archive].
This list also has an optional [Google Groups web interface](https://groups.google.com/group/qubes-devel)
and [traditional mail archive](https://www.mail-archive.com/qubes-devel@googlegroups.com/).
### qubes-project
@ -315,7 +315,7 @@ Examples of topics or question suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
* Most Github issues tagged "[business](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Abusiness)"
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
@ -325,7 +325,7 @@ required. Any email address will work.) To post a message to the list, address
your email to `qubes-project@googlegroups.com`. If your post does not appear
immediately, please allow time for moderation to occur. To unsubscribe, send a
blank email to `qubes-project+unsubscribe@googlegroups.com`. This list also
also has an optional [Google Groups web interface][qubes-project-web].
also has an optional [Google Groups web interface](https://groups.google.com/group/qubes-project).
### qubes-translation
@ -334,9 +334,9 @@ its documentation, and the website.
Examples of topics or question suitable for this list include:
* Questions about or issues with [Transifex], the translation platform we use
* Questions about or issues with [Transifex](https://www.transifex.com/), the translation platform we use
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
* Most Github issues tagged "[localization](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Alocalization)"
You don't have to subscribe in order to post to this list. However, subscribing
makes your messages less likely to be marked as spam and allows you to receive
@ -347,7 +347,7 @@ address your email to `qubes-translation@googlegroups.com`. If your post does
not appear immediately, please allow time for moderation to occur. To
unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`. This list also has an
optional [Google Groups web interface][qubes-translation-web].
optional [Google Groups web interface](https://groups.google.com/group/qubes-translation).
## Forum
@ -358,9 +358,9 @@ We have a community forum for Qubes OS users:
This is an official user forum where you can ask questions, get help, share
tips and experiences, and more! For a long time, members of our community have
sought a privacy-respecting forum experience with modern features that
traditional mailing lists do not support. The open-source [Discourse] platform
traditional mailing lists do not support. The open-source [Discourse](https://www.discourse.org/) platform
fills this need for us, as it does for many other open-source projects. Thanks
to their generous [free hosting for open source projects], we're pleased to be
to their generous [free hosting for open source projects](https://blog.discourse.org/2018/11/free-hosting-for-open-source-v2/), we're pleased to be
able to create this space for our community.
### Why was this forum created?
@ -391,7 +391,7 @@ decide where and how you want to join the conversation.
Many open-source projects (such as Fedora and Debian) have both mailing lists
and forums (and additional discussion venues). In fact, Qubes already had
non-mailing-list discussion venues such as [IRC] and [Reddit] before this forum
non-mailing-list discussion venues such as [IRC](#unofficial-chat-channels) and [Reddit](https://www.reddit.com/r/Qubes/) before this forum
was introduced. We believe that this additional venue fosters the continued
growth of community participation and improves everyone's experience. In
addition, we fully expect that many community members -- especially the most
@ -421,48 +421,3 @@ The following unofficial chat channels are maintained by the community:
* Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
* `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/>
[mailing lists]: #mailing-lists
[wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list
[Qubes team]: /team/
[contributions]: /doc/contributing/
[code-signing]: /doc/code-signing/
[contributing software packages]: /doc/package-contributions/
[contributing to the documentation]: /doc/doc-guidelines/
[verify]: /security/verifying-signatures/
[qsb]: /security/bulletins/
[qubes-announce-web]: https://groups.google.com/group/qubes-announce
[Top-posting]: https://en.wikipedia.org/wiki/Posting_style#Top-posting
[interleave]: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
[bottom-post]: https://en.wikipedia.org/wiki/Posting_style#Bottom-posting
[roadmap]: https://github.com/QubesOS/qubes-issues/milestones
[smart-questions]: http://www.catb.org/esr/faqs/smart-questions.html
[Whonix]: /doc/whonix/
[HCL]: /doc/hcl/
[Installation Guide]: /doc/installation-guide/
[System Requirements]: /doc/system-requirements/
[User FAQ]: /faq/#users
[documentation]: /doc/
[MUAs]: https://en.wikipedia.org/wiki/Email_client
[Thunderbird]: https://www.thunderbird.net/
[Mutt]: http://www.mutt.org/
[distrust the infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[Split GPG]: /doc/split-gpg/
[thunderbird-newsgroup]: https://support.mozilla.org/en-US/kb/creating-newsgroup-account
[qubes-users-archive]: https://www.mail-archive.com/qubes-users@googlegroups.com/
[qubes-devel-archive]: https://www.mail-archive.com/qubes-devel@googlegroups.com/
[qubes-users-web]: https://groups.google.com/group/qubes-users
[qubes-devel-web]: https://groups.google.com/group/qubes-devel
[qubes-translation-web]: https://groups.google.com/group/qubes-translation
[qubes-project-web]: https://groups.google.com/group/qubes-project
[business]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Abusiness
[localization]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Alocalization
[coc]: /code-of-conduct/
[Transifex]: https://www.transifex.com/
[issue tracker]: /doc/reporting-bugs/
[searching the issue tracker]: /doc/reporting-bugs/#search-tips
[forum]: #forum
[Discourse]: https://www.discourse.org/
[free hosting for open source projects]: https://blog.discourse.org/2018/11/free-hosting-for-open-source-v2/
[IRC]: #unofficial-chat-channels
[Reddit]: https://www.reddit.com/r/Qubes/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

61
project-security/security.md
View File

@ -18,35 +18,35 @@ title: Security
# Qubes OS Project Security Center
- [Security FAQ]
- [Security Goals]
- [Security Pack]
- [Security Bulletins]
- [Canaries]
- [Xen Security Advisory (XSA) Tracker]
- [Why and How to Verify Signatures]
- [PGP Keys]
- [Security FAQ](/faq/#general--security)
- [Security Goals](/security/goals/)
- [Security Pack](/security/pack/)
- [Security Bulletins](/security/bulletins/)
- [Canaries](/security/canaries/)
- [Xen Security Advisory (XSA) Tracker](/security/xsa/)
- [Why and How to Verify Signatures](/security/verifying-signatures/)
- [PGP Keys](https://keys.qubes-os.org/keys/)
## 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.
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].
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] that is responsible for ensuring the security of Qubes OS and the Qubes OS Project.
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]
- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of 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, signing, and publishing [Security Bulletins]
- Writing, signing, and publishing [Canaries]
- Generating, safeguarding, and using the project's [PGP Keys]
- 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/)
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:
@ -57,30 +57,13 @@ security at qubes-os dot org
### Security Team PGP Key
Please use the [Security Team PGP Key] to encrypt all emails sent to this address.
This key is signed by the [Qubes Master Signing Key].
Please see [Why and How to Verify 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
- [Marek Marczykowski-Górecki]
- [Simon Gaiser (aka HW42)]
- [Joanna Rutkowska] ([emeritus, canaries only])
- [Marek Marczykowski-Górecki](/team/#marek-marczykowski-górecki)
- [Simon Gaiser (aka HW42)](/team/#simon-gaiser-aka-hw42)
- [Joanna Rutkowska](/team/#joanna-rutkowska) ([emeritus, canaries only](/news/2018/11/05/qubes-security-team-update/))
[Security FAQ]: /faq/#general--security
[Security Goals]: /security/goals/
[Security Pack]: /security/pack/
[Security Bulletins]: /security/bulletins/
[Canaries]: /security/canaries/
[Xen Security Advisory (XSA) Tracker]: /security/xsa/
[Why and How to Verify Signatures]: /security/verifying-signatures/
[PGP Keys]: https://keys.qubes-os.org/keys/
[Qubes Team]: /team/
[reported security issues]: #reporting-security-issues-in-qubes-os
[Security Team PGP Key]: https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc
[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
[Marek Marczykowski-Górecki]: /team/#marek-marczykowski-górecki
[Simon Gaiser (aka HW42)]: /team/#simon-gaiser-aka-hw42
[Joanna Rutkowska]: /team/#joanna-rutkowska
[emeritus, canaries only]: /news/2018/11/05/qubes-security-team-update/
[Updating Qubes OS]: /doc/updating-qubes-os/

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

@ -29,26 +29,26 @@ The point is that we must decide who we will trust (e.g., Linus Torvalds, Micros
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][website-trust]), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc.
We call this philosophy [Distrusting 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).
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], not just verifying ISOs.)
(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:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. [Verify your Qubes ISO][signature file]
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] below.
If you run into any problems, please consult the [Troubleshooting FAQ](#troubleshooting-faq) below.
### Preparation
@ -70,13 +70,13 @@ If that still doesn't work, please consult the documentation for your specific p
### 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] (`0xDDFA1A3E36879494`).
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]):
- 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
@ -96,19 +96,19 @@ 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][Qubes Master Signing Key], 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] (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] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
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.
@ -133,7 +133,7 @@ uid Qubes Master Signing Key
```
But how do you know that this is the real fingerprint?
After all, [this website could be compromised][website-trust], so the fingerprint you see here may not be genuine.
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:
@ -216,7 +216,7 @@ The filename of the Release Signing Key for your version is usually `qubes-relea
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][copy-from-dom0] into other VMs for further use.
These can be [copied](/doc/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.:
@ -231,8 +231,8 @@ There are several ways to get the Release Signing Key for your Qubes release.
```
- Download it as a file.
You can find the Release Signing Key for your Qubes version on the [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] and the [Qubes OS Keyserver].
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
@ -271,7 +271,7 @@ If you don't see the correct Release Signing Key here, go back and follow the in
### 3. Verify your Qubes ISO
Every Qubes ISO is released with a detached PGP signature file, which you can find on the [Downloads] page alongside the 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`.
@ -298,7 +298,7 @@ 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] page, and you can always find all the digest files for every Qubes ISO in the [Qubes Security Pack].
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`.
@ -376,8 +376,8 @@ However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a m
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:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
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:
```shell_session
@ -392,11 +392,11 @@ Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to
```
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][QMSK]), we can be confident that these hash values came from the Qubes devs.
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], you should verify the PGP signature in a tag on the latest commit or on the latest commit itself.
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.
@ -426,17 +426,17 @@ 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]) rather than relying on a third party, such as GitHub.
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]
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][RSK].
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'"?
@ -445,8 +445,8 @@ 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][signature file] carefully.
- The ISO or [signature file] is bad (e.g., incomplete or corrupt download).
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.
@ -466,21 +466,21 @@ 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"?
The correct [signature file] 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], or you inverted the arguments to `gpg2`.
([The signature file goes first.][signature file])
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."?
Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK].
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][QMSK] and the [Release Signing Key][RSK] for your Qubes version.
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?
@ -491,28 +491,28 @@ 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].
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].
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], or the signature file has been modified.
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] and the [digest file]?
### 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].
You're not checking the correct [digest file](#how-to-verify-qubes-iso-digests).
### Why am I getting "WARNING: X lines are improperly formatted"?
Read [How to Verify Qubes ISO Digests][digest file] again.
Read [How to Verify Qubes ISO Digests](#how-to-verify-qubes-iso-digests) again.
### Why am I getting "WARNING: 1 listed file could not be read"?
@ -521,29 +521,8 @@ 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][QMSK], the [Release Signing Key][RSK], *and* the [signature file] and/or [digest file] all for the *correct* Qubes OS version.
If your question is about GPG, please see the [GPG documentation].
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] for places where you can ask!
Please see [Help, Support, Mailing Lists, and Forum](/support/) for places where you can ask!
[website-trust]: /faq/#should-i-trust-this-website
[Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[verifying repos]: #how-to-verify-qubes-repos
[Qubes Master Signing Key]: https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
[keyserver]: https://en.wikipedia.org/wiki/Key_server_%28cryptographic%29#Keyserver_examples
[Downloads]: /downloads/
[Qubes Security Pack]: /security/pack/
[Qubes OS Keyserver]: https://keys.qubes-os.org/keys/
[devel-master-key-msg]: https://groups.google.com/d/msg/qubes-devel/RqR9WPxICwg/kaQwknZPDHkJ
[user-master-key-msg]: https://groups.google.com/d/msg/qubes-users/CLnB5uFu_YQ/ZjObBpz0S9UJ
[mailing lists]: /support/
[Troubleshooting FAQ]: #troubleshooting-faq
[QMSK]: #1-get-the-qubes-master-signing-key-and-verify-its-authenticity
[RSK]: #2-get-the-release-signing-key
[copy-from-dom0]: /doc/copy-from-dom0/#copying-from-dom0
[signature file]: #3-verify-your-qubes-iso
[digest file]: #how-to-verify-qubes-iso-digests
[Qubes repositories]: https://github.com/QubesOS
[GPG documentation]: https://www.gnupg.org/documentation/
[Help, Support, Mailing Lists, and Forum]: /support/
[except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544

15
project-security/xsa.md
View File

@ -9,9 +9,9 @@ title: Xen Security Advisory (XSA) Tracker
Xen Security Advisory (XSA) Tracker
===================================
This tracker shows whether Qubes OS is affected by any given [Xen Security Advisory (XSA)][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)][QSB] is published, and a link to that QSB is added to the row for the associated XSA.
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**.
@ -21,17 +21,12 @@ Under the "Is Qubes Affected?" column, there are two possible values: **Yes** or
Important Notes
---------------
* For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] as affecting the *security* of Qubes OS.
* 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] 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] section for the sake of accuracy.
* 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.
[XSA]: https://xenbits.xen.org/xsa/
[QSB]: /security/bulletins/
[DoS]: https://en.wikipedia.org/wiki/Denial-of-service_attack
[Xen Security Policy]: https://www.xenproject.org/security-policy.html
[Statistics]: #statistics

6
user/advanced-configuration/bind-dirs.md
View File

@ -21,7 +21,7 @@ In a TemplateBasedVM all of the file system comes from the template except `/hom
This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix][whonix]
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## How to use bind-dirs.sh? ##
@ -85,7 +85,7 @@ Note that you must create the full folder structure under `/rw/bind-dirs` - e.g
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
* Some files are altered when a qube boots - e.g. `/etc/hosts`.
If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`][config-file]
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
## How to remove binds from bind-dirs.sh? ##
@ -105,5 +105,3 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)
[config-file]: /doc/config-files
[whonix]: https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5

10
user/advanced-configuration/installing-contributed-packages.md
View File

@ -9,14 +9,14 @@ title: Installing contributed packages
# Installing contributed packages
_This page is for users who wish to install contributed packages.
If you want to contribute a package, please see [package contributions]._
If you want to contribute a package, please see [package contributions](/doc/package-contributions/)._
Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
Qubes OS contributed packages are available under the [QubesOS-contrib](https://github.com/QubesOS-contrib/) GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations](/doc/package-contributions/).
## Installing the repositories
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib] packages.
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib](https://github.com/QubesOS-contrib/) packages.
In dom0, use `qubes-dom0-update`:
@ -57,5 +57,3 @@ sudo qubes-dom0-update --clean qvm-screenshot-tool
Please see the package's README for specific installation and setup instructions.
[package contributions]: /doc/package-contributions/
[QubesOS-contrib]: https://github.com/QubesOS-contrib/

3
user/advanced-configuration/managing-vm-kernel.md
View File

@ -11,7 +11,7 @@ title: Managing VM kernel
# VM kernel managed by dom0
By default, VMs kernels are provided by dom0.
(See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
(See [here](/doc/software-update-dom0/#kernel-upgrade) for information about upgrading kernels in dom0.)
This means that:
1. You can select the kernel version (using GUI VM Settings tool or `qvm-prefs` commandline tool);
@ -363,4 +363,3 @@ update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation.
[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade

3
user/advanced-configuration/resize-disk-image.md
View File

@ -106,6 +106,5 @@ qvm-shutdown qube1
sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
```
If you have a SSD see [here][fstrim] for information on using fstrim.
If you have a SSD see [here](/doc/disk-trim) for information on using fstrim.
[fstrim]: /doc/disk-trim

5
user/advanced-configuration/rpc-policy.md
View File

@ -10,7 +10,7 @@ RPC Policies
============
This document explains the basics of RPC policies in Qubes.
For more information, see [Qrexec: command execution in VMs][qrexec3].
For more information, see [Qrexec: command execution in VMs](/doc/qrexec3/).
Here's an example of an RPC policy file in dom0:
@ -54,9 +54,8 @@ Therefore, parsing will always stop at this rule, and no rules below it will eve
All together, the three rules we added say that all VMs tagged with "work" are allowed to copy files to each other; however, they're denied from copying files to other VMs (without the "work" tag), and other VMs (without the "work" tag) are denied from copying files to them.
The fourth rule means that the user gets prompted for any situation not already covered.
Further details about how this system works can be found in [Qrexec: command execution in VMs][qrexec3].
Further details about how this system works can be found in [Qrexec: command execution in VMs](/doc/qrexec3/).
(***Note**: the `$` character is deprecated in qrexec keywords -- please use `@` instead (e.g. `@anyvm`).
For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)
[qrexec3]: /doc/qrexec3/

53
user/advanced-configuration/salt.md
View File

@ -22,7 +22,7 @@ In the current form the **API is provisional** and subject to change between
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site][salt-doc], though we
For more exhaustive documentation, visit [official site](https://docs.saltstack.com/en/latest/), though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
@ -86,17 +86,17 @@ It executes a command on behalf of the administrator.
`name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
The module used defines which parameters can be passed to it.
There is a list of [officially available states][salt-doc-states].
There is a list of [officially available states](https://docs.saltstack.com/en/latest/ref/states/all/).
There are many very useful states:
- For [managing files][salt-doc-states-file]: Use this to create files or
- For [managing files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html): Use this to create files or
directories and change them (append lines, replace text, set their content etc.)
- For [installing and uninstalling][salt-doc-states-pkg] packages.
- For [executing shell commands][salt-doc-states-cmd].
- For [installing and uninstalling](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html) packages.
- For [executing shell commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html).
With these three states you can define most of the configuration of a VM.
You can also [order the execution][salt-doc-states-order] of your states:
You can also [order the execution](https://docs.saltstack.com/en/latest/ref/states/ordering.html) of your states:
```
D:
@ -121,7 +121,7 @@ A:
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
[require](https://docs.saltstack.com/en/latest/ref/states/requisites.html) and [order](https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option) arguments.
#### State Files
@ -133,7 +133,7 @@ configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
This is done by `*.top` files ([official documentation][salt-doc-top]).
This is done by `*.top` files ([official documentation](https://docs.saltstack.com/en/latest/ref/states/top.html)).
Their structure looks like this:
```
@ -195,15 +195,15 @@ $ qubesctl --all state.highstate
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja][jinja].
This is most commonly done with [Jinja](http://jinja.pocoo.org/).
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation][jinja-tmp].
So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation][jinja-call-salt-functions].
[Salt documentation](https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt).
## Salt Configuration, QubesOS layout
@ -259,7 +259,7 @@ This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the DVM
Template that should be used for management, such as Salt
@ -599,26 +599,11 @@ install template and shutdown updateVM:
## Further Reading
- [Salt documentation][salt-doc]
- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
[packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
- [Top files][salt-doc-top]
- [Jinja templates][jinja]
- [Qubes specific modules][salt-qvm-doc]
- [Formulas for default Qubes VMs][salt-virtual-machines-states]
- [Salt documentation](https://docs.saltstack.com/en/latest/)
- [Salt states](https://docs.saltstack.com/en/latest/ref/states/all/) ([files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html),
[packages](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltstack.com/en/latest/ref/states/ordering.html))
- [Top files](https://docs.saltstack.com/en/latest/ref/states/top.html)
- [Jinja templates](http://jinja.pocoo.org/)
- [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
- [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst
[salt-virtual-machines-states]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm
[salt-doc-states]: https://docs.saltstack.com/en/latest/ref/states/all/
[salt-doc-states-file]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-pkg]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html
[salt-doc-states-cmd]: https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html
[salt-doc-states-order]: https://docs.saltstack.com/en/latest/ref/states/ordering.html
[salt-doc-states-req]: https://docs.saltstack.com/en/latest/ref/states/requisites.html
[salt-doc-states-ord]: https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option
[salt-doc-top]:https://docs.saltstack.com/en/latest/ref/states/top.html
[jinja]: http://jinja.pocoo.org/
[jinja-tmp]: http://jinja.pocoo.org/docs/2.9/templates/
[jinja-call-salt-functions]: https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt
[QSB #45]: /news/2018/12/03/qsb-45/

2
user/advanced-configuration/secondary-storage.md
View File

@ -114,5 +114,3 @@ By default VMs will be created on the main Qubes disk (i.e. a small SSD), to cre
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```
[Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/

44
user/advanced-configuration/usb-qubes.md
View File

@ -14,20 +14,20 @@ title: USB Qubes
# USB Qubes #
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube].) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login]!
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login](#enable-a-usb-keyboard-for-login)!
## Creating and Using a USB qube ##
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue][2270-comm23].
If you find yourself in this situation, see this [issue](https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312).
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications] of using USB devices.
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications](/doc/device-handling-security/#usb-security) of using USB devices.
With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci][PCI Devices] command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci](/doc/pci-devices/) command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices](/doc/usb-devices/#finding-the-right-usb-controller).
You can create a USB qube using the management stack by performing the following steps as root in dom0:
```
@ -36,7 +36,7 @@ sudo qubesctl state.sls qvm.sys-usb
Alternatively, you can create a USB qube manually as follows:
1. Read the [PCI Devices] page to learn how to list and identify your USB controllers.
1. Read the [PCI Devices](/doc/pci-devices/) page to learn how to list and identify your USB controllers.
Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
If you find a free controller, note its name and proceed to step 2.
@ -54,19 +54,19 @@ Alternatively, you can create a USB qube manually as follows:
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
(This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
If the USB qube will not start, please have a look at the [faq].
If the USB qube will not start, please have a look at the [faq](/faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot).
## Enable a USB keyboard for login ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding!
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding!
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices).
### Automatic setup ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0:
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates](/doc/software-update-dom0/#how-to-update-dom0)) and execute in dom0:
```
sudo qubesctl state.sls qvm.usb-keyboard
@ -76,7 +76,7 @@ The above command will take care of all required configuration, including creati
Note that it will expose dom0 to USB devices while entering LUKS passphrase.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
To undo these changes, please follow the section on [**Removing a USB qube**][remove your USB-qube]!
To undo these changes, please follow the section on [**Removing a USB qube**](#removing-a-usb-qube)!
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
@ -107,12 +107,12 @@ sys-usb dom0 ask,default_target=dom0
*Don't do that if you want to unlock your device with a USB keyboard!*
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0].
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0](#how-to-hide-all-usb-controllers-from-dom0).
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
## Auto Enabling A USB Mouse ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding.
Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone.
@ -141,7 +141,7 @@ sys-usb dom0 allow
## How to hide all USB controllers from dom0 ##
(Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
This also occurs automatically if you choose to [create a USB qube] using the `qubesctl` method, which is the
This also occurs automatically if you choose to [create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
@ -155,7 +155,7 @@ There are two approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM] device, do not use the second option.
**Warning:** If you use a USB [AEM](/doc/anti-evil-maid/) device, do not use the second option.
Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
If dom0 cannot read your USB AEM device, AEM will hang.
@ -203,15 +203,3 @@ The procedure to hide all USB controllers from dom0 is as follows:
6. Save and close the file.
7. Reboot.
[remove your USB-qube]: #removing-a-usb-qube
[security implications]: /doc/device-handling-security/#usb-security
[enable your keyboard for login]: #enable-a-usb-keyboard-for-login
[2270-comm23]: https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312
[PCI Devices]: /doc/pci-devices/
[usb-controller]: /doc/usb-devices/#finding-the-right-usb-controller
[faq]: /faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot
[Security Warning about USB Input Devices]: /doc/device-handling-security/#security-warning-on-usb-input-devices
[install dom0 updates]: /doc/software-update-dom0/#how-to-update-dom0
[hiding USB controllers from dom0]: #how-to-hide-all-usb-controllers-from-dom0
[AEM]: /doc/anti-evil-maid/
[create a USB qube]: #creating-and-using-a-usb-qube

15
user/common-tasks/backup-emergency-restore-v4.md
View File

@ -23,14 +23,14 @@ any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
In Qubes 4.X, backups are encrypted and integrity-protected with [scrypt]. You
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] first!) Note that versions of
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`.
@ -39,7 +39,7 @@ 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.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key].
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.
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
@ -129,8 +129,8 @@ Emergency Recovery Instructions
with or is in a different format. In the latter case, look inside
`backup-header` at the `version` field. If it contains a value other than
`version=4`, go to the instructions for that format version:
- [Emergency Backup Recovery without Qubes (v2)]
- [Emergency Backup Recovery without Qubes (v3)]
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
4. Read `backup-header`:
@ -180,8 +180,3 @@ Emergency Recovery Instructions
https://github.com/QubesOS/qubes-doc.git
[scrypt]: https://www.tarsnap.com/scrypt.html
[verify signatures]: /security/verifying-signatures
[get and verify the Release 4 Signing Key]: /security/verifying-signatures/#2-get-the-release-signing-key
[Emergency Backup Recovery without Qubes (v2)]: /doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/

29
user/common-tasks/block-devices.md
View File

@ -13,21 +13,21 @@ title: Block (Storage) Devices
# Block (Storage) Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data".
## Using The GUI to Attach a Drive
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device][mass-storage].
(**Note:** In the present context, the term "USB drive" denotes any [USB mass storage device](https://en.wikipedia.org/wiki/USB_mass_storage_device_class).
In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
Attaching USB drives is integrated into the Devices Widget: ![device manager icon]
Attaching USB drives is integrated into the Devices Widget: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
Simply insert your USB drive and click on the widget.
You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB].
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device](/doc/usb-devices/).
Entries without a number (e.g. here `sda`) are the whole block-device.
Other entries are partitions of that block-device (e.r. here `sda1`).
@ -58,7 +58,7 @@ Beware that when you attach a whole block device, partitions can be identified b
If several different block-devices are attached to a single VM, the last letter of the device node name is advanced through the alphabet, so after `xvdi` the next device will be named `xvdj`, the next `xvdk`, and so on.
To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option][frontend-dev].
To specify this device node name, you need to use the command line tool and its [`frontend-dev`-option](#frontend-dev).
## Command Line Tool Guide
@ -123,7 +123,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger
## Recovering From Premature Device Destruction
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems][premature removal].
If the you fail to detach the device before it's destroyed in the sourceVM (e.g. by physically detaching the thumbdrive), [there will be problems](https://github.com/QubesOS/qubes-issues/issues/1082).
To recover from this error state, in dom0 run
@ -131,13 +131,13 @@ To recover from this error state, in dom0 run
virsh detach-disk targetVM xvdi
```
(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node][frontend-dev].)
(where `targetVM` is to be replaced with the VM name you attached the device to and `xvdi` is to be replaced with the used [frontend device node](#frontend-dev).)
However, if the block device originated in dom0, you will have to refer to the next section.
### What if I removed the device before detaching it from the VM?
Currently (until issue [1082] gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
Currently (until issue [1082](https://github.com/QubesOS/qubes-issues/issues/1082) gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
If this isn't an option, you can manually recover from the situation by following these steps:
@ -174,11 +174,11 @@ To attach a file as block device to another qube, first turn it into a loopback
sudo losetup -f --show /path/to/file
```
[This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available.
[This command](https://linux.die.net/man/8/losetup) will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available.
Afterwards it prints the device-node-name it found.
2. If you want to use the GUI, you're done.
Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube.
Click the Device Manager ![device manager icon](/attachment/wiki/Devices/media-removable.png) and select the `loop0`-device to attach it to another qube.
If you rather use the command line, continue:
@ -256,12 +256,3 @@ qvm-block a work sys-usb:sda1 -o devtype=cdrom
This option accepts `cdrom` and `disk`, default is `disk`.
[device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:/attachment/wiki/Devices/media-removable.png
[frontend-dev]: #frontend-dev
[premature removal]: https://github.com/QubesOS/qubes-issues/issues/1082
[detach dom0 device]: /doc/usb/#what-if-i-removed-the-device-before-detaching-it-from-the-vm
[losetup]: https://linux.die.net/man/8/losetup
[USB]:/doc/usb-devices/
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082

17
user/common-tasks/device-handling.md
View File

@ -14,10 +14,10 @@ title: Device Handling
# Device Handling
This is an overview of device handling in Qubes OS.
For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages.
For specific devices ([block](/doc/block-devices/), [USB](/doc/usb-devices/) and [PCI](/doc/pci-devices/) devices), please visit their respective pages.
**Important security warning:** Device handling comes with many security implications.
Please make sure you carefully read and understand the **[security considerations]**.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/)**.
## Introduction ##
@ -38,7 +38,7 @@ PCI devices can be attached using the Qube Settings, but require a VM reboot.
## General Qubes Device Widget Behavior And Handling ##
When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip.
When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive](/attachment/wiki/Devices/media-removable.png) several device-classes separated by lines are displayed as tooltip.
Block devices are displayed on top, microphones one below and USB-devices at the bottom.
On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
@ -57,7 +57,7 @@ Click on one and your device will be attached!
To detach a device, click the Qubes Devices Widget icon again.
Attached devices are displayed in bold.
Hover the one you want to detach.
A list of VMs appears, one showing the eject symbol: ![eject icon]
A list of VMs appears, one showing the eject symbol: ![eject icon](/attachment/wiki/Devices/media-eject.png)
### Attaching a Device to Several VMs ###
@ -65,7 +65,7 @@ A list of VMs appears, one showing the eject symbol: ![eject icon]
Only `mic` should be attached to more than one running VM.
You may *assign* a device to more than one VM (using the `--persistent` option), however, only one of them can be started at the same time.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs.
But be careful: There is a [bug in `qvm-device block` or `qvm-block`](https://github.com/QubesOS/qubes-issues/issues/4692) which will allow you to *attach* a block device to two running VMs.
Don't do that!
@ -158,10 +158,3 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
**SYNOPSIS**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/block-devices/
[USB]:/doc/usb-devices/
[PCI]:/doc/pci-devices/
[security considerations]: /doc/device-handling-security/
[device manager icon]: /attachment/wiki/Devices/media-removable.png
[eject icon]: /attachment/wiki/Devices/media-eject.png
[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692

6
user/common-tasks/disposablevm.md
View File

@ -28,7 +28,7 @@ This diagram provides a general example of how DisposableVMs can be used to safe
## Security
If a [DisposableVM Template] becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
If a [DisposableVM Template](/doc/glossary/#disposablevm-template) becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM.
@ -180,7 +180,7 @@ This line means:
In other words, any VM will be allowed to create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` and open a URL inside of that DisposableVM.
More information about RPC policies for DisposableVMs can be found [here][qrexec].
More information about RPC policies for DisposableVMs can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing DisposableVMs
@ -188,5 +188,3 @@ You can change the template used to generate the DisposableVMs, and change setti
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[qrexec]: /doc/qrexec/#qubes-rpc-administration

61
user/common-tasks/getting-started.md
View File

@ -11,16 +11,16 @@ ref: 190
title: Get Started
---
After [downloading] and [installing] Qubes OS, let's cover some basic concepts.
After [downloading](/downloads/) and [installing](/doc/installation-guide/) Qubes OS, let's cover some basic concepts.
Introduction
------------
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)] called [qubes].
In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)](/doc/glossary/#vm) called [qubes](/doc/glossary/#qube).
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a [security domain] (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template], although you can create more templates if you wish.
Instead, each qube represents a [security domain](/doc/glossary/#domain) (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template](/doc/glossary/#templatevm), although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
@ -49,14 +49,14 @@ It's entirely up to you.
![snapshot_40.png](/attachment/wiki/GettingStarted/r4.0-snapshot_40.png)
In addition to qubes and templates, there's one special domain called [dom0], where many system tools and the desktop manager run.
In addition to qubes and templates, there's one special domain called [dom0](/doc/glossary/#dom0), where many system tools and the desktop manager run.
This is where you log in to the system.
Dom0 is more trusted than any other domain (including templates and black-labeled qubes).
If dom0 were ever compromised, it would be "game over."
(The entire system would effectively be compromised.)
Due to its overarching importance, dom0 has no network connectivity and is used only for running the window and desktop managers.
Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0][dom0-precautions].
In particular, [you should never run user applications in dom0](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).
(That's what your qubes are for!)
GUI and command-line tools
@ -69,7 +69,7 @@ Opening a terminal in dom0 can be done in several ways:
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools].
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
@ -133,54 +133,31 @@ If you plan on using your system for work, then it also depends on what kind of
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
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][copy-files] any files you need to the newly created qube.
You'll also be able to easily [copy](/doc/copying-files/) any files you need to the newly created qube.
Still not sure?
You might find it helpful to read [this article][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains.
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 partitions her digital life into security domains.
Important tasks
---------------
It's very important to [keep Qubes updated][update] to ensure you have the latest security updates.
It's very important to [keep Qubes updated](/doc/updating-qubes-os/) 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] allows you to do this securely and easily.
The [Qubes backup system](/doc/backup-restore/) allows you to do this securely and easily.
Here are some other tasks you're likely to want to perform.
(A full list is available in the [Common Tasks] section of the documentation.)
(A full list is available in the [Common Tasks](/doc/#common-tasks) section of the documentation.)
- [Copying and Pasting Text Between Domains][copy-paste]
- [Copying and Moving Files Between Domains][copy-files]
- [Copying from (and to) dom0]
- [Fullscreen Mode]
- [DisposableVMs]
- [Device Handling] (block, USB, and PCI devices)
- [Copying and Pasting Text Between Domains](/doc/copy-paste/)
- [Copying and Moving Files Between Domains](/doc/copying-files/)
- [Copying from (and to) dom0](/doc/copy-from-dom0/)
- [Fullscreen Mode](/doc/full-screen-mode/)
- [DisposableVMs](/doc/disposablevm/)
- [Device Handling](/doc/device-handling/) (block, USB, and PCI devices)
If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.
[getting-started-32]: /getting-started-32/
[downloading]: /downloads/
[installing]: /doc/installation-guide/
[virtual machines (VMs)]: /doc/glossary/#vm
[qubes]: /doc/glossary/#qube
[security domain]: /doc/glossary/#domain
[template]: /doc/glossary/#templatevm
[dom0]: /doc/glossary/#dom0
[dom0-precautions]: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions
[tools]: /doc/tools/
[partitioning]: https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[copy-files]: /doc/copying-files/
[copy-paste]: /doc/copy-paste/
[Copying from (and to) dom0]: /doc/copy-from-dom0/
[Fullscreen Mode]: /doc/full-screen-mode/
[DisposableVMs]: /doc/disposablevm/
[Device Handling]: /doc/device-handling/
[Help, Support, and Mailing Lists]: /support/
If you encounter any problems, please visit the [Help, Support, and Mailing Lists](/support/) page.
<hr class="more-top more-bottom">

24
user/common-tasks/pci-devices.md
View File

@ -13,17 +13,17 @@ title: PCI Devices
# PCI Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
**Warning:** Only dom0 exposes PCI devices.
Some of them are strictly required in dom0 (e.g., the host bridge).
You may end up with an unusable system by attaching the wrong PCI device to a VM.
PCI passthrough should be safe by default, but non-default options may be required.
Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#pci-security)** before deviating from default behavior.
## Introduction
Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup.
Unlike other devices ([USB](/doc/usb-devices/), [block](/doc/block-devices/), mic), PCI devices need to be attached on VM-bootup.
Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported.
The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install.
@ -31,7 +31,7 @@ While this covers most use cases, there are some occasions when you may want to
Some devices expose multiple functions with distinct BDF-numbers.
Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM.
This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations].
This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations](/doc/device-handling-security/#pci-security).
In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
@ -45,7 +45,7 @@ There you can attach PCI-devices to a qube.
1. To reach the settings of any qube either
- Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu]\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
- Press Alt+F3 to open the application finder, type in the VM name, select the "![appmenu](/attachment/wiki/Devices/qubes-appmenu-select.png)\[VM-name\]: Qube Settings" menu entry and press enter or click "Launch"!
- Select the VM in Qube Manager and click the settings-button or right-click the VM and select `Qube settings`.
- Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
@ -59,7 +59,7 @@ There you can attach PCI-devices to a qube.
## `qvm-pci` Usage
The `qvm-pci` tool allows PCI attachment and detachment.
It's a shortcut for [`qvm-device pci`][qvm-device].
It's a shortcut for [`qvm-device pci`](/doc/device-handling/#general-qubes-device-widget-behavior-and-handling).
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
@ -93,7 +93,7 @@ Attaching a PCI device through the commandline offers additional options, specif
(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
`qvm-pci` exposes two additional options.
Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!**
Both are intended to fix device or driver specific issues, but both come with [heavy security implications](/doc/device-handling-security/#pci-security)! **Make sure you understand them before continuing!**
### no-strict-reset
@ -109,7 +109,7 @@ qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
### permissive
Allow write access to full PCI config space instead of whitelisted registers.
This increases attack surface and possibility of [side channel attacks].
This increases attack surface and possibility of [side channel attacks](https://en.wikipedia.org/wiki/Side-channel_attack).
usage example:
@ -143,11 +143,3 @@ or
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
[device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-handling-security/#pci-security
[block]:/doc/block-devices/
[USB]:/doc/usb-devices/
[appmenu]: /attachment/wiki/Devices/qubes-appmenu-select.png
[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
[qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack

23
user/common-tasks/software-update-dom0.md
View File

@ -12,10 +12,10 @@ title: Installing and updating software in dom0
# Installing and updating software in dom0
Updating [dom0] is one of the main steps in [Updating Qubes OS].
It is very important to keep dom0 up-to-date with the latest [security] updates.
Updating [dom0](/doc/glossary/#dom0) is one of the main steps in [Updating Qubes OS](/doc/updating-qubes-os/).
It is very important to keep dom0 up-to-date with the latest [security](/security/) updates.
We also publish dom0 updates for various non-security bug fixes and enhancements to Qubes components.
In addition, you may wish to update the kernel, drivers, or libraries in dom0 when [troubleshooting newer hardware].
In addition, you may wish to update the kernel, drivers, or libraries in dom0 when [troubleshooting newer hardware](/doc/newer-hardware-troubleshooting/).
## Security
@ -109,7 +109,7 @@ sudo dnf remove anti-evil-maid
## Testing repositories
There are three Qubes dom0 [testing] repositories:
There are three Qubes dom0 [testing](/doc/testing/) repositories:
- `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository
@ -132,7 +132,7 @@ To enable or disable any of these repos permanently, change the corresponding `e
## Contributed package repository
Please see [installing contributed packages].
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## Kernel upgrade
@ -144,8 +144,8 @@ The packages `kernel` and `kernel-latest` are for dom0.
In the `current` repository:
- `kernel`: an older LTS kernel that has passed Qubes [testing] (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware])
- `kernel`: an older LTS kernel that has passed Qubes [testing](/doc/testing/) (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing](/doc/testing/) (useful for [troubleshooting newer hardware](/doc/newer-hardware-troubleshooting/))
In the `current-testing` repository:
@ -155,7 +155,7 @@ In the `current-testing` repository:
### domU
The packages `kernel-qubes-vm` and `kernel-latest-qubes-vm` are for domUs.
See [Managing VM kernel] for more information.
See [Managing VM kernel](/doc/managing-vm-kernel/) for more information.
### Example
@ -236,10 +236,3 @@ For example: sys-whonix.
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
`
[dom0]: /doc/glossary/#dom0
[Updating Qubes OS]: /doc/updating-qubes-os/
[security]: /security/
[testing]: /doc/testing/
[troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
[Managing VM kernel]: /doc/managing-vm-kernel/
[installing contributed packages]: /doc/installing-contributed-packages/

34
user/common-tasks/software-update-domu.md
View File

@ -13,8 +13,8 @@ title: Installing and updating software in domUs
# Installing and updating software in domUs
Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are important steps in [Updating Qubes OS].
It is very import to keep domUs up-to-date with the latest [security] updates.
Updating [domUs](/doc/glossary/#domu), especially [TemplateVMs](/doc/templates/) and [StandaloneVMs](/doc/standalone-and-hvm/) are important steps in [Updating Qubes OS](/doc/updating-qubes-os/).
It is very import to keep domUs up-to-date with the latest [security](/security/) updates.
Updating these VMs also allows you to receive various non-security bug fixes and enhancements both from the Qubes OS Project and from your upstream distro maintainer.
## Installing software in TemplateVMs
@ -25,10 +25,10 @@ To permanently install new software in a TemplateVM:
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
5. Restart all [TemplateBasedVMs](/doc/glossary/#templatebasedvm) based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs](/doc/glossary/#templatebasedvm)' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
These new shortcuts will appear in the Applications Menu.
(If you encounter problems, see [here][shortcuts] for troubleshooting.)
(If you encounter problems, see [here](/doc/managing-appvm-shortcuts/) for troubleshooting.)
![[The Applications tab in Qube Settings](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)
@ -45,7 +45,7 @@ Advanced users can execute the standard update command for that operating system
## Testing repositories
If you wish to install updates that are still in [testing], you must enable the appropriate testing repositories.
If you wish to install updates that are still in [testing](/doc/testing), you must enable the appropriate testing repositories.
### Fedora
@ -78,11 +78,11 @@ To enable or disable any of these repos permanently, uncomment the corresponding
## Contributed package repository
Please see [installing contributed packages].
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## StandaloneVMs
When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
When you create a [StandaloneVM](/doc/standalone-and-hvm/) from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
After the moment of creation, the StandaloneVM is completely independent from the TemplateVM.
Therefore, it will not be updated when the TemplateVM is updated.
Rather, it must be updated individually.
@ -94,7 +94,7 @@ The following sections cover advanced topics pertaining to installing and updati
### RPMFusion for Fedora TemplateVMs
If you would like to enable the [RPM Fusion] repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion] for details):
If you would like to enable the [RPM Fusion](https://rpmfusion.org/) repositories, open a Terminal of the TemplateVM and type the following commands, depending on which RPM Fusion repositories you wish to enable (see [RPM Fusion](https://rpmfusion.org/) for details):
~~~
sudo dnf config-manager --set-enabled rpmfusion-free
@ -143,7 +143,7 @@ Just make sure to **back up** all of your data and changes first!
#### Reinstall the template
Please see [How to Reinstall a TemplateVM].
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
#### Full revert
@ -176,7 +176,7 @@ Thanks to such configuration all the VMs can use the same proxy address, and if
If the VM is configured to have access to the updates proxy (2), the startup scripts will automatically configure dnf to really use the proxy (3).
Also access to updates proxy is independent of any other firewall settings (VM will have access to updates proxy, even if policy is set to block all the traffic).
There are two services (`qvm-service`, [service framework]):
There are two services (`qvm-service`, [service framework](/doc/qubes-service/)):
1. `qubes-updates-proxy` (and its deprecated name: `qubes-yum-proxy`) - a service providing a proxy for templates - by default enabled in NetVMs (especially: sys-net)
2. `updates-proxy-setup` (and its deprecated name: `yum-proxy-setup`) - use a proxy provided by another VM (instead of downloading updates directly), enabled by default in all templates
@ -304,15 +304,3 @@ yelp.desktop
Note that the app will autostart only when the AppVM starts. If you would like the AppVM to autostart, select the "Start qube automatically on boot" checkbox in the AppVM's Qube Settings.
[domUs]: /doc/glossary/#domu
[TemplateVMs]: /doc/templates/
[StandaloneVM]: /doc/standalone-and-hvm/
[Updating Qubes OS]: /doc/updating-qubes-os/
[security]: /security/
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[testing]: /doc/testing
[RPM Fusion]: https://rpmfusion.org/
[service framework]: /doc/qubes-service/
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[installing contributed packages]: /doc/installing-contributed-packages/
[shortcuts]: /doc/managing-appvm-shortcuts/

38
user/common-tasks/updating-qubes-os.md
View File

@ -9,16 +9,16 @@ title: Updating Qubes OS
Updating Qubes OS
=================
*This page is about updating your system while staying on the same [supported version of Qubes OS].
If you're instead looking to upgrade from your current version of Qubes OS to a newer version, see the [Upgrade Guides].*
*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/).*
It is very important to keep your Qubes OS system up-to-date to ensure you have the latest [security] updates, as well as the latest non-security enhancements and bug fixes.
It is very important to keep your Qubes OS system up-to-date to ensure you have the latest [security](/security/) updates, as well as the latest non-security enhancements and bug fixes.
Fully updating your Qubes OS system means updating:
- [Dom0]
- [TemplateVMs]
- [StandaloneVMs] (if you have any)
- [Dom0](/doc/software-update-dom0/)
- [TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms)
- [StandaloneVMs](/doc/software-update-domu/#standalonevms) (if you have any)
You can accomplish this using the **Qubes Update** tool.
@ -35,24 +35,10 @@ As an alterntaive to the Qubes Update tool, advanced users can update each of th
Visit the pages linked above for details about updating each type.
The final step is to make sure that all of your VMs are running a supported operating system so that they're all receiving upstream security updates.
For example, you might be using a [Fedora TemplateVM].
The [Fedora Project] is independent of the Qubes OS Project.
They set their own [schedule] for when each Fedora release reaches [end-of-life] (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] and publish guides for official TemplateVM 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] and the [Debian upgrade guides]).
The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
For example, you might be using a [Fedora TemplateVM](/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 [end-of-life](https://fedoraproject.org/wiki/End_of_life) (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 TemplateVM 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 is dom0, which [doesn't have to be upgraded](/doc/supported-versions/#note-on-dom0-and-eol).
[supported version of Qubes OS]: /doc/supported-versions/#qubes-os
[Upgrade Guides]: /doc/upgrade/
[security]: /security/
[Dom0]: /doc/software-update-dom0/
[TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[StandaloneVMs]: /doc/software-update-domu/#standalonevms
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora Project]: https://getfedora.org/
[schedule]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[end-of-life]: https://fedoraproject.org/wiki/End_of_life
[announcements]: /news/categories/#announcements
[Fedora upgrade guides]: /doc/templates/fedora/#upgrading
[Debian upgrade guides]: /doc/templates/debian/#upgrading
[dom0-eol]: /doc/supported-versions/#note-on-dom0-and-eol

52
user/common-tasks/usb-devices.md
View File

@ -10,32 +10,32 @@ title: USB Devices
# USB Devices
*This page is part of [device handling in qubes].*
*This page is part of [device handling in qubes](/doc/device-handling/).*
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device] page.
If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/block-devices/) page.
**Note:** Attaching USB devices to VMs requires a [USB qube][USB-qube howto].
**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/).
**Important security warning:** USB passthrough comes with many security implications.
Please make sure you carefully read and understand the **[security considerations]**.
Whenever possible, attach a [block device] instead.
Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**.
Whenever possible, attach a [block device](/doc/block-devices/) instead.
Examples of valid cases for USB-passthrough:
- [microcontroller programming]
- [external audio devices]
- [optical drives] for recording
- [microcontroller programming](https://www.arduino.cc/en/Main/Howto)
- [external audio devices](/doc/external-audio/)
- [optical drives](/doc/recording-optical-discs/) for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy].
But it has some [issues][4661].)
(If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/).
But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).)
## Attaching And Detaching a USB Device
### With Qubes Device Manager
Click the device-manager-icon: ![device manager icon]
Click the device-manager-icon: ![device manager icon](/attachment/wiki/Devices/media-removable.png)
A list of available devices appears.
USB-devices have a USB-icon to their right: ![usb icon]
USB-devices have a USB-icon to their right: ![usb icon](/attachment/wiki/Devices/generic-usb.png)
Hover on one device to display a list of VMs you may attach it to.
@ -46,7 +46,7 @@ You're done.
After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget.
You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**.
Hover on the attached device to display a list of running VMs.
The one to which your device is connected will have an eject button ![eject icon] next to it.
The one to which your device is connected will have an eject button ![eject icon](/attachment/wiki/Devices/media-eject.png) next to it.
Click that and your device will be detached.
### With The Command Line Tool
@ -75,7 +75,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
Now, you can use your USB device (camera in this case) in the `work` qube.
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section].
If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy).
When you finish, detach the device.
@ -93,7 +93,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
### Creating And Using a USB qube
If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`.
If you've later decided to create a usb-qube, please follow [this guide][USB-qube howto].
If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/).
### Installation Of `qubes-usb-proxy`
@ -108,9 +108,9 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
### Using USB Keyboards And Other Input Devices
**Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations]** before continuing!
**Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing!
Mouse and keyboard setup are part of [setting up a USB-qube][keyboard setup].
Mouse and keyboard setup are part of [setting up a USB-qube](/doc/usb-qubes/#enable-a-usb-keyboard-for-login).
### Finding The Right USB Controller
@ -150,25 +150,9 @@ This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool][qvm-pci] to attach the controller to the targetVM.
Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/pci-devices/) to attach the controller to the targetVM.
For example, On R 4.0 the command would look something like
`qvm-pci attach --persistent personal dom0:00_1a.0`
[device handling in qubes]: /doc/device-handling/
[block device]: /doc/block-devices/
[security considerations]: /doc/device-handling-security/#usb-security
[usb-challenges]: https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html
[usb icon]: /attachment/wiki/Devices/generic-usb.png
[microcontroller programming]: https://www.arduino.cc/en/Main/Howto
[external audio devices]: /doc/external-audio/
[optical drives]: /doc/recording-optical-discs/
[qubes u2f proxy]: /doc/u2f-proxy/
[4661]: https://github.com/QubesOS/qubes-issues/issues/4661
[device manager icon]:/attachment/wiki/Devices/media-removable.png
[eject icon]:/attachment/wiki/Devices/media-eject.png
[Installation Section]:#installation-of-qubes-usb-proxy
[USB-qube howto]: /doc/usb-qubes/
[keyboard setup]: /doc/usb-qubes/#enable-a-usb-keyboard-for-login
[qvm-pci]: /doc/pci-devices/

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

@ -97,7 +97,7 @@ Default compiled-in device cipher parameters:
This means that, by default, Qubes inherits these upstream defaults:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- AES-128 [[1]](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions)[[2]](https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption)[[3]](https://github.com/dyne/Tomb/issues/238)
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
@ -162,6 +162,3 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con
The default file systems are ext4 for `/boot` and `/`, and swap for `swap`.
When you are finished, the Unknown list should go away, and all three mount points should be assigned. Proceed normally with the installation from there.
[cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238

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

@ -12,7 +12,7 @@ Qubes Download Mirrors
List of Download Mirrors
------------------------
The full list of known Qubes download mirrors is available [here][mirror-list].
The full list of known Qubes download mirrors is available [here](/downloads/#mirrors).
Instructions for Mirror Operators
---------------------------------
@ -24,10 +24,6 @@ helpful in streamlining the process.
* We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew].
* For technical accommodations, please contact [Wojtek](/team/#wojtek-porczyk) or [Marek](/team/#marek-marczykowski-górecki).
* For website updates and fixes, please contact [Andrew](/team/#andrew-david-wong).
[mirror-list]: /downloads/#mirrors
[Wojtek]: /team/#wojtek-porczyk
[Marek]: /team/#marek-marczykowski-górecki
[Andrew]: /team/#andrew-david-wong

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

@ -19,18 +19,18 @@ There are several security matters to consider before and during the Qubes insta
No operating system, not even Qubes, can help you if you're installing it on hardware that is already compromised.
This includes CPUs, GPUs, SSDs, HDDs, the motherboard, BIOS/EFI/UEFI, and all relevant firmware.
Unfortunately, in today's world of undetectable supply chain attacks, there are no easy solutions.
(Tools like [Anti Evil Maid (AEM)][AEM] can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot], [Heads], and [Skulls].
(Tools like [Anti Evil Maid (AEM)](/doc/anti-evil-maid/) can help with *maintaining* the trustworthiness of your hardware, but not with establishing it in the first place.)
Some users have chosen to use tools like [Coreboot](https://www.coreboot.org/), [Heads](http://osresearch.net/), and [Skulls](https://github.com/merge/skulls).
## Verifying the Qubes ISO
You should [verify] the PGP signature on your Qubes ISO before you install from it.
You should [verify](/security/verifying-signatures/) the PGP signature on your Qubes ISO before you install from it.
However, if the machine on which you attempt the verification process is already compromised, it could falsely claim that a malicious ISO has a good signature.
Therefore, in order to be certain that your Qubes ISO is trustworthy, you require a trustworthy machine.
But how can you be certain *that* machine is trustworthy?
Only by using another trusted machine, and so forth.
This is a [classic problem].
While various [solutions] have been proposed, the point is that each user must ultimately make a choice about whether to trust that a file is non-malicious.
This is a [classic problem](https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf).
While various [solutions](https://www.dwheeler.com/trusting-trust/) have been proposed, the point is that each user must ultimately make a choice about whether to trust that a file is non-malicious.
## Choosing an installation medium
@ -43,7 +43,7 @@ From a Qubes-specific security perspective, each has certain pros and cons.
Pros:
* Works via USB, including with a [USB qube].
* Works via USB, including with a [USB qube](/doc/usb-qubes/#creating-and-using-a-usb-qube).
* Non-fixed capacity.
(Easy to find one on which the ISO can fit.)
@ -53,7 +53,7 @@ Cons:
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware.
(Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://srlabs.de/badusb/).
Installing from a compromised drive could compromise even a brand new Qubes installation.)
### Optical discs
@ -79,12 +79,3 @@ Cons:
Considering the pros and cons of each, perhaps a USB drive with non-rewritable (or at least cryptographically-signed) firmware and a physical write-protect switch might be the best option.
[AEM]: /doc/anti-evil-maid/
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf
[solutions]: https://www.dwheeler.com/trusting-trust/
[USB qube]: /doc/usb-qubes/#creating-and-using-a-usb-qube
[BadUSB]: https://srlabs.de/badusb/
[Coreboot]: https://www.coreboot.org/
[Heads]: http://osresearch.net/
[Skulls]: https://github.com/merge/skulls

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

@ -37,16 +37,16 @@ Please read it carefully and thoroughly, as it contains important information fo
See <a href="/doc/install-security/">installation security</a> for more information.
</div>
Qubes OS has very specific [system requirements].
To ensure compatibility, we strongly recommend using [Qubes-certified hardware].
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].
You may also find it helpful to consult the [Hardware Compatibility List](/hcl/).
Even on supported hardware, you must ensure that [IOMMU-based virtualization] is activated in the BIOS.
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][intel-guide] made for Intel-based boards can help you figure out how to enter your BIOS to locate and activate those settings.
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">
@ -58,7 +58,7 @@ If those settings are not nested under the Advanced tab, you might find them und
### 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>
@ -68,7 +68,7 @@ Start by [downloading][downloads] a Qubes ISO.
</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] page by hovering over the download button.
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>
@ -90,7 +90,7 @@ $ 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`).
On Windows, you can use the [Rufus] tool to write the ISO to a USB key.
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):
@ -103,7 +103,7 @@ Be sure to select "DD image" mode (*after* selecting the Qubes ISO):
![Rufus DD image mode](/attachment/wiki/InstallationGuide/rufus-dd-image-mode.png)
If you are an advanced user, and you would like to customize your installation, please see [custom installation].
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
@ -139,7 +139,7 @@ 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].
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.
@ -160,7 +160,7 @@ If the test fails, a window will pop up.
Do not panic.
It may simply indicate that IOMMU-virtualization hasn't been activated in the BIOS.
Return to the [hardware requirements] section to learn how to activate it.
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.
@ -211,18 +211,18 @@ Don't forget to select your time and date by clicking on the Time & Date entry.
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] qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix] qubes.
Whonix allows you to use [Tor] 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.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs] later.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs](/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 configuration]).
Other desktop environments will be available to you after the installation is completed, though they may not be officially supported (see [advanced configuration](/doc/#advanced-configuration)).
Press **Done** to go back to the installation summary screen.
@ -352,7 +352,7 @@ Congratulations, you are now ready to use Qubes OS!
### Updating
Next, [update] your installation to ensure you have the latest security updates.
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.
### Security
@ -372,56 +372,26 @@ For more information about Qubes OS Project security, please see the [security c
### Backups
It is extremely important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
The [Qubes backup system](/doc/backup-restore/) 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][hcl-howto].
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] with Qubes, and read more about [Common Tasks] and [Managing Operating Systems within Qubes].
[Get Started](/getting-started/) with Qubes, and read more about [Common Tasks](/doc/#common-tasks) and [Managing Operating Systems within Qubes](/doc/#managing-operating-systems-within-qubes).
## Getting help
* We work very hard to make the [documentation] accurate, comprehensive useful and user friendly.
* 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] it!)
(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 you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] 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] for appropriate places to ask questions.
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions.
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[Qubes-certified hardware]: /doc/certified-hardware/
[Hardware Compatibility List]: /hcl/
[live USB]: /doc/live-usb/
[downloads]: /downloads/
[verifying signatures]: /security/verifying-signatures/
[security considerations]: /doc/install-security/
[Custom Installation]: /doc/custom-install/
[Upgrade Guides]: /doc/upgrade/
[Rufus]: https://rufus.akeo.ie/
[documentation]: /doc/
[improving]: /doc/doc-guidelines/
[Help, Support, Mailing Lists, and Forum]: /support/
[update]: /doc/updating-qubes-os/
[Qubes backup system]: /doc/backup-restore/
[Common Tasks]: /doc/#common-tasks
[Managing Operating Systems within Qubes]: /doc/#managing-operating-systems-within-qubes
[installation security]: /doc/install-security/
[IOMMU-based virtualization]: https://en.wikipedia.org/wiki/Input%E2%80%93output_memory_management_unit#Virtualization
[intel-guide]: https://web.archive.org/web/20200112220913/https://www.intel.in/content/www/in/en/support/articles/000007139/server-products.html
[advanced reboot]: https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings
[hardware requirements]: #hardware-requirements
[Debian]: /doc/templates/debian/
[Whonix]: /doc/whonix/
[Tor]: https://www.torproject.org/
[TemplateVMs]: /doc/templates/
[advanced configuration]: /doc/#advanced-configuration
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
[Get Started]: /getting-started/

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

@ -13,9 +13,9 @@ This page details the level and period of support for versions of operating syst
## Qubes OS
Qubes OS releases are supported for **six months** after each subsequent major
or minor release (see [Version Scheme]). The current release and past major
releases are always available on the [Downloads] page, while all ISOs, including
past minor releases, are available from our [download 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 |
| ----------- | ---------- | ---------- | --------------------- |
@ -25,7 +25,7 @@ past minor releases, are available from our [download mirrors].
| Release 3.1 | 2016-03-09 | 2017-03-29 | Unsupported |
| Release 3.2 | 2016-09-29 | 2019-03-28 | Unsupported |
| Release 4.0 | 2018-03-28 | TBA | Supported |
| Release 4.1 | TBA | TBA | [In development][4.1] |
| Release 4.1 | TBA | TBA | [In development](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.1%22+) |
### Note on point releases
@ -51,18 +51,18 @@ 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], and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
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).
## TemplateVMs
The following table shows select [TemplateVM] versions that are currently supported.
Currently, only [Fedora] and [Debian] TemplateVMs are officially supported by the Qubes OS Project.
[Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
The following table shows select [TemplateVM](/doc/templates/) versions that are currently supported.
Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) TemplateVMs are officially supported by the Qubes OS Project.
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
Qubes support for each TemplateVM ends when that upstream release reaches end-of-life (EOL), unless otherwise noted.
In the case of Debian, support ends at regular EOL, not [LTS][Debian-LTS] EOL, unless otherwise noted.
In the case of Debian, support ends at regular EOL, not [LTS](https://wiki.debian.org/LTS) EOL, unless otherwise noted.
See [below](#note-on-whonix-support) for Whonix support details.
For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debian-eol].
For upstream EOL information, see [Fedora EOL](https://fedoraproject.org/wiki/End_of_life) and [Debian EOL](https://wiki.debian.org/DebianReleases).
| Qubes OS | Fedora | Debian | Whonix |
| ----------- | ------ | ---------------------------- | ------ |
@ -73,7 +73,7 @@ For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debi
### Note on Whonix support
[Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
The Whonix Project has set its own support policy for Whonix TemplateVMs in Qubes.
This policy requires Whonix TemplateVM users to stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix TemplateVMs within a month of their respective releases.
@ -87,17 +87,3 @@ To be precise:
We aim to announce both types of events one month in advance in order to remind users to upgrade.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors
[security-critical]: /doc/security-critical-code/
[TemplateVM]: /doc/templates/
[extended support]: /news/2018/03/28/qubes-40/#the-past-and-the-future
[4.1]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A%22Release+4.1%22+
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[fedora-eol]: https://fedoraproject.org/wiki/End_of_life
[debian-eol]: https://wiki.debian.org/DebianReleases
[Whonix]: /doc/whonix/
[Whonix Project]: https://www.whonix.org/
[Debian-LTS]: https://wiki.debian.org/LTS

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

@ -9,7 +9,7 @@ title: Testing New Releases and Updates
Testing New Releases and Updates
================================
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute] to the Qubes OS Project.
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute](/doc/contributing/) to the Qubes OS Project.
However, you should only attempt to do this if you know what you're doing.
Never rely on code that is in testing for critical work!
@ -18,26 +18,26 @@ Releases
How to test upcoming Qubes OS releases:
* Use [qubes-builder] to build the latest release.
* Use [qubes-builder](/doc/qubes-builder/) to build the latest release.
* Test the latest release candidate (RC), if any is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
See [Version Scheme] for details about release versions and schedules.
See [Release Checklist] for details about the RC process.
See [Version Scheme](/doc/version-scheme/) for details about release versions and schedules.
See [Release Checklist](/doc/releases/todo/) for details about the RC process.
Updates
-------
How to test updates:
* Enable [dom0 testing repositories].
* Enable [TemplateVM testing repositories].
* Enable [dom0 testing repositories](/doc/software-update-dom0/#testing-repositories).
* Enable [TemplateVM testing repositories](/doc/software-update-domu/#testing-repositories).
Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update.
The update remains in `security-testing` or `current-testing` for a minimum of one week.
On occasion, an exception is made for a particularly critical security update, which is immediately pushed to the `current` stable repository.
In general, however, security updates remain in `security-testing` for two weeks before migrating to `current`.
Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can weeks or even months, depending on the amount of feedback received (see [Providing Feedback]).
Normal updates generally remain in `current-testing` until they have been sufficiently tested by the community, which can weeks or even months, depending on the amount of feedback received (see [Providing Feedback](#providing-feedback)).
"Sufficient testing" is, in practice, a fluid term that is up the developers' judgment. In general, it means either that no negative feedback and at least one piece of positive feedback has been received or that the package has been in `current-testing` for long enough, depending on the component and the complexity of the changes.
A limitation of the current testing setup is that it is only possible to migrate the *most recent version* of a package from `current-testing` to `current`.
@ -49,19 +49,9 @@ Providing Feedback
If you're testing new releases or updates, we would be grateful for your feedback.
We use an [automated build process].
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status] repository for tracking purposes.
We use an [automated build process](https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md).
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status](https://github.com/QubesOS/updates-status/issues) repository for tracking purposes.
We welcome any kind of feedback on any package in any testing repository.
Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository.
If you [report a bug] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
If you [report a bug](/doc/reporting-bugs/) in a package that is in a testing repository, please reference the appropriate issue in [updates-status](https://github.com/QubesOS/updates-status/issues).
[contribute]: /doc/contributing/
[qubes-builder]: /doc/qubes-builder/
[Version Scheme]: /doc/version-scheme/
[Release Checklist]: /doc/releases/todo/
[dom0 testing repositories]: /doc/software-update-dom0/#testing-repositories
[TemplateVM testing repositories]: /doc/software-update-domu/#testing-repositories
[automated build process]: https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md
[updates-status]: https://github.com/QubesOS/updates-status/issues
[report a bug]: /doc/reporting-bugs/
[Providing Feedback]: #providing-feedback

5
user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md
View File

@ -44,7 +44,7 @@ Backup R3.2
7. If your backup verifies successfully, proceed to the next section.
If it does not, **stop**.
Go back and repeat the backup steps, review the documentation, and ask for [help].
Go back and repeat the backup steps, review the documentation, and ask for [help](/support/).
Install R4.0
------------
@ -61,7 +61,7 @@ For further details, please see the [installation guide](/doc/installation-guide
If you did not successfully verify your backup in the previous section, cancel the installation, and go back to do that now.
3. Complete the R4.0 installation.
Ask for [help] if you run into trouble.
Ask for [help](/support/) if you run into trouble.
4. If you are unable to successfully install R4.0 on your system, all is not lost.
Use the R3.2 installer to reinstall R3.2, then restore from your backup.
@ -119,4 +119,3 @@ Please see [Supported Versions](/doc/supported-versions/) for information on sup
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)
[help]: /support/

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

@ -10,7 +10,7 @@ Qubes OS Upgrade Guides
=======================
These guides are for upgrading from one version of Qubes to another.
If you're just looking to update your system while staying on the same version, see [Updating Qubes OS].
If you're just looking to update your system while staying on the same version, see [Updating Qubes OS](/doc/updating-qubes-os/).
* [Upgrading from R1 to R2 Beta 1](/doc/upgrade-to-r2b1/)
* [Upgrading from R1 to R2 Beta 2](/doc/upgrade-to-r2b2/)
@ -21,4 +21,3 @@ If you're just looking to update your system while staying on the same version,
* [Upgrading from R3.1 to R3.2](/doc/upgrade-to-r3.2/)
* [Upgrading from R3.2 to R4.0](/doc/upgrade-to-r4.0/)
[Updating Qubes OS]: /doc/updating-qubes-os/

3
user/downloading-installing-upgrading/version-scheme.md
View File

@ -42,7 +42,7 @@ When enough development has been made, we announce the first stable version,
like e.g. `3.0.0` (i.e. without `-rc`). This version is considered stable and
we support it for some period. Core components are branched at this moment and
bugfixes are backported from master branch. Please see [Help, Support, Mailing
Lists, and Forum] for places to ask questions about stable releases. No major
Lists, and Forum](/support/) for places to ask questions about stable releases. No major
features and interface incompatibilities are to be included in this release. We
release bugfixes as `3.0.1`, `3.0.2` and so on, while new features come into the
next release e.g. `3.1-rcX`.
@ -158,4 +158,3 @@ Check installed version
If you want to know which version you are running, for example to report
an issue, you can either check in the Qubes Manager menu under About / Qubes OS or in the file /etc/qubes-release in dom0. For the latter you can use a command like `cat /etc/qubes-release` in a dom0 terminal.
[Help, Support, Mailing Lists, and Forum]: /support/

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

@ -18,25 +18,25 @@ Note, however, that we certify only that a particular hardware *configuration* i
We take no responsibility for our partners' manufacturing or shipping processes, nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user.
There are also other hardware models on which we have tested Qubes OS.
See [Hardware Testing] for details.
See [Hardware Testing](/doc/hardware-testing/) for details.
## Qubes-certified Laptops
Qubes-certified laptops are certified for a [major version][version-scheme] and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major version.
Qubes-certified laptops are certified for a [major version](/doc/version-scheme/) and regularly tested by the Qubes developers to ensure compatibility with all of Qubes' features within that major version.
The developers test all new updates within that major version to ensure that no regressions are introduced.
### Insurgo PrivacyBeast X230
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)][Insurgo PrivacyBeast X230]
[![insurgo-privacybeast-x230.png](/attachment/site/insurgo-privacybeast-x230.png)](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/)
The [Insurgo PrivacyBeast X230] meets and exceeds our hardware certification requirements for Qubes 4.
Read our [announcement][privacybeast announcement] of the certification for further details!
The [Insurgo PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) meets and exceeds our hardware certification requirements for Qubes 4.
Read our [announcement](/news/2019/07/18/insurgo-privacybeast-qubes-certification/) of the certification for further details!
### NitroPad X230
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)][NitroPad X230]
[![nitropad-x230.jpg](/attachment/site/nitropad-x230.jpg)](https://shop.nitrokey.com/shop/product/nitropad-x230-67)
The [NitroPad X230] satisfies all hardware certification requirements for Qubes 4, offering users extensive hardware security options.
The [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) satisfies all hardware certification requirements for Qubes 4, offering users extensive hardware security options.
## Become Hardware Certified
@ -52,18 +52,18 @@ The benefits of hardware certification include:
## Hardware Certification Requirements
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes.
For the latter, please see the [system requirements].)
For the latter, please see the [system requirements](/doc/system-requirements/).)
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT]), also known as [EPT][EPT-enabled CPUs] in Intel parlance.
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)), also known as [EPT](https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile) in Intel parlance.
SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach.
We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148], which --- unlike many other major Xen bugs --- regrettably did [affect][QSB 22] Qubes OS.
We hope that embracing SLAT-based memory virtualization will allow us to prevent disastrous security bugs, such as the infamous [XSA-148](https://xenbits.xen.org/xsa/advisory-148.html), which --- unlike many other major Xen bugs --- regrettably did [affect](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt) Qubes OS.
Consequently, we require SLAT support of all certified hardware beginning with Qubes OS 4.0.
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot].
The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP]) as well as other internal operations (see [Intel ME]).
Another important requirement is that Qubes-certified hardware should run only **open-source boot firmware** (aka "the BIOS"), such as [coreboot](https://www.coreboot.org/).
The only exception is the use of (properly authenticated) CPU-vendor-provided blobs for silicon and memory initialization (see [Intel FSP](https://firmware.intel.com/learn/fsp/about-intel-fsp)) as well as other internal operations (see [Intel ME](https://www.apress.com/9781430265719)).
However, we specifically require all code used for and dealing with the System Management Mode (SMM) to be open-source.
While we [recognize][x86_harmful] the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop].
While we [recognize](https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf) the potential problems that proprietary CPU-vendor code can cause, we are also pragmatic enough to realize that we need to take smaller steps first, before we can implement even stronger countermeasures such as a [stateless laptop](https://blog.invisiblethings.org/papers/2015/state_harmful.pdf).
A switch to open source boot firmware is one such important step.
To be compatible with Qubes OS, the BIOS must properly expose all the VT-x, VT-d, and SLAT functionality that the underlying hardware offers (and which we require).
Among other things, this implies **proper DMAR ACPI table** construction.
@ -76,7 +76,7 @@ The rest of the time, they should be outside the reach of malware.
While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).
Similarly, we don't consider physical kill switches on Wi-Fi and Bluetooth devices to be mandatory.
Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers][audio_modem]!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
Users who plan on using Qubes in an air-gap scenario would do best if they manually remove all such devices persistently (as well as the builtin [speakers](https://github.com/romanz/amodem/)!), rather than rely on easy-to-flip-by-mistake switches, while others should benefit from the Qubes default sandboxing of all networking devices in dedicated VMs.
We hope these hardware requirements will encourage the development of more secure and trustworthy devices.
@ -89,29 +89,8 @@ To have hardware certified, the vendor must:
3. Pay the Qubes team a flat monthly rate, to be agreed upon between the hardware vendor and the Qubes team.
It is the vendor's responsibility to ensure the hardware they wish to have certified can run Qubes OS, at the very least the latest stable version.
This could be done by consulting the [Hardware Compatibility List] or trying to install it themselves before shipping any units to us.
This could be done by consulting the [Hardware Compatibility List](/hcl/) or trying to install it themselves before shipping any units to us.
While we are willing to troubleshoot simple issues, we will need to charge a consulting fee for more in-depth work.
If you are interested in having your hardware certified, please [contact us].
If you are interested in having your hardware certified, please [contact us](mailto:business@qubes-os.org).
[version-scheme]: /doc/version-scheme/
[Hardware Testing]: /doc/hardware-testing/
[stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: #hardware-certification
[system requirements]: /doc/system-requirements/
[contact us]: mailto:business@qubes-os.org
[SLAT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation
[EPT-enabled CPUs]: https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile
[XSA-148]: https://xenbits.xen.org/xsa/advisory-148.html
[QSB 22]: https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-022-2015.txt
[pvh_ticket]: https://github.com/QubesOS/qubes-issues/issues/2185
[coreboot]: https://www.coreboot.org/
[Intel FSP]: https://firmware.intel.com/learn/fsp/about-intel-fsp
[Intel ME]: https://www.apress.com/9781430265719
[x86_harmful]: https://blog.invisiblethings.org/papers/2015/x86_harmful.pdf
[stateless laptop]: https://blog.invisiblethings.org/papers/2015/state_harmful.pdf
[audio_modem]: https://github.com/romanz/amodem/
[Insurgo PrivacyBeast X230]: https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/
[privacybeast announcement]: /news/2019/07/18/insurgo-privacybeast-qubes-certification/
[NitroPad X230]: https://shop.nitrokey.com/shop/product/nitropad-x230-67

8
user/hardware/hardware-testing.md
View File

@ -9,7 +9,7 @@ title: Hardware Testing
# Hardware Testing
The Qubes developers test Qubes OS on certain hardware models.
The tested hardware described on this page differs from [Qubes Certified Hardware] in a few key ways:
The tested hardware described on this page differs from [Qubes Certified Hardware](/doc/certified-hardware/) in a few key ways:
- Qubes Certified Hardware has to meet more demanding standards than hardware that is merely tested.
- All Qubes Certified Hardware is tested, but not all tested hardware is certified.
@ -17,9 +17,9 @@ The tested hardware described on this page differs from [Qubes Certified Hardwar
In general, you can think of tested hardware as "unofficial recommended" hardware:
- [Qubes Certified Hardware] --- Qubes developer certified, officially recommended
- [Qubes Certified Hardware](/doc/certified-hardware/) --- Qubes developer certified, officially recommended
- Hardware Testing (this page) --- Qubes developer tested, unofficially recommended
- [Hardware Compatibility List (HCL)] --- community test results, neither recommended nor disrecommended
- [Hardware Compatibility List (HCL)](/hcl/) --- community test results, neither recommended nor disrecommended
## Tested Models
@ -40,5 +40,3 @@ If anyone is willing to lend or donate these models to us, we would be happy to
Note: The Lenovo X and T series are similar enough to assume similar compatibility of the matching model from the other series.
[Qubes Certified Hardware]: /doc/certified-hardware/
[Hardware Compatibility List (HCL)]: /hcl/

5
user/hardware/hcl.md
View File

@ -31,7 +31,7 @@ If using the list to make a purchasing decision, we recommend that you choose ha
- the best achievable Qubes security level (green columns in HVM, IOMMU, TPM)
- and general machine compatibility (green columns in Qubes version, dom0 kernel, remarks).
Also see [Certified Hardware] and [Hardware Testing].
Also see [Certified Hardware](/doc/certified-hardware/) and [Hardware Testing](/doc/hardware-testing/).
Generating and Submitting New Reports
-------------------------------------
@ -49,6 +49,3 @@ Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To ge
**Please note:**
The **HCL Support Files** may contain numerous hardware details, including serial numbers. If, for privacy or security reasons, you do not wish to make this information public, please **do not** send the `.cpio.gz` file to the public mailing list.
[Certified Hardware]: /doc/certified-hardware/
[Hardware Testing]: /doc/hardware-testing/

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

@ -24,32 +24,32 @@ title: System Requirements
## Minimum
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 4 GB RAM
- **Storage:** 32 GB free space
## Recommended
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- [Intel VT-x](https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29) with [EPT](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables) or [AMD-V](https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29) with [RVI](https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing)
- [Intel VT-d](https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d) or [AMD-Vi (also known as AMD IOMMU)](https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29)
- **Memory:** 16 GB RAM
- **Storage:** 128 GB free space
- High-speed solid-state drive strongly recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant [troubleshooting][nvidia]
- 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])
- **Other:** Satisfaction of all [hardware certification requirements for Qubes 4.x]
- **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] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here][hcl-doc].)
- See the [Certified Hardware] page.
- See the [Hardware Testing] page.
- 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
@ -62,23 +62,8 @@ title: System Requirements
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] for advice on hardware compatibility testing.)
(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 USBVM if you move between different machines.
- [Advice on finding a VT-d capable notebook][vt-d-notebook].
- [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).
[nvidia]: /doc/install-nvidia-driver/
[hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/
[Certified Hardware]: /doc/certified-hardware/
[Hardware Testing]: /doc/hardware-testing/
[Hardware Compatibility List]: /hcl/
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J
[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29
[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29
[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d
[AMD-Vi (also known as AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables
[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing

35
user/managing-os/debian/debian-upgrade.md
View File

@ -14,10 +14,10 @@ title: In-place upgrade of Debian TemplateVMs
# Upgrading Debian TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM].
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM] page instead. ([Learn more about the two options.][Debian TemplateVM Upgrade])
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM](/doc/templates/debian/).
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system][upgrade].
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
## Summary instructions for Debian TemplateVMs
@ -34,7 +34,7 @@ In general, upgrading a Debian TemplateVM follows the same process as [upgrading
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for Debian TemplateVMs
@ -87,8 +87,8 @@ The same general procedure may be used to upgrade any template based on the stan
```
7. (Optional) Trim the new template.
(This should [no longer be necessary][template-notes], but it does not hurt.
Some users have [reported][5055] that it makes a difference.)
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
```
[user@debian-<new> ~]$ sudo fstrim -av
@ -103,7 +103,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
9. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
9. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
10. (Optional) Make the new template the global default.
@ -120,7 +120,7 @@ The same general procedure may be used to upgrade any template based on the stan
## StandaloneVMs
The procedure for upgrading a Debian [StandaloneVM] is the same as for a TemplateVM.
The procedure for upgrading a Debian [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
## Release-specific notes
@ -128,7 +128,7 @@ This section contains notes about upgrading to specific releases.
### Debian 10 ("Buster")
Please see [Debian's Buster upgrade instructions][buster].
Please see [Debian's Buster upgrade instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
### Debian 9 ("Stretch")
@ -148,15 +148,15 @@ Relevant discussions:
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)
Also see [Debian's Stretch upgrade instructions][stretch].
Also see [Debian's Stretch upgrade instructions](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
### Debian 8 ("Jessie")
Please see [Debian's Jessie upgrade instructions][jessie].
Please see [Debian's Jessie upgrade instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
### End-of-life (EOL) releases
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)].
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)](https://wiki.debian.org/DebianReleases#Production_Releases).
## Additional information
@ -166,14 +166,3 @@ We strongly recommend against using any Debian release that has reached [end-of-
* By default, Qubes uses code names in the `apt` sources files, although the templates are referred to by release number.
Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.
[Debian TemplateVM]: /doc/templates/debian/
[Debian TemplateVM Upgrade]: /doc/templates/debian/#upgrading
[upgrade]: https://wiki.debian.org/DebianUpgrade
[switch]: /doc/templates/#switching
[jessie]: https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html
[stretch]: https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html
[buster]: https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html
[end-of-life (EOL)]: https://wiki.debian.org/DebianReleases#Production_Releases
[StandaloneVM]: /doc/standalone-and-hvm/
[template-notes]: /doc/templates/#important-notes
[5055]: https://github.com/QubesOS/qubes-issues/issues/5055

35
user/managing-os/debian/debian.md
View File

@ -13,14 +13,14 @@ title: The Debian TemplateVM
# The Debian TemplateVM
The Debian [TemplateVM] is an officially [supported] TemplateVM in Qubes OS.
The Debian [TemplateVM](/doc/templates/) is an officially [supported](/doc/supported-versions/#templatevms) TemplateVM in Qubes OS.
This page is about the standard (or "full") Debian TemplateVM.
For the minimal version, please see the [Minimal TemplateVMs] page.
There is also a [Qubes page on the Debian Wiki].
For the minimal version, please see the [Minimal TemplateVMs](/doc/templates/minimal/) page.
There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
## Installing
To [install] a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-debian-XX
@ -28,29 +28,29 @@ $ sudo qubes-dom0-update qubes-template-debian-XX
(Replace `XX` with the Debian version number of the template you wish to install.)
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## After Installing
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
## Updating
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs].
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Debian release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
- [Perform an in-place upgrade of an existing Debian template.][Upgrading Debian TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
- [Perform an in-place upgrade of an existing Debian template.](/doc/template/debian/upgrade/) This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
## Release-specific notes
@ -108,16 +108,3 @@ The lesson is that you should carefully look at what is being installed to your
If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors)
[TemplateVM]: /doc/templates/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Qubes page on the Debian Wiki]: https://wiki.debian.org/Qubes
[end-of-life]: https://wiki.debian.org/DebianReleases#Production_Releases
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[Upgrading Debian TemplateVMs]: /doc/template/debian/upgrade/
[5149]: https://github.com/QubesOS/qubes-issues/issues/5149
[install]: /doc/templates/#installing

40
user/managing-os/fedora/fedora-upgrade.md
View File

@ -25,8 +25,8 @@ title: In-place upgrade of Fedora TemplateVMs
# Upgrading Fedora TemplateVMs
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM].
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM] page instead. ([Learn more about the two options.][Fedora TemplateVM Upgrade])
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM](/doc/templates/fedora/).
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM](/doc/templates/fedora/) page instead. ([Learn more about the two options.](/doc/templates/fedora/#upgrading))
## Summary instructions for standard Fedora TemplateVMs
@ -47,7 +47,7 @@ If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
```
**Recommended:** [Switch everything that was set to the old template to the new template.][switch]
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for standard Fedora TemplateVMs
@ -120,8 +120,8 @@ The same general procedure may be used to upgrade any template based on the stan
At least X MB more space needed on the / filesystem.
`
In this case, one option is to [resize the TemplateVM's disk image][resize-disk-image] before reattempting the upgrade process.
(See [Additional Information] below for other options.)
In this case, one option is to [resize the TemplateVM's disk image](/doc/resize-disk-image/) before reattempting the upgrade process.
(See [Additional Information](#additional-information) below for other options.)
4. Check that you are on the correct (new) Fedora release.
@ -130,8 +130,8 @@ The same general procedure may be used to upgrade any template based on the stan
```
5. (Optional) Trim the new template.
(This should [no longer be necessary][template-notes], but it does not hurt.
Some users have [reported][5055] that it makes a difference.)
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
```
[user@fedora-<new> ~]$ sudo fstrim -av
@ -153,7 +153,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
```
8. (Recommended) [Switch everything that was set to the old template to the new template.][switch]
8. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
9. (Optional) Make the new template the global default.
@ -186,18 +186,18 @@ The same general procedure may be used to upgrade any template based on the stan
## StandaloneVMs
The procedure for upgrading a Fedora [StandaloneVM] is the same as for a TemplateVM.
The procedure for upgrading a Fedora [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
## Release-specific notes
See the [news] announcement for each specific TemplateVM release for any important notices about that particular release.
See the [news](/news/) announcement for each specific TemplateVM release for any important notices about that particular release.
### End-of-life (EOL) releases
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)].
Also see [supported versions].
We strongly recommend against using any Fedora release that has reached [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life).
Also see [supported versions](/doc/supported-versions/).
## Additional information
@ -210,24 +210,12 @@ At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size][resize-disk-image].
1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/).
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by uninstalling packages.
You may then reinstall them again after you finish the upgrade process, if desired).
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs].
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading).
[Fedora TemplateVM]: /doc/templates/fedora/
[Fedora TemplateVM Upgrade]: /doc/templates/fedora/#upgrading
[resize-disk-image]: /doc/resize-disk-image/
[Additional Information]: #additional-information
[switch]: /doc/templates/#switching
[DispVM]: /doc/dispvm/
[end-of-life (EOL)]: https://fedoraproject.org/wiki/End_of_life
[StandaloneVM]: /doc/standalone-and-hvm/
[template-notes]: /doc/templates/#important-notes
[5055]: https://github.com/QubesOS/qubes-issues/issues/5055
[supported versions]: /doc/supported-versions/
[news]: /news/

30
user/managing-os/fedora/fedora.md
View File

@ -8,11 +8,11 @@ title: The Fedora TemplateVM
# The Fedora TemplateVM
The Fedora [TemplateVM] is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs] and [Xfce TemplateVMs] pages.
The Fedora [TemplateVM](/doc/templates/) is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs](/doc/templates/minimal/) and [Xfce TemplateVMs](/doc/templates/xfce/) pages.
## Installing
To [install] a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-fedora-XX
@ -20,39 +20,27 @@ $ sudo qubes-dom0-update qubes-template-fedora-XX
(Replace `XX` with the Fedora version number of the template you wish to install.)
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## After Installing
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
## Updating
For routine daily updates within a given release, see [Updating software in TemplateVMs].
For routine daily updates within a given release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Fedora release:
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template][switch]. You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
- [Install a fresh template to replace the existing one.](#installing) This option may be simpler for less experienced users. After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.
- [Perform an in-place upgrade of an existing Fedora template.][Upgrading Fedora TemplateVMs] This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
- [Perform an in-place upgrade of an existing Fedora template.](/doc/template/fedora/upgrade/) This option will preserve any modifications you've made to the template, but it may be more complicated for less experienced users.
[TemplateVM]: /doc/templates/
[Minimal TemplateVMs]: /doc/templates/minimal/
[Xfce TemplateVMs]: /doc/templates/xfce/
[end-of-life]: https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule
[supported]: /doc/supported-versions/#templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[Update the TemplateVM]: /doc/software-update-vm/
[switch]: /doc/templates/#switching
[uninstall the old TemplateVM]: /doc/templates/#uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[Upgrading Fedora TemplateVMs]: /doc/template/fedora/upgrade/
[install]: /doc/templates/#installing

27
user/managing-os/minimal-templates.md
View File

@ -15,10 +15,10 @@ title: Minimal TemplateVMs
# Minimal TemplateVMs
The Minimal [TemplateVMs] are lightweight versions of their standard TemplateVM counterparts.
The Minimal [TemplateVMs](/doc/templates/) are lightweight versions of their standard TemplateVM counterparts.
They have only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora], [Debian], [CentOS] and [Gentoo] TemplateVMs.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/) and [Gentoo](/doc/templates/gentoo/) TemplateVMs.
## Important
@ -27,11 +27,11 @@ There are currently three Minimal TemplateVMs corresponding to the standard [Fed
2. If something works with a standard TemplateVM but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, please do *not* file a bug report.
Instead, please see [Help, Support, Mailing Lists, and Forum] for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation][doc-guidelines].
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation](/doc/doc-guidelines/).
3. The Minimal TemplateVMs are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
[Do not ask for your favorite package to be added to the minimal template by default.](/faq/#could-you-please-make-my-preference-the-default)
4. In order to reduce unnecessary risk, unused repositories have been disabled by default.
If you wish to install or update any packages from those repositories, you must enable them.
@ -44,7 +44,7 @@ The Minimal TemplateVMs can be installed with the following command (where `X` i
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-minimal
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -61,7 +61,7 @@ The download may take a while depending on your connection speed.
## Passwordless root
It is an intentional design choice for [Passwordless Root Access in VMs] to be optional in Minimal TemplateVMs.
It is an intentional design choice for [Passwordless Root Access in VMs](/doc/vm-sudo/) to be optional in Minimal TemplateVMs.
Since the Minimal TemplateVMs are *minimal*, they are not configured for passwordless root by default.
To update or install packages, execute the following command in dom0 (where `X` is your distro and version number):
@ -131,7 +131,7 @@ Also, there are packages to provide additional services:
You may also wish to consider additional packages from the `qubes-core-agent` suite:
See [here][customization] for further information on customizing `fedora-minimal`.
See [here](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md) for further information on customizing `fedora-minimal`.
#### Logging
@ -221,14 +221,3 @@ Documentation on all of these can be found in the [docs](/doc)
You could, of course, use `qubes-vm-recommended` to automatically install many of these, but in that case you are well on the way to a standard Debian template.
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[Gentoo]: /doc/templates/gentoo/
[Help, Support, Mailing Lists, and Forum]: /support/
[doc-guidelines]: /doc/doc-guidelines/
[pref-default]: /faq/#could-you-please-make-my-preference-the-default
[testing]: /doc/testing/
[customization]: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md
[Passwordless Root Access in VMs]: /doc/vm-sudo/

3
user/managing-os/reinstall-template.md
View File

@ -11,7 +11,7 @@ title: How to Reinstall a TemplateVM
How to Reinstall a TemplateVM
=============================
If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
If you suspect your [TemplateVM](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
Automatic Method
----------------
@ -92,4 +92,3 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the
command `qvm-remove <vm-name>` in dom0.
[TemplateVM]: /doc/templates/

96
user/managing-os/templates.md
View File

@ -13,9 +13,9 @@ title: TemplateVMs
# TemplateVMs
In [Getting Started], we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software.
Your software is installed in [TemplateVMs] (or "templates" for short).
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs].
In [Getting Started](/getting-started/), we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software.
Your software is installed in [TemplateVMs](/doc/glossary/#templatevm) (or "templates" for short).
Each TemplateVM shares its root filesystem (i.e., all of its programs and system files) with other qubes called [TemplateBasedVMs](/doc/glossary/#templatebasedvm).
TemplateBasedVMs are where you run your software and store your data.
The TemplateVM system has significant benefits:
@ -25,7 +25,7 @@ The TemplateVM system has significant benefits:
* **Speed:** It is extremely fast to create new TemplateBasedVMs, since the root filesystem already exists in the TemplateVM.
* **Updates:** Updates are naturally centralized, since updating a TemplateVM means that all qubes based on it will automatically use those updates after they're restarted.
An important side effect of this system is that any software installed in a TemplateBasedVM (rather than in the TemplateVM on which it is based) will disappear after the TemplateBasedVM reboots (see [Inheritance and Persistence]).
An important side effect of this system is that any software installed in a TemplateBasedVM (rather than in the TemplateVM on which it is based) will disappear after the TemplateBasedVM reboots (see [Inheritance and Persistence](#inheritance-and-persistence)).
For this reason, we recommend installing most of your software in TemplateVMs, not TemplateBasedVMs.
The default TemplateVM in Qubes is based on Fedora, but there are additional templates based on other Linux distributions.
@ -42,11 +42,11 @@ These are the official Qubes OS Project templates.
We build and release updates for these templates.
We guarantee that the binary updates are compiled from exactly the same source code as we publish.
* [Fedora] (default)
* [Fedora Minimal]
* [Fedora Xfce]
* [Debian]
* [Debian Minimal]
* [Fedora](/doc/templates/fedora/) (default)
* [Fedora Minimal](/doc/templates/minimal/)
* [Fedora Xfce](/doc/templates/xfce)
* [Debian](/doc/templates/debian/)
* [Debian Minimal](/doc/templates/minimal/)
## Community
@ -58,21 +58,21 @@ However, such updates may be provided by the template maintainer.
By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer.
In addition, these templates may be somewhat less stable, since the Qubes developers do not test them.
* [Whonix]
* [Ubuntu]
* [Arch Linux]
* [CentOS]
* [CentOS Minimal]
* [Gentoo]
* [Gentoo Minimal]
* [Whonix](/doc/templates/whonix/)
* [Ubuntu](/doc/templates/ubuntu/)
* [Arch Linux](/doc/building-archlinux-template/)
* [CentOS](/doc/templates/centos/)
* [CentOS Minimal](/doc/templates/minimal/)
* [Gentoo](/doc/templates/gentoo/)
* [Gentoo Minimal](/doc/templates/minimal/)
## Installing
Certain TemplateVMs come preinstalled with Qubes OS.
However, there may be times when you wish to install a fresh TemplateVM from the Qubes repositories, e.g.:
* When a TemplateVM version you're using reaches [end-of-life][supported].
* When a new version of a TemplateVM that you wish to use becomes [supported].
* When a TemplateVM version you're using reaches [end-of-life](/doc/supported-versions/).
* When a new version of a TemplateVM that you wish to use becomes [supported](/doc/supported-versions/).
* When you suspect your TemplateVM has been compromised.
* When you have made modifications to your TemplateVM that you no longer want.
@ -91,22 +91,22 @@ If you wish to install a community template, you must enable the community templ
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<name>
```
If you receive the message that no match is found for `qubes-template-<name>`, see [here][no-match].
If you receive the message that no match is found for `qubes-template-<name>`, see [here](/faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found).
## After Installing
After installing a fresh TemplateVM, we recommend performing the following steps:
1. [Update the TemplateVM].
1. [Update the TemplateVM](#updating).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one][switch].
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](#switching).
3. If desired, [uninstall the old TemplateVM].
3. If desired, [uninstall the old TemplateVM](#uninstalling).
## Updating
Updating TemplateVMs is an important part of [Updating Qubes OS].
Please see [Updating software in TemplateVMs].
Updating TemplateVMs is an important part of [Updating Qubes OS](/doc/updating-qubes-os/).
Please see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
## Uninstalling
@ -137,7 +137,7 @@ warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file
These are normal and expected. Nothing is wrong, and no action is required to address these warnings.
If this uninstallation command doesn't work, please see [How to Remove VMs Manually].
If this uninstallation command doesn't work, please see [How to Remove VMs Manually](/doc/remove-vm-manually/).
If the Applications Menu entry doesn't go away after you uninstall a TemplateVM, execute the following type of command in dom0:
@ -153,7 +153,7 @@ $ rm /usr/local/share/applications/<template_vm_name>
## Reinstalling
Please see [How to Reinstall a TemplateVM].
Please see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
## Switching
@ -179,7 +179,7 @@ When you install a new template or upgrade a clone of a template, it is recommen
Applications Menu --> System Tools --> Qubes Template Manager
`
4. Base the [DisposableVM Template] on the new template.
4. Base the [DisposableVM Template](/doc/glossary/#disposablevm-template) on the new template.
```
[user@dom0 ~]$ qvm-create -l red -t <new_template> <new_template_dvm>
@ -208,7 +208,7 @@ No changes in any other directories in TemplateBasedVMs persist in this manner.
(1) Upon creation
(2) Following shutdown
(3) Including any [DisposableVM Templates]
(3) Including any [DisposableVM Templates](/doc/glossary/#disposablevm-template)
### Trusting your TemplateVMs
@ -274,45 +274,13 @@ Note the word "clean" means in this context: the same as their template filesyst
* `qvm-trim-template` is no longer necessary or available in Qubes 4.0 and higher.
All VMs are created in a thin pool and trimming is handled automatically.
No user action is required.
See [Disk Trim] for more information.
See [Disk Trim](/doc/disk-trim) for more information.
* RPM-installed templates are "system managed" and therefore cannot be backed up using Qubes' built-in backup function.
In order to ensure the preservation of your custom settings and the availability of a "known-good" backup template, you may wish to clone the default system template and use your clone as the default template for your AppVMs.
* Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder].
* Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the [Qubes Builder](/doc/qubes-builder/).
In particular, some template "flavors" are available in source code form only.
For the technical details of the template system, please see [TemplateVM Implementation].
Take a look at the [Qubes Builder] documentation for instructions on how to compile them.
For the technical details of the template system, please see [TemplateVM Implementation](/doc/template-implementation/).
Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for instructions on how to compile them.
[Getting Started]: /getting-started/
[TemplateVMs]: /doc/glossary/#templatevm
[TemplateBasedVMs]: /doc/glossary/#templatebasedvm
[Fedora]: /doc/templates/fedora/
[Fedora Minimal]: /doc/templates/minimal/
[Fedora Xfce]: /doc/templates/xfce
[Debian]: /doc/templates/debian/
[Debian Minimal]: /doc/templates/minimal/
[Whonix]: /doc/templates/whonix/
[Ubuntu]: /doc/templates/ubuntu/
[Arch Linux]: /doc/building-archlinux-template/
[CentOS]: /doc/templates/centos/
[CentOS Minimal]: /doc/templates/minimal/
[CentOS Xfce]: /doc/templates/xfce
[Gentoo]: /doc/templates/gentoo/
[Gentoo Minimal]: /doc/templates/minimal/
[Gentoo Xfce]: /doc/templates/xfce
[Qubes Builder]: /doc/qubes-builder/
[TemplateVM Implementation]: /doc/template-implementation/
[How to Remove VMs Manually]: /doc/remove-vm-manually/
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[DisposableVM Templates]: /doc/glossary/#disposablevm-template
[Updating Qubes OS]: /doc/updating-qubes-os/
[Disk Trim]: /doc/disk-trim
[Inheritance and Persistence]: #inheritance-and-persistence
[supported]: /doc/supported-versions/
[Update the TemplateVM]: #updating
[switch]: #switching
[uninstall the old TemplateVM]: #uninstalling
[Updating software in TemplateVMs]: /doc/software-update-domu/#updating-software-in-templatevms
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[no-match]: /faq/#when-i-try-to-install-a-templatevm-it-says-no-match-is-found

15
user/managing-os/xfce-templates.md
View File

@ -14,7 +14,7 @@ title: Xfce TemplateVMs
# Xfce TemplateVMs
If you would like to use Xfce (more lightweight compared to GNOME desktop environment) Linux distribution in your qubes,
you can install one of the available Xfce templates for [Fedora], [CentOS] or [Gentoo].
you can install one of the available Xfce templates for [Fedora](/doc/templates/fedora/), [CentOS](/doc/templates/centos/) or [Gentoo](/doc/templates/gentoo/).
## Installation
@ -24,7 +24,7 @@ The Fedora Xfce TemplateVMs can be installed with the following command (where `
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -37,7 +37,7 @@ If you would like to install a community distribution, like CentOS or Gentoo, tr
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
```
If your desired version is not found, it may still be in [testing].
If your desired version is not found, it may still be in [testing](/doc/testing/).
You may wish to try again with the testing repository enabled:
```
@ -46,12 +46,5 @@ You may wish to try again with the testing repository enabled:
The download may take a while depending on your connection speed.
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM].
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
[How to Reinstall a TemplateVM]: /doc/reinstall-template/
[TemplateVMs]: /doc/templates/
[Fedora]: /doc/templates/fedora/
[Debian]: /doc/templates/debian/
[CentOS]: /doc/templates/centos/
[Gentoo]: /doc/templates/gentoo/
[testing]: /doc/testing/

7
user/reference/glossary.md
View File

@ -107,7 +107,7 @@ NetVM
-----
*This is an old definition from before Qubes 4.0.
NetVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
NetVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Network Virtual Machine.
A type of [VM](#vm) that connects directly to a network.
@ -121,7 +121,7 @@ ProxyVM
-------
*This is an old definition from before Qubes 4.0.
ProxyVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
ProxyVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Proxy Virtual Machine.
A type of [VM](#vm) that proxies network access for other VMs.
@ -131,7 +131,7 @@ FirewallVM
----------
*This is an old definition from before Qubes 4.0.
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here](https://github.com/QubesOS/qubes-doc/pull/748) for technical details).*
Firewall Virtual Machine.
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
@ -228,4 +228,3 @@ QWT
An abbreviation of Qubes [Windows Tools](#windows-tools).
[pr-748]: https://github.com/QubesOS/qubes-doc/pull/748

27
user/security-in-qubes/device-handling-security.md
View File

@ -11,7 +11,7 @@ title: Device Handling Security
Any additional ability a VM gains is additional attack surface.
It's a good idea to always attach the minimum entity required in a VM.
For example, attaching a full USB-device offers [more attack surface than attaching a single block device][USB security], while
For example, attaching a full USB-device offers [more attack surface than attaching a single block device](https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"), while
attaching a full block device (e.g. `sda`) again offers more attack surface than attaching a single partition (e.g. `sda1`), since the targetVM doesn't have to parse the partition-table.
(Attaching a full block device offers the advantage that most file-managers will mount and display them correctly, whereas they don't expect single partitions to be added and therefore don't handle them correctly.)
@ -41,25 +41,25 @@ Only whitelisted registers are accessible.
However, some devices or applications require full PCI access.
In these cases, the whole config-space may be allowed.
You're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit.
This increases the VM's ability to run a [side channel attack] and vulnerability to the same.
See [Xen PCI Passthrough: PV guests and PCI quirks] and [Software Attacks on Intel VT-d] \(page 7) for more details.
This increases the VM's ability to run a [side channel attack](https://en.wikipedia.org/wiki/Side-channel_attack) and vulnerability to the same.
See [Xen PCI Passthrough: PV guests and PCI quirks](https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks) and [Software Attacks on Intel VT-d](https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) \(page 7) for more details.
## USB Security
The connection of an untrusted USB device to dom0 is a security risk since the device can attack an arbitrary USB driver (which are included in the linux kernel), exploit bugs during partition-table-parsing or simply pretend to be a keyboard.
There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky][rubber duck].
There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky](https://shop.hak5.org/products/usb-rubber-ducky-deluxe).
The whole USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, use a [USB qube].
To avoid this risk, use a [USB qube](/doc/usb-qubes/).
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues][USB security] associated with the USB-stack.
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues](https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security") associated with the USB-stack.
If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
## Security Warning On USB Input Devices
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a [USB qube] entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
Because of this, the benefits of using a [USB qube](/doc/usb-qubes/) entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
@ -71,16 +71,7 @@ This is because you are guarding the system not only against anyone with local a
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
One way to achieve this is to use a [YubiKey](/doc/YubiKey/), or some other hardware token, or even to manually enter a one-time password.
Support for [two factor authentication][qubes u2f proxy] was recently added, though there are [issues][4661].
Support for [two factor authentication](/news/2018/09/11/qubes-u2f-proxy/) was recently added, though there are [issues](https://github.com/QubesOS/qubes-issues/issues/4661).
[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"
[rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe
[USB qube]: /doc/usb-qubes/
[YubiKey]: /doc/YubiKey/
[qubes u2f proxy]: /news/2018/09/11/qubes-u2f-proxy/
[4661]: https://github.com/QubesOS/qubes-issues/issues/4661
[side channel attack]: https://en.wikipedia.org/wiki/Side-channel_attack
[Xen PCI Passthrough: PV guests and PCI quirks]: https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks
[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf

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

@ -97,7 +97,7 @@ Please note that previously, this parameter was set in ~/.bash_profile.
This will no longer work.
If you have the parameter set in ~/.bash_profile you *must* update your configuration.
Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations][current-limitations] section.
Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
### Configuring the client apps to use Split GPG backend
@ -199,7 +199,7 @@ Once this is done, you should be able to send an encrypted and signed email by s
[![tb78-10.png](/attachment/wiki/SplitGpg/tb78-10.png)](/attachment/wiki/SplitGpg/tb78-10.png)
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards] from which the above documentation is inspired.
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards) from which the above documentation is inspired.
### Older Thunderbird versions
@ -284,11 +284,11 @@ A safe, unspoofable user consent dialog box is displayed.
[![r2-split-gpg-5.png](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)](/attachment/wiki/SplitGpg/r2-split-gpg-5.png)
Selecting "Yes to All" will add a line in the corresponding [RPC Policy] file.
Selecting "Yes to All" will add a line in the corresponding [RPC Policy](/doc/rpc-policy/) file.
## Advanced: Using Split GPG with Subkeys
Users with particularly high security requirements may wish to use Split GPG with [​subkeys].
Users with particularly high security requirements may wish to use Split GPG with [subkeys](https://wiki.debian.org/Subkeys).
However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model.
Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
@ -343,14 +343,14 @@ In this example, the following keys are stored in the following locations (see b
This is a network-isolated VM.
The initial master keypair and subkeys are generated in this VM.
The master secret key *never* leaves this VM under *any* circumstances.
No files or text is *ever* [copied] or [pasted] into this VM under *any* circumstances.
No files or text is *ever* [copied](/doc/copying-files#security) or [pasted](/doc/copy-paste#security) into this VM under *any* circumstances.
* `work-gpg`
This is a network-isolated VM.
This VM is used *only* as the GPG backend for `work-email`.
The secret subkeys (but *not* the master secret key) are [copied] from the `vault` VM to this VM.
Files from less trusted VMs are *never* [copied] into this VM under *any* circumstances.
The secret subkeys (but *not* the master secret key) are [copied](/doc/copying-files#security) from the `vault` VM to this VM.
Files from less trusted VMs are *never* [copied](/doc/copying-files#security) into this VM under *any* circumstances.
* `work-email`
@ -361,9 +361,9 @@ In this example, the following keys are stored in the following locations (see b
### Security Benefits
In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised.
First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [​MUA] could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM.
In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels].
In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/data-leaks).
Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there.
@ -371,23 +371,23 @@ Rather, the master secret key remains in the `vault` VM, which is extremely unli
<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
(This is significantly less devastating than having to create a new *master* keypair.)
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM][trusting-templates] upon which the `vault` VM is based.
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/doc/templates/#trusting-your-templatevms) upon which the `vault` VM is based.
### Subkey Tutorials and Discussions
(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments.
As always, exercise caution and use your good judgment.)
* [​"OpenPGP in Qubes OS" on the qubes-users mailing list][openpgp-in-qubes-os]
* [​"Creating the Perfect GPG Keypair" by Alex Cabal][cabal]
* [​"GPG Offline Master Key w/ smartcard" maintained by Abel Luck][luck]
* [​"Using GnuPG with QubesOS" by Alex][apapadop]
* ["OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
* ["Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
* ["GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
* ["Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)
## Current limitations
* Current implementation requires importing of public keys to the vault domain.
This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
See ticket [#474] for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys].
See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
Perhaps the GPG backend domain could start a DisposableVM and have the to-be-signed document displayed there? To Be Determined.
@ -395,26 +395,9 @@ As always, exercise caution and use your good judgment.)
* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
It will give an `Inappropriate ioctl for device` error.
Do not set passphrases for the private keys in the GPG backend domain.
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys].
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
(See [this StackExchange answer][se-pinentry] for more information.)
(See [this StackExchange answer](https://unix.stackexchange.com/a/379373) for more information.)
Note: The error shows only if you **do not** have graphical pinentry installed.
[#474]: https://github.com/QubesOS/qubes-issues/issues/474
[using Split GPG with subkeys]: #advanced-using-split-gpg-with-subkeys
[intro]: #what-is-split-gpg-and-why-should-i-use-it-instead-of-the-standard-gpg
[se-pinentry]: https://unix.stackexchange.com/a/379373
[​subkeys]: https://wiki.debian.org/Subkeys
[copied]: /doc/copying-files#security
[pasted]: /doc/copy-paste#security
[​MUA]: https://en.wikipedia.org/wiki/Mail_user_agent
[covert channels]: /doc/data-leaks
[trusting-templates]: /doc/templates/#trusting-your-templatevms
[openpgp-in-qubes-os]: https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion
[cabal]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[luck]: https://gist.github.com/abeluck/3383449
[apapadop]: https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/
[current-limitations]: #current-limitations
[RPC Policy]: /doc/rpc-policy/
[Thunderbird:OpenPGP:Smartcards]: https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards

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

@ -8,12 +8,12 @@ title: The Qubes U2F Proxy
# The Qubes U2F Proxy
The [Qubes U2F Proxy] is a secure proxy intended to make use of U2F two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies][USB] implemented in Qubes.
The [Qubes U2F Proxy](https://github.com/QubesOS/qubes-app-u2f) is a secure proxy intended to make use of U2F two-factor authentication devices with web browsers without exposing the browser to the full USB stack, not unlike the [USB keyboard and mouse proxies](/doc/usb/) implemented in Qubes.
## What is U2F?
[U2F], which stands for "Universal 2nd Factor", is a framework for authentication using hardware devices (U2F tokens) as "second factors", i.e. *what you have* as opposed to *what you know*, like a passphrase.
This additional control provides [good protection][krebs] in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
[U2F](https://en.wikipedia.org/wiki/U2F), which stands for "Universal 2nd Factor", is a framework for authentication using hardware devices (U2F tokens) as "second factors", i.e. *what you have* as opposed to *what you know*, like a passphrase.
This additional control provides [good protection](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/) in cases in which the passphrase is stolen (e.g. by phishing or keylogging).
While passphrase compromise may not be obvious to the user, a physical device that cannot be duplicated must be stolen to be used outside of the owner's control.
Nonetheless, it is important to note at the outset that U2F cannot guarantee security when the host system is compromised (e.g. a malware-infected operating system under an adversary's control).
@ -25,8 +25,8 @@ The user interface is usually limited to a single LED and a button that is press
Currently, the most common form of two-step authentication consists of a numeric code that the user manually types into a web application.
These codes are typically generated by an app on the user's smartphone or sent via SMS.
By now, it is well-known that this form of two-step authentication is vulnerable to phishing and man-in-the-middle attacks due to the fact that the application requesting the two-step authentication code is typically not itself authenticated by the user.
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the U2F model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here][u2f-details]).
Nonetheless, [some attacks are still possible][wired] even with U2F (more on this below).
(In other words, users can accidentally give their codes to attackers because they do not always know who is really requesting the code.) In the U2F model, by contrast, the browser ensures that the token receives valid information about the web application requesting authentication, so the token knows which application it is authenticating (for details, see [here](https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs)).
Nonetheless, [some attacks are still possible](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) even with U2F (more on this below).
## The Qubes approach to U2F
@ -34,7 +34,7 @@ In a conventional setup, web browsers and the USB stack (to which the U2F token
Since the U2F model assumes that the browser is trustworthy, any browser in the OS is able to access any key stored on the U2F token.
The user has no way to know which keys have been accessed by which browsers for which services.
If any of the browsers are compromised, it should be assumed that all of the token's keys have been compromised.
(This problem can be mitigated, however, if the U2F device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB].
(This problem can be mitigated, however, if the U2F device has a special display to show the user what's being authenticated.) Moreover, since the USB stack is in the same monolithic OS, the system is vulnerable to attacks like [BadUSB](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil).
In Qubes OS, by contrast, it is possible to securely compartmentalise the browser in one qube and the USB stack in another so that they are always kept separate from each other.
The Qubes U2F Proxy then allows the token connected to the USB stack in one qube to communicate with the browser in a separate qube.
@ -50,21 +50,21 @@ The frontend runs in the same qube as the browser and presents a fake USB-like H
The backend runs in `sys-usb` and behaves like a browser.
This is done using the `u2flib_host` reference library.
All of our code was written in Python.
The standard [qrexec] policy is responsible for directing calls to the appropriate domains.
The standard [qrexec](/doc/qrexec3/) policy is responsible for directing calls to the appropriate domains.
The `vault` qube with a dashed line in the bottom portion of the diagram depicts future work in which we plan to implement the Qubes U2F Proxy with a software token in an isolated qube rather than a physical hardware token.
This is similar to the manner in which [Split GPG] allows us to emulate the smart card model without physical smart cards.
This is similar to the manner in which [Split GPG](/doc/split-gpg/) allows us to emulate the smart card model without physical smart cards.
One very important assumption of U2F is that the browser verifies every request sent to the U2F token --- in particular, that the web application sending an authentication request matches the application that would be authenticated by answering that request (in order to prevent, e.g., a phishing site from sending an authentication request for your bank's site).
With the WebUSB feature in Chrome, however, a malicious website can [bypass][wired] this safeguard by connecting directly to the token instead of using the browser's U2F API.
With the WebUSB feature in Chrome, however, a malicious website can [bypass](https://www.wired.com/story/chrome-yubikey-phishing-webusb/) this safeguard by connecting directly to the token instead of using the browser's U2F API.
The Qubes U2F Proxy also prevents this class of attacks by implementing an additional verification layer.
This verification layer allows you to enforce, for example, that the web browser in your `twitter` qube can only access the U2F key associated with `https://twitter.com`.
This means that if anything in your `twitter` qube were compromised --- the browser or even the OS itself --- it would still not be able to access the U2F keys on your token for any other websites or services, like your email and bank accounts.
This is another significant security advantage over monolithic systems.
(For details and instructions, see the [Advanced usage] section below.)
(For details and instructions, see the [Advanced usage](#advanced-usage-per-qube-key-access) section below.)
For even more protection, you can combine this with the [Qubes firewall] to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
For even more protection, you can combine this with the [Qubes firewall](/doc/firewall/) to ensure, for example, that the browser in your `banking` qube accesses only one website (your bank's website).
By configuring the Qubes firewall to prevent your `banking` qube from accessing any other websites, you reduce the risk of another website compromising the browser in an attempt to bypass U2F authentication.
## Installation
@ -93,7 +93,7 @@ $ sudo apt install qubes-u2f
```
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your U2F token (but see [Browser support] below).
After that, you may use your U2F token (but see [Browser support](#templatevm-and-browser-support) below).
## Advanced usage: per-qube key access
@ -132,20 +132,5 @@ The large number of possible combinations of TemplateVM (Fedora 27, 28; Debian 8
In some cases, you may be the first person to try a particular combination.
Consequently (and as with any new feature), users will inevitably encounter bugs.
We ask for your patience and understanding in this regard.
As always, please [report any bugs you encounter].
As always, please [report any bugs you encounter](/doc/reporting-bugs/).
[Qubes U2F Proxy]: https://github.com/QubesOS/qubes-app-u2f
[USB]: /doc/usb/
[U2F]: https://en.wikipedia.org/wiki/U2F
[krebs]: https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/
[u2f-details]: https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-overview-v1.2-ps-20170411.html#site-specific-public-private-key-pairs
[wired]: https://www.wired.com/story/chrome-yubikey-phishing-webusb/
[BadUSB]: https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil
[qrexec]: /doc/qrexec3/
[Split GPG]: /doc/split-gpg/
[Qubes firewall]: /doc/firewall/
[Advanced usage]: #advanced-usage-per-qube-key-access
[Browser support]: #templatevm-and-browser-support
[report any bugs you encounter]: /doc/reporting-bugs/
[ff-u2f-addon]: https://addons.mozilla.org/en-US/firefox/addon/u2f-support-add-on/?src=api
[qubes-devel]: /support/#qubes-devel

9
user/troubleshooting/hardware-troubleshooting.md
View File

@ -16,7 +16,7 @@ By default, the kernel that is installed in dom0 comes from the `kernel` package
For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues.
For example, the audio might not work if the sound card is too new for the LTS kernel.
To fix this, you can try the `kernel-latest` package -- though be aware that it's less tested!
(See [here][dom0-kernel-upgrade] for more information about upgrading kernels in dom0).
(See [here](/doc/software-update-dom0/#kernel-upgrade) for more information about upgrading kernels in dom0).
In dom0:
~~~
@ -51,10 +51,5 @@ Do not edit it by hand, unless you know what you are doing.
Restarting `xorg` is required.
The most straightforward way is to reboot the system.
More information in [this discussion][layout_discussion] and [this GitHub issue][layout_issue].
More information in [this discussion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion) and [this GitHub issue](https://github.com/QubesOS/qubes-issues/issues/1396).
[dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade
[hardware-reqs]: /doc/installation-guide/#hardware-requirements
[layout_discussion]: https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion
[layout_issue]: https://github.com/QubesOS/qubes-issues/issues/1396

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

@ -91,11 +91,10 @@ During Qubes installation, you may come across the error message which reads "Un
Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally".
This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS.
Return to the [hardware requirements][hardware-reqs] section to learn how to activate it.
Return to the [hardware requirements](/doc/installation-guide/#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.
In Qubes 4.0, the default installation won't function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to "PV".
In Qubes 4.1, IOMMU is strictly required, even when the virtualization mode of a VM is changed to "PV"; it is not possible to use Qubes on a system without IOMMU.
[hardware-reqs]: /doc/installation-guide/#hardware-requirements

10
user/troubleshooting/update-troubleshooting.md
View File

@ -15,11 +15,11 @@ Usually, this is due to network problems (especially if downloading updates over
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- <https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/>
- <https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update>
- <https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/>
- <https://bugzilla.redhat.com/show_bug.cgi?id=1494178>
- <https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates>
- [https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/](https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/)
- [https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update](https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update)
- [https://www.reddit.com/r/Fedora/comments/74nldq/fedora\_26\_dnf\_error\_failed\_to\_synchronize\_cache/](https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/)
- [https://bugzilla.redhat.com/show\_bug.cgi?id=1494178](https://bugzilla.redhat.com/show_bug.cgi?id=1494178)
- [https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates](https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates)
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.

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

@ -62,9 +62,9 @@ Errors suggesting this issue:
- during `qvm-start sys-usb`:
`
```
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
`
```
Another solution would be to set the pci_strictreset option in dom0: