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

Markdown formatting fixes

Browse Source 
- mark all code blocks with ```
- unify empty lines between sections
- adjust list syntax (no space before dash)
- adjust headers to use Atx-style syntax
- remove trailing spaces
This commit is contained in:
Maya 2021-03-13 18:03:23 +01:00 committed by Marek Marczykowski-Górecki
parent 2bde7d07e0
commit 67a92614aa
No known key found for this signature in database
GPG Key ID: F32894BE9684938A
148 changed files with 4025 additions and 3639 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,16 +8,14 @@ redirect_from:
- /wiki/DevelopmentWorkflow/ - /wiki/DevelopmentWorkflow/
--- ---
Development Workflow # Development Workflow
====================
A workflow for developing Qubes OS+ A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
assumes you're using qubes-builder to build Qubes. assumes you're using qubes-builder to build Qubes.
Repositories and committing Code # Repositories and committing Code
--------------------------------
Qubes is split into a bunch of git repos. This are all contained in the Qubes is split into a bunch of git repos. This are all contained in the
`qubes-src` directory under qubes-builder. Subdirectories there are separate `qubes-src` directory under qubes-builder. Subdirectories there are separate
@ -162,8 +160,7 @@ verify tags and show the changes. This do not merge the changes - there are
left for review as FETCH\_HEAD ref. You can merge them using `git merge left for review as FETCH\_HEAD ref. You can merge them using `git merge
FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them. FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
Copying Code to dom0 ## Copying Code to dom0
--------------------
When developing it is convenient to be able to rapidly test changes. Assuming When developing it is convenient to be able to rapidly test changes. Assuming
you're developing Qubes on Qubes, you should be working in a special VM for you're developing Qubes on Qubes, you should be working in a special VM for
@ -309,7 +306,6 @@ to `testbuilder` VM. Otherwise it creates remote pointing at github account of
the same name. In any case it points at repository matching current directory the same name. In any case it points at repository matching current directory
name. name.
## Sending packages to different VM ## Sending packages to different VM
Other useful script(s) can be used to setup local package repository hosted in Other useful script(s) can be used to setup local package repository hosted in
@ -421,10 +417,10 @@ 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: 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] instead of [linux-yum] as a base - both in source and target VM
- use different `update_repo.sh` script in source VM (below) - use different `update_repo.sh` script in source VM (below)
- use `local.UpdateApt` qrexec service in target VM (code 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) - in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
`update_repo.sh` script: `update_repo.sh` script:

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

@ -10,8 +10,7 @@ redirect_from:
**Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.** **Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**
Building Qubes from scratch # Building Qubes from scratch
===========================
We have a fully automated build system for Qubes, that downloads, builds and We have a fully automated build system for Qubes, that downloads, builds and
packages all the Qubes components, and finally should spit out a ready-to-use packages all the Qubes components, and finally should spit out a ready-to-use
@ -39,7 +38,9 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou
Usually you can install those packages by just issuing: Usually you can install those packages by just issuing:
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA ```shell
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA
```
The build system creates build environments in chroots and so no other packages are needed on the host. The build system creates build environments in chroots and so no other packages are needed on the host.
All files created by the build system are contained within the qubes-builder directory. All files created by the build system are contained within the qubes-builder directory.
@ -49,66 +50,73 @@ The build system is configured via builder.conf file.
You can use the setup.sh script to create and modify this file. You can use the setup.sh script to create and modify this file.
Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.: Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.:
cp example-configs/qubes-os-master.conf builder.conf ```shell
# edit the builder.conf file and set the following variables: cp example-configs/qubes-os-master.conf builder.conf
NO_SIGN=1 # edit the builder.conf file and set the following variables:
NO_SIGN=1
```
One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password). One additional useful requirement is that 'sudo root' must work without any prompt, which is default on most distros (e.g. 'sudo bash' brings you the root shell without asking for any password).
This is important as the builder needs to switch to root and then back to user several times during the build process. This is important as the builder needs to switch to root and then back to user several times during the build process.
Additionally, if building with signing enabled (NO\_SIGN is not set), you must adjust \~/.rpmmacro file so that it points to the GPG key used for package signing, e.g.: Additionally, if building with signing enabled (NO\_SIGN is not set), you must adjust \~/.rpmmacro file so that it points to the GPG key used for package signing, e.g.:
%_signature gpg ```bash
%_gpg_path /home/user/.gnupg %_signature gpg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing %_gpg_path /home/user/.gnupg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
```
It is also recommended that you use an empty passphrase for the private key used for signing. It is also recommended that you use an empty passphrase for the private key used for signing.
Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over anyway, whether you have used an additional passphrase for the key or not. Contrary to a popular belief, this doesn't affect your key or sources security -- if somebody compromised your system, then the game is over anyway, whether you have used an additional passphrase for the key or not.
So, to build Qubes you would do: So, to build Qubes you would do:
# Import the Qubes master key ```shell
gpg --recv-keys 0xDDFA1A3E36879494 # Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
# Verify its fingerprint, set as 'trusted'. # Verify its fingerprint, set as 'trusted'.
# This is described here: # This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures # https://www.qubes-os.org/doc/VerifyingSignatures
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc gpg --import qubes-developers-keys.asc
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
cd qubes-builder cd qubes-builder
# Verify its integrity: # Verify its integrity:
git tag -v `git describe` git tag -v `git describe`
cp example-configs/qubes-os-master.conf builder.conf cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables: # edit the builder.conf file and set the following variables:
# NO_SIGN="1" # NO_SIGN="1"
# Download all components: # Download all components:
make get-sources make get-sources
# And now to build all Qubes rpms (this will take a few hours): # And now to build all Qubes rpms (this will take a few hours):
make qubes make qubes
# ... and then to build the ISO # ... and then to build the ISO
make iso make iso
```
And this should produce a shiny new ISO. And this should produce a shiny new ISO.
You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon: You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon:
```shell
make gui-daemon make gui-daemon
```
You can get a full list from make help. You can get a full list from make help.
Making customized build ## Making customized build
-----------------------
### Manual source modification ### Manual source modification
@ -118,10 +126,11 @@ Here are some basic steps:
1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command) 1. Download qubes-builder as described above (if you want to use marmarek's branches, you should also download qubes-builder from his repo - replace 'QubesOS' with 'marmarek' in above git clone command)
2. Edit builder.conf (still the same as above), some useful additions: 2. Edit builder.conf (still the same as above), some useful additions:
- You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions - You can also set GIT\_PREFIX="marmarek/qubes-" to use marmarek's repo instead of "mainstream" - it contains newer (but less tested) versions
3. Download unmodified sources 3. Download unmodified sources
```shell
make get-sources make get-sources
```
4. **Make your modifications here** 4. **Make your modifications here**
@ -133,11 +142,15 @@ Here are some basic steps:
6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing 6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
```shell
make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
```
1. build iso installation image 7. build iso installation image
```shell
make iso make iso
```
### Use pre-built Qubes packages ### Use pre-built Qubes packages
@ -146,19 +159,25 @@ This is especially true for `gcc`, which takes several hours to build.
Before creating the `chroot`, add this to your `builder.conf`: Before creating the `chroot`, add this to your `builder.conf`:
USE_QUBES_REPO_VERSION = $(RELEASE) ```
USE_QUBES_REPO_VERSION = $(RELEASE)
```
It will add the 'current' Qubes repository to your `chroot` environment. It will add the 'current' Qubes repository to your `chroot` environment.
Next, specify which components (`gcc`, for example) you want to download instead of compiling: Next, specify which components (`gcc`, for example) you want to download instead of compiling:
COMPONENTS := $(filter-out gcc,$(COMPONENTS)) ```
COMPONENTS := $(filter-out gcc,$(COMPONENTS))
```
Alternatively, edit the actual COMPONENTS list which is defined in the included version-dependent config from example-configs (see series of include directives near the beginning of `builder.conf`). Alternatively, edit the actual COMPONENTS list which is defined in the included version-dependent config from example-configs (see series of include directives near the beginning of `builder.conf`).
This way, you can build only the packages in which you are interested. This way, you can build only the packages in which you are interested.
If you also want to use the 'current-testing' repository, add this to your configuration: If you also want to use the 'current-testing' repository, add this to your configuration:
USE_QUBES_REPO_TESTING = 1 ```
USE_QUBES_REPO_TESTING = 1
```
In the case of an existing `chroot`, for mock-enabled builds, this works immediately because `chroot` is constructed each time separately. In the case of an existing `chroot`, for mock-enabled builds, this works immediately because `chroot` is constructed each time separately.
For legacy builds, it will not add the necessary configuration into the build environment unless a specific builder change or configuration would force rebuilding chroot. For legacy builds, it will not add the necessary configuration into the build environment unless a specific builder change or configuration would force rebuilding chroot.
@ -170,22 +189,22 @@ And even if it did, there could be some leftover packages installed from those r
If you are building Ubuntu templates, you cannot use this option. If you are building Ubuntu templates, you cannot use this option.
This is because Qubes does not provide official packages for Ubuntu templates. This is because Qubes does not provide official packages for Ubuntu templates.
Code verification keys management ## Code verification keys management
---------------------------------
[QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code. [QubesBuilder](/doc/qubes-builder/) by default verifies signed tags on every downloaded code.
Public keys used for that are stored in `keyrings/git`. Public keys used for that are stored in `keyrings/git`.
By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using: By default Qubes developers' keys are imported automatically, but if you need some additional keys (for example your own), you can add them using:
GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc ```shell
GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
# here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY
# here use "trust" command to set key fully or ultimately trusted - only those keys are accepted by QubesBuilder
```
All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically. All Qubes developers' keys are signed by the Qubes Master Signing Key (which is set as ultimately trusted key), so are trusted automatically.
If you are the owner of Master key and want to revoke such signature, use the `revsig` gpg key edit command and update the key in qubes-developers-keys.asc - now the key will be no longer trusted (unless manually set as such). If you are the owner of Master key and want to revoke such signature, use the `revsig` gpg key edit command and update the key in qubes-developers-keys.asc - now the key will be no longer trusted (unless manually set as such).
Further information ## Further information
-------------------
For advanced [QubesBuilder](/doc/qubes-builder/) use, and preparing sources, take a look at [QubesBuilderDetails](/doc/qubes-builder-details/) page, or [QubesBuilder's doc directory](https://github.com/marmarek/qubes-builder/tree/master/doc). For advanced [QubesBuilder](/doc/qubes-builder/) use, and preparing sources, take a look at [QubesBuilderDetails](/doc/qubes-builder-details/) page, or [QubesBuilder's doc directory](https://github.com/marmarek/qubes-builder/tree/master/doc).

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

@ -68,7 +68,6 @@ git tag -v `git describe`
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build. Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build.
The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources). The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources).
Build using setup script Build using setup script
----------------- -----------------
@ -128,7 +127,6 @@ make iso
Enjoy your new ISO! Enjoy your new ISO!
Build using manual steps Build using manual steps
----------------- -----------------

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

@ -4,14 +4,11 @@ title: Code Signing
permalink: /doc/code-signing/ permalink: /doc/code-signing/
--- ---
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] must be cryptographically signed by the author's PGP key.
## Generating a Key
Generating a Key
----------------
(Note: If you already have a PGP key, you may skip this step.) (Note: If you already have a PGP key, you may skip this step.)
@ -78,8 +75,7 @@ uid Bilbo Baggins <bilbo@shire.org>
sub 4096R/69B0EA85 2013-03-13 sub 4096R/69B0EA85 2013-03-13
~~~ ~~~
Upload the Key ## Upload the Key
--------------
For others to find the public key, please upload it to a server. For others to find the public key, please upload it to a server.
@ -88,8 +84,7 @@ $ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85
gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net
``` ```
Using PGP with Git ## Using PGP with Git
------------------
If you're submitting a patch via GitHub (or a similar Git server), please sign If you're submitting a patch via GitHub (or a similar Git server), please sign
your Git commits. your Git commits.
@ -141,8 +136,7 @@ your Git commits.
vtag = !git tag -v `git describe` vtag = !git tag -v `git describe`
~~~ ~~~
GitHub Signature Verification (optional) ## GitHub Signature Verification (optional)
----------------------------------------
GitHub shows a green `Verified` label indicating that the GPG signature could be 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 verified using any of the contributor’s GPG keys uploaded to GitHub. You can
@ -150,8 +144,7 @@ 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 key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
page]. page].
Code Signature Checks ## Code Signature Checks
---------------------
The [signature-checker] checks if code contributions are signed. 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: 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:
@ -171,21 +164,27 @@ In this case, you have several options to sign the commit:
1. Amend the commit and replace it with a signed commit. 1. Amend the commit and replace it with a signed commit.
You can use this command to create a new signed commit: You can use this command to create a new signed commit:
``` ```
git commit --amend -S git commit --amend -S
``` ```
This also rewrites the commit so you need to push it forcefully: This also rewrites the commit so you need to push it forcefully:
``` ```
git push -f git push -f
``` ```
2. Create a signed tag for the unsigned commit. 2. Create a signed tag for the unsigned commit.
If the commit is back in history and you do not want to change it, If the commit is back in history and you do not want to change it,
you can create a signed tag for this commit and push the signature. you can create a signed tag for this commit and push the signature.
You can use the alias from above: You can use the alias from above:
``` ```
git checkout <commit> git checkout <commit>
git spush git spush
``` ```
Now, the signature checker needs to re-check the signature. Now, the signature checker needs to re-check the signature.
Please comment on the pull request that you would like to have the signatures checked again. Please comment on the pull request that you would like to have the signatures checked again.
@ -198,15 +197,12 @@ 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. This might be that you forgot to upload the key to a key server.
Please upload it. Please upload it.
## Using PGP with Email
Using PGP with Email
--------------------
If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key. 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]. One good way to do this is with a program like [Enigmail].
Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails. 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/ [guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[source code]: /doc/source-code/ [source code]: /doc/source-code/
[developer mailing list]: /support/#qubes-devel [developer mailing list]: /support/#qubes-devel
@ -214,4 +210,3 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow
[signature-checker]: https://github.com/marmarek/signature-checker [signature-checker]: https://github.com/marmarek/signature-checker
[GitHub New GPG key]: https://github.com/settings/gpg/new [GitHub New GPG key]: https://github.com/settings/gpg/new
[GitHub SSH GPG keys page]: https://github.com/settings/keys [GitHub SSH GPG keys page]: https://github.com/settings/keys

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

@ -124,7 +124,7 @@ Source Code management (Git) guidelines
- Use git to maintain all code for Qubes project. - Use git to maintain all code for Qubes project.
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it. - Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
- Qubes code is divided into many git repositories. There are several reasons for that: - Qubes code is divided into many git repositories. There are several reasons for that:
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
@ -137,13 +137,13 @@ Commit message guidelines
Please attempt to follow these conventions when writing your Git commit messages: Please attempt to follow these conventions when writing your Git commit messages:
* Separate the subject line from the body with a blank line. - Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters. - Limit the subject line to approximately 50 characters.
* Capitalize the subject line. - Capitalize the subject line.
* Do not end the subject line with a period. - Do not end the subject line with a period.
* Use the imperative mood in the subject line. - Use the imperative mood in the subject line.
* Wrap the body at 72 characters. - Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*. - Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list. For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list.

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

@ -14,11 +14,11 @@ Qubes Source Code Repositories
All the Qubes code is kept in Git repositories. We have divided the project into All the Qubes code is kept in Git repositories. We have divided the project into
several components, each of which has its own separate repository, for example: several components, each of which has its own separate repository, for example:
* `core-admin.git` -- The core Qubes infrastructure, responsible for VM * `core-admin.git` -- The core Qubes infrastructure, responsible for VM
management, VM templates, fs sharing, etc. management, VM templates, fs sharing, etc.
* `gui-daemon.git` -- GUI virtualization, Dom0 side. * `gui-daemon.git` -- GUI virtualization, Dom0 side.
* `gui-agent-linux.git` -- GUI virtualization, Linux VM side. * `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
* `linux-template-builder.git` -- Scripts and other files used to create Qubes * `linux-template-builder.git` -- Scripts and other files used to create Qubes
template images. template images.
All of our repositories are available under the [QubesOS GitHub account]. All of our repositories are available under the [QubesOS GitHub account].
@ -53,7 +53,6 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
(Alternatively, you can pull instead of just fetching.) (Alternatively, you can pull instead of just fetching.)
How to Send Patches How to Send Patches
------------------- -------------------

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

@ -7,11 +7,9 @@ redirect_from:
- /doc/AutomatedTests/ - /doc/AutomatedTests/
--- ---
Automated Tests # Automated Tests
===============
Unit and Integration 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][unittest] 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). 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).
@ -46,6 +44,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a
You can use `python3 -m qubes.tests.run -h` to get usage information: You can use `python3 -m qubes.tests.run -h` to get usage information:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -h [user@dom0 ~]$ python3 -m qubes.tests.run -h
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
[--do-not-clean] [--do-clean] [--loglevel LEVEL] [--do-not-clean] [--do-clean] [--loglevel LEVEL]
@ -83,9 +82,11 @@ You can use `python3 -m qubes.tests.run -h` to get usage information:
When running only specific tests, write their names like in log, in format: When running only specific tests, write their names like in log, in format:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.". MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
Example: basic/TC_00_Basic/test_000_create Example: basic/TC_00_Basic/test_000_create
```
For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list: For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking network/VmNetworking_fedora-21/test_000_simple_networking
network/VmNetworking_fedora-21/test_010_simple_proxyvm network/VmNetworking_fedora-21/test_010_simple_proxyvm
@ -108,6 +109,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
[user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21` [user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
```
Example test run: Example test run:
@ -115,11 +117,12 @@ Example test run:
Tests are also compatible with nose2 test runner, so you can use this instead: Tests are also compatible with nose2 test runner, so you can use this instead:
```bash
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd 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].
### Unit testing inside a VM ### Unit testing inside a VM
Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped. Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped.
@ -132,6 +135,7 @@ its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec)
The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/). The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
```{.bash} ```{.bash}
cd ~ cd ~
sudo dnf install python3-pip lvm2 python35 python3-virtualenv sudo dnf install python3-pip lvm2 python35 python3-virtualenv
@ -158,16 +162,17 @@ the current stable branch.
Test runs can be altered using environment variables: Test runs can be altered using environment variables:
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format - `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card) - `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested - `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol) - `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
### Adding a new test to core-admin ### Adding a new test to core-admin
After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py) After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py)
#### Editing `__init__.py` #### Editing `__init__.py`
You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`. You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`.
Again, given the hypothetical `example.py` test: Again, given the hypothetical `example.py` test:
@ -237,11 +242,10 @@ class SomeTestCase(unittest.TestCase):
gc.collect() gc.collect()
~~~ ~~~
## Installation Tests with openQA
Installation Tests with openQA
------------------------------
**URL:** <https://openqa.qubes-os.org/> **URL:** <https://openqa.qubes-os.org/>
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos> **Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
Manually testing the installation of Qubes OS is a time-consuming process. Manually testing the installation of Qubes OS is a time-consuming process.
@ -258,4 +262,3 @@ Thanks to an anonymous donor, our openQA system is hosted in a datacenter on har
[unittest]: https://docs.python.org/3/library/unittest.html [unittest]: https://docs.python.org/3/library/unittest.html
[OpenQA]: http://open.qa/ [OpenQA]: http://open.qa/

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

@ -26,6 +26,7 @@ From dom0 terminal:
3: Attach the device to your newly created disp VM 3: Attach the device to your newly created disp VM
From the GUI, or from the command line: From the GUI, or from the command line:
```bash ```bash
[user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev
``` ```
@ -37,15 +38,19 @@ From the GUI, or from the command line:
``` ```
5: Umount and kill the VM 5: Umount and kill the VM
```
```bash
[user@dispXXXX]$ umount /mnt/ [user@dispXXXX]$ umount /mnt/
``` ```
6: Remove the image from qubesdb 6: Remove the image from qubesdb
```
```bash
[user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
``` ```
# References # References
https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625 Please consult this issue's [comment].
[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625

16
developer/debugging/profiling.md
View File

@ -8,15 +8,13 @@ redirect_from:
- /wiki/Profiling/ - /wiki/Profiling/
--- ---
Profiling # Profiling
=========
This is a python profiling primer. This is a python profiling primer.
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats. For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
Requirements ## Requirements
------------
~~~ ~~~
yum install gprof2dot graphviz yum install gprof2dot graphviz
@ -32,8 +30,7 @@ qvm-run -p qubes-dev 'cat ~/profiling/Upload.sh' > ~/profiling/Upload.sh
- WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned. - WARNING: this will obviously be running third-party code which is not signed by ITL nor Fedora. You have been warned.
Workflow ## Workflow
--------
### Identify function responsible for some slow action ### Identify function responsible for some slow action
@ -43,17 +40,21 @@ You have to select the area in which you suspect less than optimal performance.
Replace Replace
```python
def foo(self, bar): def foo(self, bar):
# function content # function content
```
with with
```python
def foo(self, *args, **kwargs): def foo(self, *args, **kwargs):
profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(), profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats')) time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
def real_foo(self, bar): def real_foo(self, bar):
# function content # function content
```
### Run application ### Run application
@ -88,8 +89,7 @@ This creates `index.html` with all SVG graphics linked to TXT files, ready for u
make REMOTE=example.com:public_html/qubes/profiling/ upload make REMOTE=example.com:public_html/qubes/profiling/ upload
~~~ ~~~
Example ## Example
-------
This example is from `qubes-manager` (`qubesmanager/main.py`). This example is from `qubes-manager` (`qubesmanager/main.py`).

21
developer/debugging/test-bench.md
View File

@ -8,20 +8,19 @@ redirect_from:
- /wiki/TestBench/ - /wiki/TestBench/
--- ---
Test bench for Dom0 # Test bench for Dom0
===================
This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal. This guide shows how to set up simple test bench that automatically test your code you're about to push. It is written especially for `core3` branch of `core-admin.git` repo, but some ideas are universal.
We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly. We will set up a spare machine (bare metal, not a virtual) that will be hosting our experimental Dom0. We will communicate with it via Ethernet and SSH. This tutorial assumes you are familiar with [QubesBuilder](/doc/qubes-builder/) and you have it set up and running flawlessly.
Setting up the machine ## Setting up the machine
----------------------
First, do a clean install from ISO you built or grabbed elsewhere. First, do a clean install from ISO you built or grabbed elsewhere.
You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else. You have to fix network, because it is intentionally broken. This script should reenable your network card without depending on anything else.
```bash
#!/bin/sh #!/bin/sh
# adjust this for your NIC (run lspci) # adjust this for your NIC (run lspci)
@ -53,6 +52,7 @@ You have to fix network, because it is intentionally broken. This script should
pcibind ${BDF} e1000e pcibind ${BDF} e1000e
dhclient dhclient
```
TODO: describe how to run this at every startup TODO: describe how to run this at every startup
@ -66,8 +66,7 @@ yum install openssh-server
Ensure that sudo works without password from your user account (it should by default). Ensure that sudo works without password from your user account (it should by default).
Development VM ## Development VM
--------------
### SSH ### SSH
@ -95,12 +94,15 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
`qtb-runtests`: `qtb-runtests`:
```bash
#!/bin/sh #!/bin/sh
ssh testbench python -m qubes.tests.run ssh testbench python -m qubes.tests.run
```
`qtb-install`: `qtb-install`:
```bash
#!/bin/sh #!/bin/sh
TMPDIR=/tmp/qtb-rpms TMPDIR=/tmp/qtb-rpms
@ -119,9 +121,11 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})" ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"
shift shift
done done
```
`qtb-iterate`: `qtb-iterate`:
```bash
#!/bin/sh #!/bin/sh
set -e set -e
@ -136,6 +140,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
make core-admin make core-admin
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
qtb-runtests qtb-runtests
```
### Hooking git ### Hooking git
@ -143,14 +148,18 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked
`core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability) `core-admin/.git/hooks/pre-commit`: (you may retain also the default hook, here omitted for readability)
```bash
#!/bin/sh #!/bin/sh
set -e set -e
python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())" python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
```
`core-admin/.git/hooks/pre-push`: `core-admin/.git/hooks/pre-push`:
```bash
#!/bin/sh #!/bin/sh
exec qtb-iterate exec qtb-iterate
```

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

@ -9,8 +9,7 @@ redirect_from:
- /wiki/SystemDoc/VMInterface/ - /wiki/SystemDoc/VMInterface/
--- ---
VM Configuration Interface # VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
@ -19,10 +18,9 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple
- Qubes RPC (called at VM startup, or when configuration changed) - Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol - GUI protocol
QubesDB ## QubesDB
--------------------
### Keys exposed by dom0 to VM ### ### Keys exposed by dom0 to VM
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` - `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` - `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
@ -47,7 +45,7 @@ QubesDB
- `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server - `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself - `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
#### Firewall rules in 3.x #### #### Firewall rules in 3.x
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
separate key for each target VM. Entries: separate key for each target VM. Entries:
@ -63,7 +61,7 @@ VM after applying rules may signal some error, writing a message to
`/qubes-iptables-error` key. This does not exclude any other way of `/qubes-iptables-error` key. This does not exclude any other way of
communicating problems - like a popup. communicating problems - like a popup.
#### Firewall rules in 4.x #### #### Firewall rules in 4.x
QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
a separate entry, grouped on target VM: a separate entry, grouped on target VM:
@ -85,19 +83,19 @@ Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. QubesDB enforces limit on a single entry length - 3072 bytes. by space. QubesDB enforces limit on a single entry length - 3072 bytes.
Possible options for a single rule: Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present in every rule - `action`, values: `accept`, `drop`; this is present in every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dsthost`, value: DNS hostname of destination host - `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp` - `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values: - `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but - `dns` - such option should match DNS traffic to default DNS server (but
not any DNS server), on both TCP and UDP not any DNS server), on both TCP and UDP
- `dstports`, value: destination ports range separated with `-`, valid only - `dstports`, value: destination ports range separated with `-`, valid only
together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80` together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for - `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
echo request, valid only together with `proto=icmp` echo request, valid only together with `proto=icmp`
- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering - `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering
Options must appear in the rule in the order listed above. Duplicated options Options must appear in the rule in the order listed above. Duplicated options
are forbidden. are forbidden.
@ -117,7 +115,7 @@ Example valid rules:
- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP - `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
- `action=drop` - `action=drop`
### Keys set by VM for passing info to dom0 ### ### Keys set by VM for passing info to dom0
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; - `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
@ -130,8 +128,7 @@ Example valid rules:
- `desc` - device description (ASCII text) - `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3) - `usb-ver` - USB version (1, 2 or 3)
Qubes RPC ## Qubes RPC
---------
Services called by dom0 to provide some VM configuration: Services called by dom0 to provide some VM configuration:
@ -158,7 +155,6 @@ Services called by dom0 to provide some VM configuration:
Name of disk image is passed on standard input (`root`, `private`, `volatile`, Name of disk image is passed on standard input (`root`, `private`, `volatile`,
or other). This is used starting with Qubes 4.0. or other). This is used starting with Qubes 4.0.
Other Qrexec services installed by default: Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by - `qubes.Backup` - store Qubes backup. The service receives location chosen by
@ -224,7 +220,6 @@ abstraction. This will change in the future. Those tools are:
Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that. Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
GUI protocol ## GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call. GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

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

@ -8,8 +8,7 @@ redirect_from:
- /wiki/WindowsDebugging/ - /wiki/WindowsDebugging/
--- ---
Debugging Windows HVMs # Debugging Windows HVMs
======================
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs. Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
@ -23,16 +22,19 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later. - To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: - To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
```bash
#!/bin/sh #!/bin/sh
id1=$(xl domid "$1-dm") id1=$(xl domid "$1-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
echo $tty1 echo $tty1
```
Pass it a running VM name and it will output the corresponding pty name. Pass it a running VM name and it will output the corresponding pty name.
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that: - To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
```bash
#!/bin/sh #!/bin/sh
id1=$(xl domid "$1-dm") id1=$(xl domid "$1-dm")
@ -40,11 +42,12 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty) tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
socat $tty1,raw $tty2,raw socat $tty1,raw $tty2,raw
```
...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0. ...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port. - On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. - On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- Reboot the *target* VM. - Reboot the *target* VM.
- Run the above shell script in dom0. - Run the above shell script in dom0.
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: - If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
@ -73,6 +76,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works: ...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
```c
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <fcntl.h> #include <fcntl.h>
@ -182,6 +186,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
close(fd2); close(fd2);
return 0; return 0;
} }
```
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like: > This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
> >
@ -214,7 +219,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
There are two main issues to be adopted to get all things to work in the R4.0. There are two main issues to be adopted to get all things to work in the R4.0.
## Add a virtual serial port ## ## Add a virtual serial port
Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console. Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console.
@ -228,15 +233,17 @@ $ gunzip stubdom-linux-rootfs.gz
$ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs $ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
$ rm stubdom-linux-rootfs $ rm stubdom-linux-rootfs
``` ```
2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line. 2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
3. Apply changes: 3. Apply changes:
```shell_session ```shell_session
$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs $ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot $ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
``` ```
## Connect two consoles ## ## Connect two consoles
Run the following script: Run the following script:

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

@ -11,19 +11,19 @@ redirect_from:
Below is a list of various books that might be useful in learning some basics needed for Qubes development. Below is a list of various books that might be useful in learning some basics needed for Qubes development.
- A must-read about Xen internals: - A must-read about Xen internals:
* _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall - _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall
- Some good books about the Linux kernel: - Some good books about the Linux kernel:
* _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love - _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love
* _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet - _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet
- Solid intro into Trusted Computing: - Solid intro into Trusted Computing:
* _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT) - _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT)
- Good book about GIT: - Good book about GIT:
* _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online) - _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
- Useful books about Python: - Useful books about Python:
* _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield - _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
* _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield - _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
(Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.) (Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

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

@ -16,7 +16,6 @@ By cloning and regularly pulling from this repo, users can maintain their own up
The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive. 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][contribute]!
## Security ## Security
*Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)* *Also see: [Should I trust this website?](/faq/#should-i-trust-this-website)*
@ -33,7 +32,6 @@ The documentation maintainer then verifies that the pull request is mechanically
If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote. If so, the documentation maintainer then merges the pull request, adds a PGP-signed tag to the latest commit (usually the merge commit), then pushes to the remote.
In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag). In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
## Questions, problems, and improvements ## 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 have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
@ -41,18 +39,17 @@ If you see that something in the documentation should be fixed or improved, plea
To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue]. To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.) (If you 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 ## How to contribute
Editing the documentation is easy, so if you see that a change should be made, please contribute it! Editing the documentation is easy, so if you see that a change should be made, please contribute it!
A few notes before we get started: A few notes before we get started:
* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted. * 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. 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. * 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][issue] 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. * 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. 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. 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.
@ -113,8 +110,7 @@ If, for some reason, we can't accept your pull request, we'll post a comment exp
[![done](/attachment/wiki/doc-edit/10-done.png)](/attachment/wiki/doc-edit/10-done.png) [![done](/attachment/wiki/doc-edit/10-done.png)](/attachment/wiki/doc-edit/10-done.png)
## How to add images
### How to add images
To add an image to a page, use the following syntax in the main document. To add an image to a page, use the following syntax in the main document.
This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself. This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself.
@ -127,7 +123,6 @@ Then, submit your image(s) in a separate pull request to the [qubes-attachment]
This is the only permitted way to include images. This is the only permitted way to include images.
Do not link to images on other websites. Do not link to images on other websites.
## Organizational guidelines ## Organizational guidelines
### Do not duplicate documentation ### Do not duplicate documentation
@ -231,7 +226,6 @@ To foo:
Once you foo, make sure to close the baz before fooing the next bar. Once you foo, make sure to close the baz before fooing the next bar.
## Qubes 4.0 ## ## Qubes 4.0 ##
### How to Foo ### ### How to Foo ###
@ -251,7 +245,7 @@ Once you foo, make sure to close the baz before fooing the next bar.
Subdividing the page into clearly-labeled sections for each version has several benefits: Subdividing the page into clearly-labeled sections for each version has several benefits:
* It preserves good content for older (but still supported) versions. * It preserves good content for older (but still supported) versions.
Many documentation contributors are also people who prefer to use the latest version. Many documentation contributors are also people who prefer to use the latest version.
Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version. Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
This is somewhat understandable. This is somewhat understandable.
@ -261,15 +255,15 @@ Subdividing the page into clearly-labeled sections for each version has several
With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation. With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation.
Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision. Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it. It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version. * It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
* It's hard for readers to miss information they need, since it's all in one place. * It's hard for readers to miss information they need, since it's all in one place.
In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page. In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page.
In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored. In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice. The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated. Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing: Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software. We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software.
* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions. * It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions. Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions.
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so. By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
@ -281,10 +275,9 @@ Good general content that was submitted only to one branch would effectively dis
For further discussion about version-specific documentation in Qubes, see [here][version-thread]. For further discussion about version-specific documentation in Qubes, see [here][version-thread].
## Style guidelines ## Style guidelines
* Familiarize yourself with the terms defined in the [glossary]. Use these * Familiarize yourself with the terms defined in the [glossary]. Use these
terms consistently and accurately throughout your writing. terms consistently and accurately throughout your writing.
* Syntactically distinguish variables in commands. * Syntactically distinguish variables in commands.
For example, this is ambiguous: For example, this is ambiguous:
@ -300,7 +293,6 @@ For further discussion about version-specific documentation in Qubes, see [here]
2. Using underscores (`_`) between words 2. Using underscores (`_`) between words
3. Using all capital letters 3. Using all capital letters
## Markdown conventions ## Markdown conventions
All the documentation is written in Markdown for maximum accessibility. All the documentation is written in Markdown for maximum accessibility.
@ -320,14 +312,15 @@ When making contributions, please try to observe the following style conventions
* 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). * 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).
* Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text. * Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text.
It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability. It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability.
* If appropriate, make numerals in numbered lists match between Markdown source and HTML output. * If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions. * Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Use hanging indentations * Use hanging indentations
where appropriate. where appropriate.
* Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc. * Use Atx-style headings: `# h1`, `##h 2`, `### h3`, etc.
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted. * When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When providing command line examples: * When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown ~~~markdown
Open a terminal in dom0 and run: Open a terminal in dom0 and run:
```shell_session ```shell_session
@ -336,10 +329,12 @@ When making contributions, please try to observe the following style conventions
Hello Hello
``` ```
~~~ ~~~
* Precede each command with the appropriate command prompt: * Precede each command with the appropriate command prompt:
At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively. At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Don't try to add comments inside the code block. * Don't try to add comments inside the code block.
For example, *don't* do this: For example, *don't* do this:
~~~markdown ~~~markdown
Open a terminal in dom0 and run: Open a terminal in dom0 and run:
```shell_session ```shell_session
@ -350,18 +345,17 @@ When making contributions, please try to observe the following style conventions
Hello Hello
``` ```
~~~ ~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt. The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose. Instead, put your comments *outside* of the code block in normal prose.
([This][md] is a great source for learning about Markdown.) ([This][md] is a great source for learning about Markdown.)
## Git conventions ## Git conventions
Please try to write good commit messages, according to the Please try to write good commit messages, according to the
[instructions in our coding style guidelines][git-commit]. [instructions in our coding style guidelines][git-commit].
[qubes-doc]: https://github.com/QubesOS/qubes-doc [qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/ [glossary]: /doc/glossary/
[issue]: /doc/reporting-bugs/ [issue]: /doc/reporting-bugs/

148
developer/general/gsoc.md
View File

@ -98,17 +98,17 @@ If applicable, links to more information or discussions
**Expected results**: **Expected results**:
- Design how Vagrant Qubes provider should look like, including: - Design how Vagrant Qubes provider should look like, including:
- [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format) - [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
- method for running commands inside (ssh vs qvm-run) - method for running commands inside (ssh vs qvm-run)
- Write a Vagrant provider able to create/start/stop/etc a VM - Write a Vagrant provider able to create/start/stop/etc a VM
- Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules - Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules
- Write integration tests - Write integration tests
**Knowledge prerequisite**: **Knowledge prerequisite**:
- Ruby - Ruby
- Vagrant concepts - Vagrant concepts
**Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/) **Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/)
@ -124,7 +124,6 @@ If applicable, links to more information or discussions
- Implementation of the above mechanism. - Implementation of the above mechanism.
- Documentation how to configure it securely. - Documentation how to configure it securely.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- shell and/or python scripting - shell and/or python scripting
@ -151,10 +150,11 @@ Choose either of GUI agent, GUI daemon. Both are of similar complexity and each
- implement tests for new GUI handling, similar to existing tests for X11 based GUI - implement tests for new GUI handling, similar to existing tests for X11 based GUI
Relevant links: Relevant links:
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux) - [Low level GUI documentation](/doc/gui/)
- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon) - [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366) - [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
**Knowledge prerequisite**: **Knowledge prerequisite**:
@ -181,21 +181,21 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
**Expected results**: **Expected results**:
- Adjust set of VMs and templates included in live edition. - Adjust set of VMs and templates included in live edition.
- Update and fix build scripts for recent Qubes OS version. - Update and fix build scripts for recent Qubes OS version.
- Update startup script to mount appropriate directories as either - Update startup script to mount appropriate directories as either
copy-on-write (device-mapper snapshot), or tmpfs. copy-on-write (device-mapper snapshot), or tmpfs.
- Optimize memory usage: should be possible to run sys-net, sys-firewall, and - Optimize memory usage: should be possible to run sys-net, sys-firewall, and
at least two more VMs on 4GB machine. This include minimizing writes to at least two more VMs on 4GB machine. This include minimizing writes to
copy-on-write layer and tmpfs (disable logging etc). copy-on-write layer and tmpfs (disable logging etc).
- Research option to install the system from live image. If feasible add - Research option to install the system from live image. If feasible add
this option. this option.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd. - System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- Python and Bash scripting - Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files. - Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
**Mentor**: [Frédéric Pierret](/team/) **Mentor**: [Frédéric Pierret](/team/)
@ -219,7 +219,6 @@ REMOVED as of January 2020: work is being done on this
**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/) **Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
--> -->
### LogVM(s) ### LogVM(s)
**Project**: LogVM(s) **Project**: LogVM(s)
@ -232,35 +231,36 @@ immune to altering past entries. See
**Expected results**: **Expected results**:
- Design a _simple_ protocol for transferring logs. The less metadata (parsed - Design a _simple_ protocol for transferring logs. The less metadata (parsed
in log-collecting VM) the better. in log-collecting VM) the better.
- Implement log collecting service. Besides logs itself, should save - Implement log collecting service. Besides logs itself, should save
information about logs origin (VM name) and timestamp. The service should information about logs origin (VM name) and timestamp. The service should
_not_ trust sending VM in any of those. _not_ trust sending VM in any of those.
- Implement log forwarder compatible with systemd-journald and rsyslog. A - Implement log forwarder compatible with systemd-journald and rsyslog. A
mechanism (service/plugin) fetching logs in real time from those and sending mechanism (service/plugin) fetching logs in real time from those and sending
to log-collecting VM over qrexec service. to log-collecting VM over qrexec service.
- Document the protocol. - Document the protocol.
- Write unit tests and integration tests. - Write unit tests and integration tests.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- syslog - syslog
- systemd - systemd
- Python/Bash scripting - Python/Bash scripting
**Mentor**: [Frédéric Pierret](/team/) **Mentor**: [Frédéric Pierret](/team/)
### Whonix IPv6 and nftables support ### Whonix IPv6 and nftables support
**Project**: Whonix IPv6 and nftables support **Project**: Whonix IPv6 and nftables support
**Brief explanation**: [T509](https://phabricator.whonix.org/T509) **Brief explanation**: [T509](https://phabricator.whonix.org/T509)
**Expected results**: **Expected results**:
- Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397 - Work at upstream Tor: An older version of [TransparentProxy](https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy) page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. [here](https://trac.torproject.org/projects/tor/ticket/21397)
- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39 - implement corridor feature request add IPv6 support / port to nftables - [issue](https://github.com/rustybird/corridor/issues/39)
- port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables - port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables
- make connections to IPv6 Tor relays work - make connections to IPv6 Tor relays work
- make connections to IPv6 destinations work - make connections to IPv6 destinations work
@ -293,19 +293,19 @@ immune to altering past entries. See
**Expected results**: **Expected results**:
- A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user. - A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user.
- A tool for generating actual `autounattended.xml` file based on the template and user settings. - A tool for generating actual `autounattended.xml` file based on the template and user settings.
- A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point). - A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point).
- (Optional) Unattended installation should also include Qubes Windows Tools. - (Optional) Unattended installation should also include Qubes Windows Tools.
- (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu) - (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu)
- User documentation - User documentation
- Automated tests (unit tests, integration tests) - Automated tests (unit tests, integration tests)
**Knowledge prerequisite**: **Knowledge prerequisite**:
- Python scripting - Python scripting
- Linux administration, including handling loop devices, partition tables, filesystems etc - Linux administration, including handling loop devices, partition tables, filesystems etc
- For optional features, C language and x86 architecture (ACPI tables) - For optional features, C language and x86 architecture (ACPI tables)
**Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/) **Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/)
@ -315,33 +315,33 @@ immune to altering past entries. See
**Brief explanation**: Integrating GNOME into Qubes dom0. This include: **Brief explanation**: Integrating GNOME into Qubes dom0. This include:
- patching window manager to add colorful borders - patching window manager to add colorful borders
- removing stuff not needed in dom0 (file manager(s), indexing services etc) - removing stuff not needed in dom0 (file manager(s), indexing services etc)
- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place) - adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806) - More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
**Expected results**: **Expected results**:
- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome). - Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- Patch window manager to draw colorful borders (we use only server-side - Patch window manager to draw colorful borders (we use only server-side
decorations), there is already very similar patch in decorations), there is already very similar patch in
[Cappsule project](https://github.com/cappsule/cappsule-gui). [Cappsule project](https://github.com/cappsule/cappsule-gui).
- Configure GNOME to not make use of dom0 user home in visible way (no search - Configure GNOME to not make use of dom0 user home in visible way (no search
in files there, no file manager, etc). in files there, no file manager, etc).
- Configure GNOME to not look into external devices plugged in (no auto - Configure GNOME to not look into external devices plugged in (no auto
mounting, device notifications etc). mounting, device notifications etc).
- Package above modifications as rpms, preferably as extra configuration files - Package above modifications as rpms, preferably as extra configuration files
and/or plugins than overwriting existing files. Exceptions to this rule may and/or plugins than overwriting existing files. Exceptions to this rule may
apply if no other option. apply if no other option.
- Adjust comps.xml (in installer-qubes-os repo) to define package group with - Adjust comps.xml (in installer-qubes-os repo) to define package group with
all required packages. all required packages.
- Document installation procedure. - Document installation procedure.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- GNOME architecture - GNOME architecture
- C language (patching metacity) - C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions - Probably also javascript - for modifying GNOME shell extensions
**Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/) **Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/)
@ -358,6 +358,7 @@ immune to altering past entries. See
**Mentors**: Andrew Clausen and Jean-Philippe Ouellet **Mentors**: Andrew Clausen and Jean-Philippe Ouellet
### Progress towards reproducible builds ### Progress towards reproducible builds
**Project**: Progress towards reproducible builds **Project**: Progress towards reproducible builds
**Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See: **Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See:
@ -384,21 +385,21 @@ Qubes currently only supports the x86_64 CPU architecture. Xen currently has add
Some related discussion: Some related discussion:
- [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64. - [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64.
- [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel. - [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel.
**Expected results**: **Expected results**:
- Add cross-compilation support to qubes-builder and related components. - Add cross-compilation support to qubes-builder and related components.
- Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). - Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- Aarch64 specific integration and unit tests. - Aarch64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware. - Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages). - Libvirt and Qubes toolstacks (C and python languages).
- Xen debugging. - Xen debugging.
- General ARM architecture knowledge. - General ARM architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/) **Mentor**: [Marek Marczykowski-Górecki](/team/)
@ -426,16 +427,16 @@ More information and further links can be found in the related issue:
**Expected results**: **Expected results**:
- Add cross-compilation support to qubes-builder and related components. - Add cross-compilation support to qubes-builder and related components.
- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains). - Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- ppc64 specific integration and unit tests. - ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware. - Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**: **Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages). - Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals - KVM or XEN internals
- General ppc64 architecture knowledge. - General ppc64 architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/) **Mentor**: [Marek Marczykowski-Górecki](/team/)
@ -451,11 +452,12 @@ Since it's software emulation it's rather slow.
Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233) Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
**Expected results**: **Expected results**:
- a simple way of setting up Android qubes with hardware emulation
- a simple way of setting up Android qubes with hardware emulation
(distributed as a template or as a salt, handling various modern Android versions) (distributed as a template or as a salt, handling various modern Android versions)
- figuring out and implementing an easy and secure way to connect an Android - figuring out and implementing an easy and secure way to connect an Android
qube to a development qube with Android studio qube to a development qube with Android studio
- documentation and tests - documentation and tests
**Knowledge prerequisite**: **Knowledge prerequisite**:

15
developer/general/gsod.md
View File

@ -29,6 +29,7 @@ Here's a suggested template for adding project ideas:
**Mentor**: Name and email address. **Mentor**: Name and email address.
``` ```
### Offline documentation ### Offline documentation
**Project**: Offline documentation **Project**: Offline documentation
@ -37,13 +38,13 @@ Here's a suggested template for adding project ideas:
**Expected results**: **Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019) - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
- Recommend workflow and platform for displaying offline documentation - Recommend workflow and platform for displaying offline documentation
- Test workflow and platform to ensure usability and functionality - Test workflow and platform to ensure usability and functionality
**Knowledge prerequisite**: **Knowledge prerequisite**:
- [Markdown][markdown] - [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team] **Mentor**: [Marek Marczykowski-Górecki][team]
@ -55,12 +56,12 @@ Here's a suggested template for adding project ideas:
**Expected results**: **Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774) - Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
- Provide visual mock-ups and proposed text - Provide visual mock-ups and proposed text
**Knowledge prerequisite**: **Knowledge prerequisite**:
- some experience with Anaconda would be helpful - some experience with Anaconda would be helpful
**Mentor**: [Marek Marczykowski-Górecki][team] **Mentor**: [Marek Marczykowski-Górecki][team]

1
developer/general/join.md
View File

@ -10,4 +10,3 @@ Joining the Qubes OS Team
The Qubes OS Project does not currently have any open positions. The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available. This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

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

@ -15,38 +15,41 @@ This page explains the inclusion criteria and procedures for such packages, as w
Inclusion Criteria Inclusion Criteria
------------------ ------------------
In order to be accepted, packages must: In order to be accepted, packages must:
* In no way weaken the security of Qubes OS. * In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]). * Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines]. * Follow our [coding guidelines].
* Be thoroughly tested. * Be thoroughly tested.
* Have a clearly-defined use case for Qubes users. * Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review. * Not be unduly burdensome to review.
(Please note that we always reserve the right to add criteria to this list.) (Please note that we always reserve the right to add criteria to this list.)
Contribution Procedure 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].
Once you have a package that's ready to become part of Qubes OS, please follow this procedure: 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]. 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]. 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]. 3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`. 4. Create an issue in [qubes-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. 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. 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. 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.
If this happens, please do not be discouraged. If this happens, please do not be discouraged.
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). 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! We appreciate your understanding!
5. You may be asked followup questions. 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] 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 not to accept your contribution, we will state the reason and close the issue. If we decide not to accept your contribution, we will state the reason and close the issue.
Update Procedure Update Procedure
---------------- ----------------
*Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package! *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. The update procedure is the same for everyone, including the original package contributor.
@ -57,6 +60,7 @@ Please be prepared to read and respond to these comments.
Review Procedure 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]). 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). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
In all cases, the QCR will be a core Qubes developer. In all cases, the QCR will be a core Qubes developer.
@ -65,38 +69,39 @@ For example, if someone contributes a package, then disappears, and no suitable
The review procedure is as follows: The review procedure is as follows:
1. Someone, S, wishes to make a change to a package, P. 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].
3. The PM reviews the pull request. 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. 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.) (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 pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not. 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. 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][sig] 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. 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] 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:
- Package dependencies,
- Build scripts (including downloaded ones), * Package dependencies,
- All downloaded components should be verified against static hash, * Build scripts (including downloaded ones),
- RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages), * All downloaded components should be verified against static hash,
- Makefiles, * RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
- Package build [reproducible] * Makefiles,
* Package build [reproducible]
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].
Package Maintainers Package Maintainers
------------------- -------------------
If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. 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: 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. * 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 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. 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/ [installing contributed packages]: /doc/installing-contributed-packages/
[Inclusion Criteria]: #inclusion-criteria [Inclusion Criteria]: #inclusion-criteria
[Contribution Procedure]: #contribution-procedure [Contribution Procedure]: #contribution-procedure

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

@ -4,8 +4,7 @@ title: Usability & UX
permalink: /doc/usability-ux/ permalink: /doc/usability-ux/
--- ---
Usability & UX # Usability & UX
==============
Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority!
@ -39,7 +38,6 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura
In making software easy to use, it is crucial to be mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* Making sure your interfaces don't pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed. In making software easy to use, it is crucial to be mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* Making sure your interfaces don't pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
--- ---
## Easy to Understand ## Easy to Understand

16
developer/releases/1_0/release-notes.md
View File

@ -6,13 +6,11 @@ redirect_from:
- /en/doc/releases/1.0/release-notes/ - /en/doc/releases/1.0/release-notes/
--- ---
Qubes R1.0 Release Notes # Qubes R1.0 Release Notes
========================
Detailed release notes in [this blog post](https://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html). Detailed release notes in [this blog post](https://blog.invisiblethings.org/2012/09/03/introducing-qubes-10.html).
Known issues ## Known issues
------------
- Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected). - Installer might not support some USB keyboards (\#230). This seems to include all the Mac Book keyboards (most PC laptops have PS2 keyboards and are not affected).
@ -29,18 +27,15 @@ Known issues
- On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again. - On some systems the KDE Window Manager might freeze upon resuming from S3 sleep when compositing is enabled (and the only method to log in to the system if this happens is to switch to a text console, enter your user's password, kill the kwin process, go back to the Xorg console, log in, and start a new instance of kwin using Konsole application :) If you experience such problems, make sure to disable compositing before putting the system into sleep by pressing Alt-Ctrl-F12 (and then enabling it back once you log in after resume) -- this way you should never see this problem again.
Downloads ## Downloads
---------
See [Qubes Downloads](/doc/QubesDownloads/). See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
Upgrading ## Upgrading
---------
### From Qubes 1.0-rc1 ### From Qubes 1.0-rc1
@ -53,4 +48,3 @@ If you have Qubes Beta 3 currently installed on your system, you must reinstall
~~~ ~~~
qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64 qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64
~~~ ~~~

30
developer/releases/2_0/release-notes.md
View File

@ -6,13 +6,11 @@ redirect_from:
- /en/doc/releases/2.0/release-notes/ - /en/doc/releases/2.0/release-notes/
--- ---
Qubes R2.0 Release Notes # Qubes R2.0 Release Notes
========================
Detailed release notes in [this blog post](https://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html) Detailed release notes in [this blog post](https://blog.invisiblethings.org/2014/09/26/announcing-qubes-os-release-2.html)
New features since 1.0 ## New features since 1.0
----------------------
* Support for generic fully virtualized VMs (without qemu in the TCB!) * Support for generic fully virtualized VMs (without qemu in the TCB!)
* Support for Windows-based AppVMs integration (clipboard, file exchange, qrexec, pv drivers) * Support for Windows-based AppVMs integration (clipboard, file exchange, qrexec, pv drivers)
@ -28,35 +26,31 @@ New features since 1.0
* Support for dynamic screen resolution change * Support for dynamic screen resolution change
* Dom0 distribution upgraded to Fedora 20 * Dom0 distribution upgraded to Fedora 20
Known issues ## Known issues
------------
- On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer). * On some graphics cards the Xfce4 Window Manager (one of the two supported Dom0 Windows Managers in Qubes R2, the other being KDE) might behave "strangely", e.g. decorations might not be drawn sometimes. Also the accompanying lightdm login manager might incorrectly display the wallpaper. If you're facing those problems, it's advisable to use the KDE Window Manager and kdm instead of Xfce4 and lightdm (this is default if one chooses the KDE only installation option in the installer).
- Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead. * Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
- If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system. * If your GPU is not correctly supported by the Dom0 kernel (e.g. the 3D desktop effects do not run smoothly) then you might experience "heaviness" with Windows 7-based AppVMs. In that case, please solve the problem with your GPU support in Dom0 in the first place (by using a different kernel), or install Qubes OS on a different system.
- Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually. * Under some circumstances, Qubes backup can create broken backup, without any visible message (\#902). It is advisable to verify a backup to spot the problem. If you encounter this problem, backup VM directory manually.
- System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first. * System shutdown sometimes is very slow (\#903). To mitigate the problem, shutdown all the VMs first.
- For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority) * For other known issues take a look at [our trac tickets](https://wiki.qubes-os.org/query?status=accepted&status=assigned&status=new&status=reopened&type=defect&milestone=Release+2.1+(post+R2)&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority)
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads ## Downloads
---------
See [Qubes Downloads](/doc/QubesDownloads/). See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
Upgrading ## Upgrading
---------
### From Qubes R2 rc1 ### From Qubes R2 rc1

19
developer/releases/3_0/release-notes.md
View File

@ -6,13 +6,11 @@ redirect_from:
- /en/doc/releases/3.0/release-notes/ - /en/doc/releases/3.0/release-notes/
--- ---
Qubes R3.0 Release Notes ### Qubes R3.0 Release Notes
========================
This Qubes OS release is dedicated to the memory of Caspar Bowden. This Qubes OS release is dedicated to the memory of Caspar Bowden.
New features since 2.0 ## New features since 2.0
----------------------
* HAL (Hypervisor Abstraction Layer) - based on libvirt, opens a whole new * HAL (Hypervisor Abstraction Layer) - based on libvirt, opens a whole new
possibilities of using different hypervisors. Currently Qubes OS uses Xen. possibilities of using different hypervisors. Currently Qubes OS uses Xen.
@ -27,8 +25,7 @@ New features since 2.0
templates using DispVM. templates using DispVM.
* Automated tests - makes much easier to find bugs, before its even shipped to users * Automated tests - makes much easier to find bugs, before its even shipped to users
Known issues ## Known issues
------------
* Windows Tools: `qvm-block` does not work * Windows Tools: `qvm-block` does not work
@ -42,18 +39,15 @@ Known issues
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads ## Downloads
---------
See [Qubes Downloads](/doc/QubesDownloads/). See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
Upgrading ## Upgrading
---------
### From R3.0 release candidate ### From R3.0 release candidate
@ -64,4 +58,3 @@ If you are using Qubes R3.0rc1, R3.0rc2 or R3.0rc3, just install system updates,
The easiest and safest way to upgrade to Qubes R3.0 is to install it from scratch and use [qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs. The easiest and safest way to upgrade to Qubes R3.0 is to install it from scratch and use [qubes backup and restore tools](/doc/backup-restore/) for migrating of all of the user VMs.
Users of Qubes R2 can upgrade using [experimental procedure](/doc/upgrade-to-r3.0/). Users of Qubes R2 can upgrade using [experimental procedure](/doc/upgrade-to-r3.0/).

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

@ -4,11 +4,9 @@ title: Qubes R3.1 release notes
permalink: /doc/releases/3.1/release-notes/ permalink: /doc/releases/3.1/release-notes/
--- ---
Qubes R3.1 release notes # Qubes R3.1 release notes
========================
New features since 3.0 ## 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][salt-doc]
* Out of the box Whonix setup * Out of the box Whonix setup
@ -23,8 +21,7 @@ New features since 3.0
You can get detailed description in [completed github issues][github-release-notes] You can get detailed description in [completed github issues][github-release-notes]
Known issues ## Known issues
------------
* Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more) * Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more)
@ -38,18 +35,15 @@ Known issues
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads ## Downloads
---------
See [Qubes Downloads](/downloads/). See [Qubes Downloads](/downloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
Upgrading ## Upgrading
---------
### From R3.0 ### From R3.0

2
developer/releases/3_1/schedule.md
View File

@ -18,4 +18,4 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
| 12 Jan 2016 | 3.1-rc2 release | | 12 Jan 2016 | 3.1-rc2 release |
| 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 | | 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 |
| 9 Feb 2016 | current-testing freeze before 3.1-rc3 | | 9 Feb 2016 | current-testing freeze before 3.1-rc3 |
| <strike>16 Feb 2016</strike><br/>23 Feb 2016 | 3.1-rc3 release | | ~~16 Feb 2016~~ <br/> 23 Feb 2016 | 3.1-rc3 release |

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

@ -4,11 +4,9 @@ title: Qubes R3.2 release notes
permalink: /doc/releases/3.2/release-notes/ permalink: /doc/releases/3.2/release-notes/
--- ---
Qubes R3.2 release notes # Qubes R3.2 release notes
========================
New features since 3.1 ## New features since 3.1
----------------------
* Management Stack extended to support in-VM configuration - [documentation][salt-doc] * Management Stack extended to support in-VM configuration - [documentation][salt-doc]
* PV USB - [documentation][usb] * PV USB - [documentation][usb]
@ -21,8 +19,7 @@ New features since 3.1
You can get detailed description in [completed github issues][github-release-notes] You can get detailed description in [completed github issues][github-release-notes]
Known issues ## Known issues
------------
* [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2018/01/06/fedora-26-upgrade/). * [Fedora 23 reached EOL in December 2016](https://fedoraproject.org/wiki/End_of_life). There is a [manual procedure to upgrade your VMs](/news/2018/01/06/fedora-26-upgrade/).
@ -34,19 +31,16 @@ Known issues
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads ## Downloads
---------
See [Qubes Downloads](/downloads/). See [Qubes Downloads](/downloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/). After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/).
Upgrading ## Upgrading
---------
### From R3.1 ### From R3.1

6
developer/releases/3_2/schedule.md
View File

@ -15,9 +15,9 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
| -----------:| --------------------------------------- | | -----------:| --------------------------------------- |
| 18 Jun 2016 | 3.2-rc1 release | | 18 Jun 2016 | 3.2-rc1 release |
| 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | | 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 |
| <strike>16 Jul 2016</strike><br/>20 Jul 2016 | current-testing freeze before 3.2-rc2 | | ~~16 Jul 2016~~ <br/> 20 Jul 2016 | current-testing freeze before 3.2-rc2 |
| <strike>23 Jul 2016</strike><br/>27 Jul 2016 | 3.2-rc2 release | | ~~23 Jul 2016~~ <br/> 27 Jul 2016 | 3.2-rc2 release |
| <strike> 5 Aug 2016</strike><br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | | ~~5 Aug 2016~~ <br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 |
| 24 Aug 2016 | current-testing freeze before 3.2-rc3 | | 24 Aug 2016 | current-testing freeze before 3.2-rc3 |
| 31 Aug 2016 | 3.2-rc3 release | | 31 Aug 2016 | 3.2-rc3 release |
| 29 Sep 2016 | 3.2 release | | 29 Sep 2016 | 3.2 release |

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

@ -103,7 +103,6 @@ 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. [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. We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
[backup]: /doc/backup-restore/ [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 [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 [custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477

10
developer/releases/4_0/schedule.md
View File

@ -14,15 +14,15 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
| Date | Stage | | Date | Stage |
| -----------:| --------------------------------------- | | -----------:| --------------------------------------- |
| 31 Jul 2017 | 4.0-rc1 release | | 31 Jul 2017 | 4.0-rc1 release |
| <strike>28 Aug 2017</strike><br/><strike>11 Sep 2017</strike><br/><strike>9 Oct 2017</strike><br/>18 Oct 2017 | current-testing freeze before 4.0-rc2 | | ~~28 Aug 2017~~ <br/>~~11 Sep 2017~~ <br/>~~9 Oct 2017~~ <br/>18 Oct 2017 | current-testing freeze before 4.0-rc2 |
| <strike> 4 Sep 2017</strike><br/><strike>18 Sep 2017</strike><br/><strike>16 Oct 2017</strike><br/>23 Oct 2017 | 4.0-rc2 release | | ~~4 Sep 2017~~ <br/> ~~18 Sep 2017~~ <br/>~~16 Oct 2017~~ <br/>23 Oct 2017 | 4.0-rc2 release |
| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 | | 6 Nov 2017 | decide whether 4.0-rc2 is the final 4
| 20 Nov 2017 | current-testing freeze before 4.0-rc3 | | 20 Nov 2017 | current-testing freeze before 4.0-rc3 |
| 27 Nov 2017 | 4.0-rc3 release | | 27 Nov 2017 | 4.0-rc3 release |
| 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 | | 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 |
| 1 Jan 2018 | current-testing freeze before 4.0-rc4 | | 1 Jan 2018 | current-testing freeze before 4.0-rc4 |
| <strike>8 Jan 2018</strike><br/>31 Jan 2018 | 4.0-rc4 release | | ~~8 Jan 2018~~ <br/>31 Jan 2018 | 4.0-rc4 release |
| <strike>22 Jan 2018</strike><br/>14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 | | ~~22 Jan 2018~~ <br/>14 Feb 2018 | decide whether 4.0-rc4 is the final 4.0 |
| 27 Feb 2018 | current-testing freeze before 4.0-rc5 | | 27 Feb 2018 | current-testing freeze before 4.0-rc5 |
| 6 Mar 2018 | 4.0-rc5 release | | 6 Mar 2018 | 4.0-rc5 release |
| 20 Mar 2018 | decide whether 4.0-rc5 is the final 4.0 | | 20 Mar 2018 | decide whether 4.0-rc5 is the final 4.0 |

13
developer/releases/notes.md
View File

@ -7,10 +7,9 @@ permalink: /doc/releases/notes/
Release Notes Release Notes
============= =============
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) * [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) * [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) * [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) * [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) * [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) * [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)

9
developer/releases/schedules.md
View File

@ -7,8 +7,7 @@ permalink: /doc/releases/schedules/
Release Schedules Release Schedules
================= =================
* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) * [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) * [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)

3
developer/releases/todo.md
View File

@ -13,6 +13,7 @@ Release Checklist
On -rc1 On -rc1
------- -------
* write schedule * write schedule
* create package repositories (linux-yum, linux-deb) * create package repositories (linux-yum, linux-deb)
* update repository definition (core-agent-linux, installer-qubes-os/qubes-release) * update repository definition (core-agent-linux, installer-qubes-os/qubes-release)
@ -24,6 +25,7 @@ On -rc1
On subsequent -rc On subsequent -rc
----------------- -----------------
* push packages to `current` * push packages to `current`
* update release notes * update release notes
* build ISO and push to mirrors * build ISO and push to mirrors
@ -31,6 +33,7 @@ On subsequent -rc
On final release On final release
---------------- ----------------
* push packages to `current` * push packages to `current`
* finish release notes * finish release notes
* update InstallationInstructions * update InstallationInstructions

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

@ -148,23 +148,22 @@ to set the policy using current mechanism.
Volume properties: Volume properties:
- `pool` - `pool`
- `vid` - `vid`
- `size` - `size`
- `usage` - `usage`
- `rw` - `rw`
- `source` - `source`
- `save_on_stop` - `save_on_stop`
- `snap_on_start` - `snap_on_start`
- `revisions_to_keep` - `revisions_to_keep`
- `is_outdated` - `is_outdated`
Method `admin.vm.Stats` returns `vm-stats` events every `stats_interval` seconds, for every running VM. Parameters of `vm-stats` events: Method `admin.vm.Stats` returns `vm-stats` events every `stats_interval` seconds, for every running VM. Parameters of `vm-stats` events:
- `memory_kb` - memory usage in kB - `memory_kb` - memory usage in kB
- `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU - `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU
- `cpu_usage` - CPU usage in percents - `cpu_usage` - CPU usage in percents
## Returned messages ## Returned messages
@ -329,6 +328,7 @@ The changes are validated before saving, so that the policy cannot end up in an
invalid state (e.g. syntax error, missing include file). invalid state (e.g. syntax error, missing include file).
In addition, there is a mechanism to prevent concurrent modifications of the policy files: In addition, there is a mechanism to prevent concurrent modifications of the policy files:
- A `*.Get` call returns a file along with a *token* (currently implemented as - A `*.Get` call returns a file along with a *token* (currently implemented as
a hash of the file). a hash of the file).
- When calling `Replace` or `Remove`, you need to include the current token as - When calling `Replace` or `Remove`, you need to include the current token as

1
developer/services/qfileexchgd.md
View File

@ -54,4 +54,3 @@ In order to minimize attack surface presented by necessity to process virtual pe
2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM. 2. *qfilexchgd* sees that "send" argument=="disposable", and creates a new DisposableVM by calling */usr/lib/qubes/qubes\_restore*. It adds the new DisposableVM to qubesDB via qvm\_collection.add\_new\_disposablevm. Then it attaches the virtual pendrive (previously attached as `/dev/xvdg` at AppVM1) as `/dev/xvdh` in DisposableVM.
3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself. 3. In DisposableVM, *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key in xenstore, and instead processing the virtual pendrive as in the case of normal copy, treats it as DVM transaction (a request, because we run in DisposableVM). It retrieves the body of the file passed in `/dev/xvdh`, copies to /tmp, and runs *mime-open* utility to open appropriate executable to edit it. When *mime-open* returns, if the file was modified, it is sent back to AppVM1 (by writing "send AppVM1 SEQ" to `device/qpen` xenstore key). Then DisposableVM destroys itself.
4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it. 4. In AppVM1, a new `/dev/xvdh` appears (because DisposableVM has sent it). *qubes\_add\_pendrive\_script* sees non-zero `qubes_transaction_seq` key, and treats it as DVM transaction (a response, because we run in AppVM, not DisposableVM). It retrieves the filename from `/home/user/.dvm/SEQ`, and copies data from `/dev/xvdh` to it.

1
developer/services/qmemman.md
View File

@ -75,7 +75,6 @@ Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, th
4. wait BALOON\_DELAY (0.1s) 4. wait BALOON\_DELAY (0.1s)
5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error). 5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).
Notes Notes
----- -----

42
developer/services/qrexec-internals.md
View File

@ -32,6 +32,7 @@ These tools are not designed to be used by users directly.
One instance is required for every active domain. One instance is required for every active domain.
`qrexec-daemon` is responsible for both: `qrexec-daemon` is responsible for both:
- handling execution and service requests from **dom0** (source: `qrexec-client`); and - handling execution and service requests from **dom0** (source: `qrexec-client`); and
- handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). - handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`).
@ -39,9 +40,9 @@ Command line usage:
`qrexec-daemon domain-id domain-name [default user]` `qrexec-daemon domain-id domain-name [default user]`
* `domain-id`: Numeric Qubes ID assigned to the associated domain. - `domain-id`: Numeric Qubes ID assigned to the associated domain.
* `domain-name`: Associated domain name. - `domain-name`: Associated domain name.
* `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one. - `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one.
### qrexec-client ### qrexec-client
@ -51,11 +52,11 @@ Used to pass execution and service requests to `qrexec-daemon`.
Command line usage: Command line usage:
* `-d target-domain-name`: Specifies the target for the execution/service request. - `-d target-domain-name`: Specifies the target for the execution/service request.
* `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer. - `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer.
* `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received. - `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received.
* `-c <request-id,src-domain-name,src-domain-id>`: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. - `-c <request-id,src-domain-name,src-domain-id>`: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example.
* `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. - `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example.
## VM tools implementation ## VM tools implementation
@ -65,8 +66,9 @@ Command line usage:
One instance runs in each active domain. One instance runs in each active domain.
Responsible for: Responsible for:
* Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0.
* Executing associated `qrexec-daemon` execution/service requests. - Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0.
- Executing associated `qrexec-daemon` execution/service requests.
The `qrexec-agent` command takes no parameters. The `qrexec-agent` command takes no parameters.
@ -81,26 +83,30 @@ Command line usage:
`qrexec-client-vm target-domain-name service-name local-program [local program arguments]` `qrexec-client-vm target-domain-name service-name local-program [local program arguments]`
* `target-domain-name`: Target domain for the service request. Source is the current domain. - `target-domain-name`: Target domain for the service request. Source is the current domain.
* `service-name`: Requested service name. - `service-name`: Requested service name.
* `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint. - `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint.
## Qrexec protocol details ## Qrexec protocol details
The qrexec protocol is message-based. The qrexec protocol is message-based.
All messages share a common header followed by an optional data packet. All messages share a common header followed by an optional data packet.
/* uniform for all peers, data type depends on message type */ ```c
struct msg_header { /* uniform for all peers, data type depends on message type */
struct msg_header {
uint32_t type; /* message type */ uint32_t type; /* message type */
uint32_t len; /* data length */ uint32_t len; /* data length */
}; };
```
When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct: When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
struct peer_info { ```c
struct peer_info {
uint32_t version; /* qrexec protocol version */ uint32_t version; /* qrexec protocol version */
}; };
```
The client then should reply with its own `MSG_HELLO` and `peer_info`. The client then should reply with its own `MSG_HELLO` and `peer_info`.
The lower of two versions define protocol used for this connection. The lower of two versions define protocol used for this connection.

4
developer/services/qrexec-socket-services.md
View File

@ -20,11 +20,15 @@ If the file is a Unix socket, qrexec will try to connect to it.
Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`. Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`.
When running in a VM, this is: When running in a VM, this is:
```
<service_name> <source>\0 <service_name> <source>\0
```
When running in dom0, it is: When running in dom0, it is:
```
<service_name> <source> <target_type> <target>\0 <service_name> <source> <target_type> <target>\0
```
(The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`). (The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`).

72
developer/services/qrexec2.md
View File

@ -17,7 +17,6 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM)
services. It offers a mechanism to start programs in VMs, redirect their services. It offers a mechanism to start programs in VMs, redirect their
stdin/stdout, and a policy framework to control this all. stdin/stdout, and a policy framework to control this all.
## Qrexec basics ## ## Qrexec basics ##
During each domain creation a process named `qrexec-daemon` is started in During each domain creation a process named `qrexec-daemon` is started in
@ -31,7 +30,9 @@ the stdin/stdout/stderr from this remote process will be passed to the
E.g., to start a primitive shell in a VM type the following in Dom0 console: E.g., to start a primitive shell in a VM type the following in Dom0 console:
```shell_session
[user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d <vm name> user:bash [user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d <vm name> user:bash
```
The string before first semicolon specifies what user to run the command as. The string before first semicolon specifies what user to run the command as.
@ -55,7 +56,6 @@ There is a similar command line utility available inside Linux AppVMs (note
the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent
sections. sections.
## Qubes RPC services ## ## Qubes RPC services ##
Apart from simple Dom0-\>VM command executions, as discussed above, it is Apart from simple Dom0-\>VM command executions, as discussed above, it is
@ -90,7 +90,6 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout
of the server process with the corresponding stdin/stdout of the requesting of the server process with the corresponding stdin/stdout of the requesting
process in the requesting VM (see example Hello World service described below). process in the requesting VM (see example Hello World service described below).
## Qubes RPC administration ## ## Qubes RPC administration ##
Besides each VM needing to provide explicit programs to serve each supported Besides each VM needing to provide explicit programs to serve each supported
@ -100,6 +99,7 @@ In dom0, there is a bunch of files in `/etc/qubes-rpc/policy/` directory,
whose names describe the available RPC actions; their content is the RPC whose names describe the available RPC actions; their content is the RPC
access policy database. Some example of the default services in Qubes are: access policy database. Some example of the default services in Qubes are:
```
qubes.Filecopy qubes.Filecopy
qubes.OpenInVM qubes.OpenInVM
qubes.ReceiveUpdates qubes.ReceiveUpdates
@ -109,10 +109,13 @@ access policy database. Some example of the default services in Qubes are:
qubes.Gpg qubes.Gpg
qubes.NotifyUpdates qubes.NotifyUpdates
qubes.PdfConvert qubes.PdfConvert
```
These files contain lines with the following format: These files contain lines with the following format:
```
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to] srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
```
You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`, You can specify `srcvm` and `destvm` by name, or by one of `$anyvm`,
`$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the
@ -132,12 +135,13 @@ if still there is no policy file after prompting, the action is denied.
On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file
name of the program that will be invoked. name of the program that will be invoked.
### Requesting VM-VM (and VM-Dom0) services execution ### ### Requesting VM-VM (and VM-Dom0) services execution ###
In a src VM, one should invoke the qrexec client via the following command: In a src VM, one should invoke the qrexec client via the following command:
```
/usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments] /usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]
```
Note that only stdin/stdout is passed between RPC server and client -- Note that only stdin/stdout is passed between RPC server and client --
notably, no cmdline argument are passed. notably, no cmdline argument are passed.
@ -169,7 +173,9 @@ to the policy file, which will unconditionally allow further calls for given
In order to remove such authorization, issue this command from a Dom0 terminal In order to remove such authorization, issue this command from a Dom0 terminal
(example below for `qubes.Filecopy` service): (example below for `qubes.Filecopy` service):
```shell_session
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
```
and then remove any line(s) ending in "allow" (before the first `##` comment) and then remove any line(s) ending in "allow" (before the first `##` comment)
which are the "Yes to All" results. which are the "Yes to All" results.
@ -178,35 +184,44 @@ A user might also want to set their own policies in this section. This may
mostly serve to prevent the user from mistakenly copying files or text from mostly serve to prevent the user from mistakenly copying files or text from
a trusted to untrusted domain, or vice-versa. a trusted to untrusted domain, or vice-versa.
### Qubes RPC "Hello World" service ### ### Qubes RPC "Hello World" service ###
We will show the necessary files to create a simple RPC call that adds two We will show the necessary files to create a simple RPC call that adds two
integers on the target VM and returns back the result to the invoking VM. integers on the target VM and returns back the result to the invoking VM.
* Client code on source VM (`/usr/bin/our_test_add_client`) * Client code on source VM (`/usr/bin/our_test_add_client`)
```bash
#!/bin/sh #!/bin/sh
echo $1 $2 # pass data to rpc server echo $1 $2 # pass data to rpc server
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other rpc endpoint
```
* Server code on target VM (`/usr/bin/our_test_add_server`) * Server code on target VM (`/usr/bin/our_test_add_server`)
```bash
#!/bin/sh #!/bin/sh
read arg1 arg2 # read from stdin, which is received from the rpc client read arg1 arg2 # read from stdin, which is received from the rpc client
echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client echo $(($arg1+$arg2)) # print to stdout - so, pass to the rpc client
```
* Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`) * Policy file in dom0 (`/etc/qubes-rpc/policy/test.Add`)
```shell_session
$anyvm $anyvm ask $anyvm $anyvm ask
```
* Server path definition on target VM (`/etc/qubes-rpc/test.Add`) * Server path definition on target VM (`/etc/qubes-rpc/test.Add`)
```
/usr/bin/our_test_add_server /usr/bin/our_test_add_server
```
* To test this service, run the following in the source VM: * To test this service, run the following in the source VM:
```
/usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2 /usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2
```
and we should get "3" as answer, provided dom0 policy allows the call to pass and we should get "3" as answer, provided dom0 policy allows the call to pass
through, which would happen after we click "Yes" in the popup that should through, which would happen after we click "Yes" in the popup that should
@ -227,7 +242,6 @@ users/app developers are always free to run more high-level RPC protocols on
top of qrexec. Care should be taken, however, to consider potential attack top of qrexec. Care should be taken, however, to consider potential attack
surfaces that are exposed to untrusted or less trusted VMs in that case. surfaces that are exposed to untrusted or less trusted VMs in that case.
# Qubes RPC internals # # Qubes RPC internals #
(*This is about the implementation of qrexec v2. For the implementation of (*This is about the implementation of qrexec v2. For the implementation of
@ -235,52 +249,48 @@ qrexec v3, see [here](/doc/qrexec-internals/). Note that the user
API in v3 is backward compatible: qrexec apps written for Qubes R2 should API in v3 is backward compatible: qrexec apps written for Qubes R2 should
run without modification on Qubes R3.*) run without modification on Qubes R3.*)
## Dom0 tools implementation ## ## Dom0 tools implementation ##
Players: Players:
* `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a * `/usr/lib/qubes/qrexec-daemon`: started by mgmt stack (qubes.py) when a
VM is started. VM is started.
* `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the * `/usr/lib/qubes/qrexec-policy`: internal program used to evaluate the
policy file and making the 2nd half of the connection. policy file and making the 2nd half of the connection.
* `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the * `/usr/lib/qubes/qrexec-client`: raw command line tool that talks to the
daemon via unix socket (`/var/run/qubes/qrexec.XID`) daemon via unix socket (`/var/run/qubes/qrexec.XID`)
**Note:** None of the above tools are designed to be used by users. **Note:** None of the above tools are designed to be used by users.
## Linux VMs implementation ## ## Linux VMs implementation ##
Players: Players:
* `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon. * `/usr/lib/qubes/qrexec-agent`: started by VM bootup scripts, a daemon.
* `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program, * `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program,
as specified in VM's `/etc/qubes-rpc/qubes.XYZ`. as specified in VM's `/etc/qubes-rpc/qubes.XYZ`.
* `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to * `/usr/lib/qubes/qrexec-client-vm`: raw command line tool that talks to
the agent. the agent.
**Note:** None of the above tools are designed to be used by **Note:** None of the above tools are designed to be used by
users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
## Windows VMs implementation ## ## Windows VMs implementation ##
`%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things `%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
Lab\Qubes OS Windows Tools` by default). Lab\Qubes OS Windows Tools` by default).
* `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible * `%QUBES_DIR%\bin\qrexec-agent.exe`: runs as a system service. Responsible
both for raw command execution and interpreting RPC service requests. both for raw command execution and interpreting RPC service requests.
* `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain * `%QUBES_DIR%\qubes-rpc`: directory with `qubes.XYZ` files that contain
commands for executing RPC services. Binaries for the services are contained commands for executing RPC services. Binaries for the services are contained
in `%QUBES_DIR%\qubes-rpc-services`. in `%QUBES_DIR%\qubes-rpc-services`.
* `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to * `%QUBES_DIR%\bin\qrexec-client-vm`: raw command line tool that talks to
the agent. the agent.
**Note:** None of the above tools are designed to be used by **Note:** None of the above tools are designed to be used by
users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
## All the pieces together at work ## ## All the pieces together at work ##
**Note:** This section is not needed to use qrexec for writing Qubes **Note:** This section is not needed to use qrexec for writing Qubes
@ -298,20 +308,20 @@ vchan connections.
When a user in a source VM executes `qrexec-client-vm` utility, the following When a user in a source VM executes `qrexec-client-vm` utility, the following
steps are taken: steps are taken:
* `qrexec-client-vm` connects to `qrexec-agent`'s * `qrexec-client-vm` connects to `qrexec-agent`'s
`/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from `/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from
each of them, which is the fd number of the accepted socket in agent. These each of them, which is the fd number of the accepted socket in agent. These
3 integers, in text, concatenated, form "connection identifier" (CID) 3 integers, in text, concatenated, form "connection identifier" (CID)
* `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob, * `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob,
consisting of target vmname, rpc action, and CID consisting of target vmname, rpc action, and CID
* `qrexec-client-vm` executes the rpc client, passing the above mentioned * `qrexec-client-vm` executes the rpc client, passing the above mentioned
unix sockets as process stdin/stdout, and optionally stderr (if the unix sockets as process stdin/stdout, and optionally stderr (if the
`PASS_LOCAL_STDERR` env variable is set) `PASS_LOCAL_STDERR` env variable is set)
* `qrexec-agent` passes the blob to `qrexec-daemon`, via * `qrexec-agent` passes the blob to `qrexec-daemon`, via
`MSG_AGENT_TO_SERVER_TRIGGER_CONNECT_EXISTING` message over vchan `MSG_AGENT_TO_SERVER_TRIGGER_CONNECT_EXISTING` message over vchan
* `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target * `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target
vmname, rpc action, and CID as cmdline arguments vmname, rpc action, and CID as cmdline arguments
* `qrexec-policy` evaluates the policy file. If successful, creates a pair of * `qrexec-policy` evaluates the policy file. If successful, creates a pair of
`qrexec-client` processes, whose stdin/stdout are cross-connected. `qrexec-client` processes, whose stdin/stdout are cross-connected.
* The first `qrexec-client` connects to the src VM, using the `-c ClientID` * The first `qrexec-client` connects to the src VM, using the `-c ClientID`
parameter, which results in not creating a new process, but connecting to parameter, which results in not creating a new process, but connecting to
@ -321,7 +331,7 @@ steps are taken:
`qubes-rpc-multiplexer` command there with the rpc action as the cmdline `qubes-rpc-multiplexer` command there with the rpc action as the cmdline
argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server
on the target. on the target.
* In the above step, if the target VM is `$dispvm`, the DispVM is created * In the above step, if the target VM is `$dispvm`, the DispVM is created
via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client` via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client`
process to exit, and then destroys the DispVM. process to exit, and then destroys the DispVM.

20
developer/system/architecture.md
View File

@ -18,7 +18,6 @@ Qubes implements a Security by Isolation approach. To do this, Qubes utilizes vi
Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course. Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course.
Key Architecture features Key Architecture features
------------------------- -------------------------
@ -36,7 +35,6 @@ Key Architecture features
Please note that this document is for historical interest only. Please note that this document is for historical interest only.
For the latest information, please see the rest of the [System Documentation](/doc/#system).) For the latest information, please see the rest of the [System Documentation](/doc/#system).)
Qubes Core Stack Qubes Core Stack
---------------- ----------------
@ -45,26 +43,26 @@ the glue that connects all the other components together, and which allows users
and admins to interact with and configure the system. The other components of and admins to interact with and configure the system. The other components of
the Qubes system include: the Qubes system include:
- VM-located core agents (implementing e.g. qrexec endpoints used by various - VM-located core agents (implementing e.g. qrexec endpoints used by various
Qubes services) Qubes services)
- VM-customizations (making the VMs lightweight and working well with seamless - VM-customizations (making the VMs lightweight and working well with seamless
GUI virtualization) GUI virtualization)
- Qubes GUI virtualization (the protocol, VM-located agents, and daemons - Qubes GUI virtualization (the protocol, VM-located agents, and daemons
located in the GUI domain which, for now, happens to be the same as dom0), located in the GUI domain which, for now, happens to be the same as dom0),
- GUI domain customizations (Desktop Environment customizations, decoration - GUI domain customizations (Desktop Environment customizations, decoration
coloring plugin, etc) coloring plugin, etc)
- The AdminVM distribution (various customizations, special services, such as - The AdminVM distribution (various customizations, special services, such as
for receiving and verifying updates, in the future: custom distro) for receiving and verifying updates, in the future: custom distro)
- The Xen hypervisor (with a bunch of customization patches, occasional - The Xen hypervisor (with a bunch of customization patches, occasional
hardening) or - in the future - some other virtualising or containerizing hardening) or - in the future - some other virtualising or containerizing
software or technology software or technology
- Multiple "Qubes Apps" (various services built on top of Qubes qrexec - Multiple "Qubes Apps" (various services built on top of Qubes qrexec
infrastructure, such as: trusted PDF and Image converters, Split GPG, safe infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
USB proxies for HID devices, USB proxy for offering USB devices (exposed via USB proxies for HID devices, USB proxy for offering USB devices (exposed via
qvm-usb), Yubikey support, USB Armory support, etc) qvm-usb), Yubikey support, USB Armory support, etc)
- Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used - Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used
to create actual VMs, i.e. provide the root filesystem to the VMs to create actual VMs, i.e. provide the root filesystem to the VMs
- Salt Stack integration - Salt Stack integration
And all these components are "glued together" by the Qubes Core Stack. And all these components are "glued together" by the Qubes Core Stack.

25
developer/system/audio.md
View File

@ -10,8 +10,8 @@ Audio Virtualization
VMs on Qubes OS have access to virtualized audio through the PulseAudio module. VMs on Qubes OS have access to virtualized audio through the PulseAudio module.
It consists of two parts: It consists of two parts:
- `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon) - `pacat-simple-vchan` running in a dom0/Audio VM (standalone application, one per VM, connected to the PulseAudio daemon)
- `module-vchan-sink` running in a VM (loaded into the PulseAudio process) - `module-vchan-sink` running in a VM (loaded into the PulseAudio process)
Protocol Protocol
-------- --------
@ -33,10 +33,10 @@ Each such notification is a 4-byte number in little-endian format.
List of defined codes: List of defined codes:
- `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM. - `0x00010001` -- VM wants to receive audio input (some process is listening); prior to this message, `pacat-simple-vchan` will not send any audio samples to the VM.
- `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM. - `0x00010000` -- VM does not want to receive audio input (no process is listening anymore); after this message, `pacat-simple-vchan` will not send any audio samples to the VM.
- `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays). - `0x00020000` -- VM does not want to send audio output; informational for dom0, to avoid buffer under runs (may affect PulseAudio calculated delays).
- `0x00020001` -- VM does want to send audio output. - `0x00020001` -- VM does want to send audio output.
pacat-simple-vchan pacat-simple-vchan
------------------ ------------------
@ -52,20 +52,19 @@ It needs to be both requested by the VM part and explicitly enabled in `pacat-si
The mechanism to do this differs between Qubes versions. The mechanism to do this differs between Qubes versions.
In Qubes before R4.1, `pacat-simple-vchan` is controlled over system D-Bus: In Qubes before R4.1, `pacat-simple-vchan` is controlled over system D-Bus:
- destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name) - destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name)
- object path: `/org/qubesos/audio` - object path: `/org/qubesos/audio`
- interface: `org.qubesos.Audio` - interface: `org.qubesos.Audio`
- property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface) - property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface)
In Qubes R4.1 and later, `pacat-simple-vchan` is controlled over a UNIX socket at `/var/run/qubes/audio-control.VMNAME` (where `VMNAME` is the VM's name). In Qubes R4.1 and later, `pacat-simple-vchan` is controlled over a UNIX socket at `/var/run/qubes/audio-control.VMNAME` (where `VMNAME` is the VM's name).
Supported commands: Supported commands:
- `audio-input 1\n` - enable audio input - `audio-input 1\n` - enable audio input
- `audio-input 0\n` - disable audio input - `audio-input 0\n` - disable audio input
These commands can be sent using the `qubes.AudioInputEnable+VMNAME` and `qubes.AudioInputDisable+VMNAME` qrexec services, respectively. These commands can be sent using the `qubes.AudioInputEnable+VMNAME` and `qubes.AudioInputDisable+VMNAME` qrexec services, respectively.
The current status is written into QubesDB at `/audio-input/VMNAME` (where `VMNAME` is the VM's name) with either `1` or `0` values. The current status is written into QubesDB at `/audio-input/VMNAME` (where `VMNAME` is the VM's name) with either `1` or `0` values.
The lack of a key means that the `pacat-simple-vchan` for a given VM is not running. The lack of a key means that the `pacat-simple-vchan` for a given VM is not running.
In either version, it is exposed to the user as device of class `mic`, which can be attached to a VM (for example, using the `qvm-device mic` command). In either version, it is exposed to the user as device of class `mic`, which can be attached to a VM (for example, using the `qvm-device mic` command).

8
developer/system/gui.md
View File

@ -115,7 +115,7 @@ Window manager hints and flags are described in the [Extended Window Manager Hin
Each message starts with the following header: Each message starts with the following header:
~~~ ```c
struct msghdr { struct msghdr {
uint32_t type; uint32_t type;
uint32_t window; uint32_t window;
@ -126,7 +126,7 @@ struct msghdr {
* whatever it wants! */ * whatever it wants! */
uint32_t untrusted_len; uint32_t untrusted_len;
}; };
~~~ ```
This header is followed by message-specific data: This header is followed by message-specific data:
@ -279,12 +279,12 @@ Proper handling of the below messages is NOT security-critical.
Each message starts with the following header Each message starts with the following header
~~~ ```c
struct msghdr { struct msghdr {
uint32_t type; uint32_t type;
uint32_t window; uint32_t window;
}; };
~~~ ```
The header is followed by message-specific data: The header is followed by message-specific data:

19
developer/system/networking.md
View File

@ -9,18 +9,15 @@ redirect_from:
- /wiki/QubesNet/ - /wiki/QubesNet/
--- ---
VM network in Qubes # VM network in Qubes
===================
Overall description ## Overall description
-------------------
In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices and NAT is applied at each network hop. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used. In Qubes, the standard Xen networking is used, based on backend driver in the driver domain and frontend drivers in VMs. In order to eliminate layer 2 attacks originating from a compromised VM, routed networking is used instead of the default bridging of `vif` devices and NAT is applied at each network hop. The default *vif-route* script had some deficiencies (requires `eth0` device to be up, and sets some redundant iptables rules), therefore the custom *vif-route-qubes* script is used.
The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via QubesDB to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs. The IP address of `eth0` interface in AppVM, as well as two IP addresses to be used as nameservers (`DNS1` and `DNS2`), are passed via QubesDB to AppVM during its boot (thus, there is no need for DHCP daemon in the network driver domain). `DNS1` and `DNS2` are private addresses; whenever an interface is brought up in the network driver domain, the */usr/lib/qubes/qubes\_setup\_dnat\_to\_ns* script sets up the DNAT iptables rules translating `DNS1` and `DNS2` to the newly learned real dns servers. This way AppVM networking configuration does not need to be changed when configuration in the network driver domain changes (e.g. user switches to a different WLAN). Moreover, in the network driver domain, there is no DNS server either, and consequently there are no ports open to the VMs.
Routing tables examples ## Routing tables examples
-----------------------
VM routing table is simple: VM routing table is simple:
@ -40,18 +37,21 @@ Network driver domain routing table is a bit longer:
|192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0| |192.168.0.0|0.0.0.0|255.255.255.0|U|1|0|0|eth0|
|0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0| |0.0.0.0|192.168.0.1|0.0.0.0|UG|0|0|0|eth0|
IPv6 ## IPv6
----
Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed. Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed.
The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled. The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled.
To enable the `ipv6` feature use `qvm-features` tool and set the value to `1`. For example to enable it on `sys-net`, execute in dom0: To enable the `ipv6` feature use `qvm-features` tool and set the value to `1`. For example to enable it on `sys-net`, execute in dom0:
```
qvm-features sys-net ipv6 1 qvm-features sys-net ipv6 1
```
It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting `ipv6` feature to empty value: It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting `ipv6` feature to empty value:
```
qvm-features ipv4-only-qube ipv6 '' qvm-features ipv4-only-qube ipv6 ''
```
This configuration is presented below - green qubes have IPv6 access, red one does not. This configuration is presented below - green qubes have IPv6 access, red one does not.
@ -64,8 +64,7 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs
Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later. Besides enabling IPv6 forwarding, standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only `qvm-firewall` command support adding IPv6 rules, GUI firewall editor will have this ability later.
### Limitations ### ### Limitations
Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability. Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks. But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.

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

@ -21,20 +21,18 @@ The size of the current TCB is on the order order of hundreds of thousands of li
For more information, see [Qubes Security Goals]. For more information, see [Qubes Security Goals].
Security-critical Qubes-specific Components Security-critical Qubes-specific Components
------------------------------------------- -------------------------------------------
The following code components are security-critical in Qubes OS: The following code components are security-critical in Qubes OS:
- Dom0-side of the libvchan library - Dom0-side of the libvchan library
- Dom0-side of the GUI virtualization code (`qubes-guid`) - Dom0-side of the GUI virtualization code (`qubes-guid`)
- Dom0-side of the sound virtualization code (`pacat-simple-vchan`) - Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
- Dom0-side in qrexec-related code (`qrexec_daemon`) - Dom0-side in qrexec-related code (`qrexec_daemon`)
- VM memory manager (`qmemman`) that runs in Dom0 - VM memory manager (`qmemman`) that runs in Dom0
- Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus` - Select Qubes RPC servers that run in Dom0: `qubes.ReceiveUpdates` and `qubes.SyncAppMenus`
- The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them) - The `qubes.Filecopy` RPC server that runs in a VM (critical because it could allow one VM to compromise another if the user allows a file copy operation to be performed between them)
Security-critical Third-party Components Security-critical Third-party Components
---------------------------------------- ----------------------------------------
@ -42,26 +40,24 @@ Security-critical Third-party Components
We did not create these components, but Qubes OS relies on them. We did not create these components, but Qubes OS relies on them.
At the current stage of the project, we cannot afford to spend the time to thoroughly review and audit them, so we more or less "blindly" trust that they are secure. At the current stage of the project, we cannot afford to spend the time to thoroughly review and audit them, so we more or less "blindly" trust that they are secure.
- The Xen hypervisor - The Xen hypervisor
- Xen's xenstore backend running in Dom0 - Xen's xenstore backend running in Dom0
- Xen's block backend running in Dom0's kernel - Xen's block backend running in Dom0's kernel
- The RPM program used in Dom0 for verifying signatures on dom0 updates - The RPM program used in Dom0 for verifying signatures on dom0 updates
- Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs - Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
Attacks on Networking Components Attacks on Networking Components
-------------------------------- --------------------------------
Here are two examples of networking components that an adversary might seek to attack (or in which to exploit a vulnerability as part of an attack): Here are two examples of networking components that an adversary might seek to attack (or in which to exploit a vulnerability as part of an attack):
- Xen network PV frontends - Xen network PV frontends
- VMs' core networking stacks (core TCP/IP code) - VMs' core networking stacks (core TCP/IP code)
Hypothetically, an adversary could compromise a NetVM, `sys-net-1`, and try to use it to attack the VMs connected to that NetVM. Hypothetically, an adversary could compromise a NetVM, `sys-net-1`, and try to use it to attack the VMs connected to that NetVM.
However, Qubes allows for the existence of more than one NetVM, so the adversary would not be able to use `sys-net-1` in order to attack VMs connected to a *different* NetVM, `sys-net-2` without also compromising `sys-net-2`. However, Qubes allows for the existence of more than one NetVM, so the adversary would not be able to use `sys-net-1` in order to attack VMs connected to a *different* NetVM, `sys-net-2` without also compromising `sys-net-2`.
In addition, the adversary would not be able to use `sys-net-1` (or, for that matter, `sys-net-2`) to attack VMs that have networking disabled (i.e., VMs that are not connected to any NetVM). In addition, the adversary would not be able to use `sys-net-1` (or, for that matter, `sys-net-2`) to attack VMs that have networking disabled (i.e., VMs that are not connected to any NetVM).
Buggy Code vs. Backdoored Code Buggy Code vs. Backdoored Code
------------------------------ ------------------------------
@ -74,8 +70,6 @@ This means that we must trust at least some of the vendors that supply the code
In practice, we trust the software provided by the [Fedora Project]. In practice, we trust the software provided by the [Fedora Project].
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. 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/ [Qubes Security Goals]: /security/goals/
[Fedora Project]: https://getfedora.org/ [Fedora Project]: https://getfedora.org/
[Understanding and Preventing Data Leaks]: /doc/data-leaks/ [Understanding and Preventing Data Leaks]: /doc/data-leaks/

1
developer/system/storage-pools.md
View File

@ -32,7 +32,6 @@ When installed, the system has, as you can see from the contents of
default pool is special in R3.2. It will add `dir_path=/var/lib/qubes` default pool is special in R3.2. It will add `dir_path=/var/lib/qubes`
configuration value from `defaults[pool_config]`, if not overwritten. configuration value from `defaults[pool_config]`, if not overwritten.
Currently the only supported driver out of the box is `xen`. The benefit of Currently the only supported driver out of the box is `xen`. The benefit of
pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2 pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2
is that you can store your domains in multiple places. is that you can store your domains in multiple places.

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

@ -8,8 +8,7 @@ redirect_from:
- /wiki/TemplateImplementation/ - /wiki/TemplateImplementation/
--- ---
Overview of VM block devices # Overview of VM block devices
============================
Every VM has 4 block devices connected: Every VM has 4 block devices connected:
@ -18,8 +17,7 @@ Every VM has 4 block devices connected:
- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below) - **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware - **xvdd** – modules.img – kernel modules and firmware
private.img (xvdb) ## private.img (xvdb)
------------------
This is mounted as /rw and here is placed all VM private data. This includes: This is mounted as /rw and here is placed all VM private data. This includes:
@ -29,8 +27,7 @@ This is mounted as /rw and here is placed all VM private data. This includes:
**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are copied to the child TemplateBasedVM's `/home`. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM. **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are copied to the child TemplateBasedVM's `/home`. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
modules.img (xvdd) ## modules.img (xvdd)
------------------
As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files: As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
@ -42,8 +39,7 @@ Normally kernel "package" is common for many VMs (can be set using qvm-prefs). O
There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom". There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
Qubes TemplateVM implementation # Qubes TemplateVM implementation
===============================
TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs: TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
@ -54,8 +50,7 @@ There are two layers of the device-mapper snapshot device; the first one enables
![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png) ![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png)
Snapshot device in Dom0 ## Snapshot device in Dom0
-----------------------
This device consists of: This device consists of:
@ -90,8 +85,7 @@ Steps performed by **qvm-revert-template-changes**:
6. Cleanup snapshot device (if nobody uses it at the moment). 6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). 7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
Snapshot device in AppVM ## Snapshot device in AppVM
------------------------
Root device is exposed to AppVM in read-only mode. AppVM can write only in: Root device is exposed to AppVM in read-only mode. AppVM can write only in:
@ -105,8 +99,7 @@ volatile.img is divided into two partitions:
Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart. Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
StandaloneVM ## StandaloneVM
------------
Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*. Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.

2
introduction/contributing.md
View File

@ -57,7 +57,6 @@ 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 details, we'll add you to our [Community-Developed Feature Tracker]. We'll then
be grateful to [receive your patch][patch]. be grateful to [receive your patch][patch].
[source code]: /doc/source-code/ [source code]: /doc/source-code/
[Report security issues]: /security/ [Report security issues]: /security/
[patch]: /doc/source-code/#how-to-send-patches [patch]: /doc/source-code/#how-to-send-patches
@ -79,4 +78,3 @@ be grateful to [receive your patch][patch].
[qubes-devel]: /support/#qubes-devel [qubes-devel]: /support/#qubes-devel
[Community-Developed Feature Tracker]: /qubes-issues/ [Community-Developed Feature Tracker]: /qubes-issues/
[Qubes download mirror]: /downloads/mirrors/ [Qubes download mirror]: /downloads/mirrors/

51
introduction/faq.md
View File

@ -102,7 +102,6 @@ Booting your computer from a live CD (or DVD) when you need to perform sensitive
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] 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. 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? ### How does Qubes OS compare to running VMs in a conventional OS?
Not all virtual machine software is equal when it comes to security. Not all virtual machine software is equal when it comes to security.
@ -121,7 +120,6 @@ Qubes makes it so that multiple VMs running under a Type 1 hypervisor can be sec
For example, it puts all of your application windows on the same desktop with special colored borders indicating the trust levels of their respective VMs. For example, it puts all of your application windows on the same desktop with special colored borders indicating the trust levels of their respective VMs.
It also allows for things like secure copy/paste operations between VMs, securely copying and transferring files between VMs, and secure networking between VMs and the Internet. It also allows for things like secure copy/paste operations between VMs, securely copying and transferring files between VMs, and secure networking between VMs and the Internet.
### How does Qubes OS compare to using a separate physical machine? ### How does Qubes OS compare to using a separate physical machine?
Using a separate physical computer for sensitive activities can certainly be more secure than using one computer with a conventional OS for everything, but there are still risks to consider. Using a separate physical computer for sensitive activities can certainly be more secure than using one computer with a conventional OS for everything, but there are still risks to consider.
@ -131,23 +129,22 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
<i class="fa fa-check"></i> <strong>Pros</strong> <i class="fa fa-check"></i> <strong>Pros</strong>
</div> </div>
* Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.) - Physical separation doesn't rely on a hypervisor. (It's very unlikely that an attacker will break out of Qubes' hypervisor, but if one were to manage to do so, one could potentially gain control over the entire system.)
* Physical separation can be a natural complement to physical security. - Physical separation can be a natural complement to physical security.
(For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.) (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
<div class="focus"> <div class="focus">
<i class="fa fa-times"></i> <strong>Cons</strong> <i class="fa fa-times"></i> <strong>Cons</strong>
</div> </div>
* Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need. - Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
* There's generally no secure way to transfer data between physically separate computers running conventional OSes. - There's generally no secure way to transfer data between physically separate computers running conventional OSes.
(Qubes has a secure inter-VM file transfer system to handle this.) (Qubes has a secure inter-VM file transfer system to handle this.)
* Physically separate computers running conventional OSes are still independently vulnerable to most conventional attacks due to their monolithic nature. - 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. - 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][paper-compart].)
### What is the main concept behind Qubes? ### What is the main concept behind Qubes?
To build security on the "Security by Compartmentalization (or Isolation)" principle. To build security on the "Security by Compartmentalization (or Isolation)" principle.
@ -253,6 +250,7 @@ Please refer to [this page].
### Why is dom0 so old? ### Why is dom0 so old?
Please see: Please see:
- [Installing and updating software in dom0] - [Installing and updating software in dom0]
- [Note on dom0 and EOL] - [Note on dom0 and EOL]
@ -315,7 +313,6 @@ So, if feature X isn't enabled, it's most likely for one of three reasons:
If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]! If it seems like a feature that we can and should enable, please [let us know][reporting-bugs]!
## Users ## Users
### Can I watch YouTube videos in qubes? ### Can I watch YouTube videos in qubes?
@ -346,7 +343,6 @@ See [here] for details.
However, in Qubes 4.x we will be implementing management functionality. However, in Qubes 4.x we will be implementing management functionality.
See [Admin API] and [Core Stack] for more details. See [Admin API] and [Core Stack] for more details.
### What are the system requirements for Qubes OS? ### What are the system requirements for Qubes OS?
See the [system requirements]. See the [system requirements].
@ -437,7 +433,6 @@ You shouldn't do that, because it poses a security risk for your Qubes OS instal
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].
It begins with an explanation of the risks with such a setup. It begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running? ### Which version of Qubes am I running?
See [here][version]. See [here][version].
@ -473,16 +468,18 @@ This is an intended feature.
A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there. A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there.
In order to re-enable the device in dom0, either: In order to re-enable the device in dom0, either:
* Reboot the physical machine. - Reboot the physical machine.
or or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`: - Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
```
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias` MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1` MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
```
See also [here][assign_devices]. See also [here][assign_devices].
@ -510,7 +507,9 @@ For Debian:
1. (Recommended) Clone an existing Debian TemplateVM 1. (Recommended) Clone an existing Debian TemplateVM
2. Install VLC in that TemplateVM: 2. Install VLC in that TemplateVM:
```bash_session
$ sudo apt install vlc $ sudo apt install vlc
```
3. Use VLC to play your video files. 3. Use VLC to play your video files.
@ -520,7 +519,9 @@ For Fedora:
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM][Enable RPMFusion]. 2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM][Enable RPMFusion].
3. Install VLC in that TemplateVM: 3. Install VLC in that TemplateVM:
```bash_session
$ sudo dnf install vlc $ sudo dnf install vlc
```
4. Use VLC to play your video files. 4. Use VLC to play your video files.
@ -585,7 +586,9 @@ I see a screen popup with SeaBios and 4 lines, last one being `Probing EDD (edd=
From a `dom0` prompt, enter: From a `dom0` prompt, enter:
qvm-prefs <HVMname> kernel "" ```
qvm-prefs <HVMname> kernel ""
```
### When I try to install a TemplateVM, it says no match is found. ### When I try to install a TemplateVM, it says no match is found.
@ -603,6 +606,7 @@ The full message looks like:
[FAILED] Failed to start Load Kernel Modules. [FAILED] Failed to start Load Kernel Modules.
See 'systemctl status systemd-modules-load.service' for details. See 'systemctl status systemd-modules-load.service' for details.
``` ```
This is cosmetic only, and can safely be ignored. This is cosmetic only, and can safely be ignored.
### Why is Qubes so slow and how can I make it faster? ### Why is Qubes so slow and how can I make it faster?
@ -622,7 +626,6 @@ There is no particular configuration that will be ideal for everyone (despite ho
Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference. Please don't ask for your favorite program to be installed by default or for some setting that obviously varies by user preference to be changed so that it matches *your* preference.
This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences. This is an incredibly selfish attitude that demonstrates a complete lack of consideration for the thousands of other Qubes users who don't happen to share your preferences.
## Developers ## Developers
### Are there restrictions on the software that the Qubes developers are willing to use? ### Are there restrictions on the software that the Qubes developers are willing to use?
@ -631,10 +634,10 @@ Yes.
In general, the Qubes developers will not use a piece of software unless there is an *easy* way to verify both its **integrity** and **authenticity**, preferably via PGP signatures (see [Verifying Signatures](/security/verifying-signatures/)). In general, the Qubes developers will not use a piece of software unless there is an *easy* way to verify both its **integrity** and **authenticity**, preferably via PGP signatures (see [Verifying Signatures](/security/verifying-signatures/)).
Specifically: Specifically:
* If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust. - If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
* If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)). - If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)).
* If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation). - If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
* If the software must be built from source, the source code and any builders must be signed. - If the software must be built from source, the source code and any builders must be signed.
(Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.) (Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.)
### Why does dom0 need to be 64-bit? ### Why does dom0 need to be 64-bit?
@ -667,11 +670,11 @@ See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issu
The policy is there mostly to ease maintenance, on several levels: The policy is there mostly to ease maintenance, on several levels:
* Less modifications means easier migration to new upstream distribution - Less modifications means easier migration to new upstream distribution
releases. releases.
* The upstream documentation matches the distribution running in the Qubes VM. - The upstream documentation matches the distribution running in the Qubes VM.
* We're less likely to introduce Qubes-specific issues. - We're less likely to introduce Qubes-specific issues.
* Each officially supported distribution (ideally) should offer the same set of - Each officially supported distribution (ideally) should offer the same set of
Qubes-specific features - a change in one supported distribution should be Qubes-specific features - a change in one supported distribution should be
followed also in others, including new future distributions. followed also in others, including new future distributions.

3
introduction/intro.html
View File

@ -11,6 +11,7 @@ redirect_from:
--- ---
<h2>What is Qubes OS?</h2> <h2>What is Qubes OS?</h2>
<a id = "what-is-qubes-os"></a>
<div class="row"> <div class="row">
<div class="col-lg-12 col-md-12"> <div class="col-lg-12 col-md-12">
@ -159,6 +160,7 @@ redirect_from:
<h2 class="more-bottom">Why Qubes OS?</h2> <h2 class="more-bottom">Why Qubes OS?</h2>
<a id = "why-qubes-os"></a>
<h3>Physical isolation is a given safeguard that the digital world lacks</h3> <h3>Physical isolation is a given safeguard that the digital world lacks</h3>
@ -336,4 +338,3 @@ redirect_from:
</li> </li>
</ul> </ul>
</p> </p>

2
introduction/reporting-bugs.md
View File

@ -123,7 +123,6 @@ If the issue is closed without one of these specific resolutions, then it means,
- [Package Contributions] - [Package Contributions]
- [Documentation Guidelines] - [Documentation Guidelines]
[qubes-issues-all]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue [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-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 [qubes-issues-labels]: https://github.com/QubesOS/qubes-issues/labels
@ -146,4 +145,3 @@ If the issue is closed without one of these specific resolutions, then it means,
[Package Contributions]: /doc/package-contributions/ [Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/ [Documentation Guidelines]: /doc/doc-guidelines/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

20
introduction/statistics.md
View File

@ -12,8 +12,7 @@ redirect_from:
</a> </a>
</div> </div>
FAQ ## FAQ
---
### How often is this graph updated? ### How often is this graph updated?
@ -39,10 +38,11 @@ tor_users = tor_requests * (plain_users / plain_requests)
``` ```
Where: Where:
- `tor_users` is the estimated number of Qubes users who download updates via Tor each month.
- `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month. - `tor_users` is the estimated number of Qubes users who download updates via Tor each month.
- `plain_users` is the number of unique clearnet IPv4 addresses that connect to the Qubes update servers each month. - `tor_requests` is the total number of requests the Qubes update servers receive from Tor exit nodes each month.
- `plain_requests` is the total number of requests the Qubes update servers receive from clearnet IPv4 addresses each month. - `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] 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. 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.
@ -51,9 +51,9 @@ For this purpose, we count an IP address as belonging to a Tor exit node if ther
We collect: We collect:
- The IPv4 addresses that connect to the Qubes update servers - The IPv4 addresses that connect to the Qubes update servers
- The number of requests from each IPv4 address - The number of requests from each IPv4 address
- Standard server access and error logs - Standard server access and error logs
We do not collect any other kinds of data about Qubes users. We do not collect any other kinds of data about Qubes users.
@ -64,9 +64,7 @@ The raw data is available [here][raw-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. 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][source-code].
[tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed [tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed
[TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel [TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel
[raw-data]: https://tools.qubes-os.org/counter/stats.json [raw-data]: https://tools.qubes-os.org/counter/stats.json
[source-code]: https://github.com/woju/qubes-stats [source-code]: https://github.com/woju/qubes-stats

118
introduction/support.md
View File

@ -13,7 +13,7 @@ redirect_from:
- /wiki/QubesLists/ - /wiki/QubesLists/
--- ---
# Help, Support, Mailing Lists, and Forum # # Help, Support, Mailing Lists, and Forum
Help and support for Qubes OS is available from the [documentation], the Help and support for Qubes OS is available from the [documentation], the
[mailing lists], and our [forum] which are explained below. The Qubes OS [mailing lists], and our [forum] which are explained below. The Qubes OS
@ -24,8 +24,7 @@ see the [issue tracker]. These issues are constantly being updated and may
contain workarounds for problems that you're experiencing, so it's worth contain workarounds for problems that you're experiencing, so it's worth
[searching the issue tracker] as a first step. [searching the issue tracker] as a first step.
## Staying safe
## Staying safe ##
The Qubes mailing lists and forum are open to the public. The contents are The Qubes mailing lists and forum are open to the public. The contents are
crawled by search engines and archived by third-party services outside of our crawled by search engines and archived by third-party services outside of our
@ -61,8 +60,7 @@ 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] that these
came from the same keyholder. came from the same keyholder.
## Discussion guidelines
## Discussion guidelines ##
Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our 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 [forum], all of which are explained below. Most questions should be directed to
@ -81,7 +79,7 @@ and knowledgeable people who enjoy corresponding on these lists. The vast
majority of them will be happy to help you if you follow these simple majority of them will be happy to help you if you follow these simple
guidelines. guidelines.
### Be polite and respectful ### ### Be polite and respectful
Remember, no one here is under any obligation Remember, no one here is under any obligation
to reply to you. Think about your readers. Most of them are coming home after to reply to you. Think about your readers. Most of them are coming home after
@ -89,14 +87,14 @@ a long, hard day at work. The last thing they need is someone's temper
tantrum. If you are rude and disrespectful, you are very tantrum. If you are rude and disrespectful, you are very
likely to be ignored. likely to be ignored.
### Be concise ### ### Be concise
Include only essential information. Most of your readers lead Include only essential information. Most of your readers lead
busy lives and have precious little time. We *want* to spend some of that busy lives and have precious little time. We *want* to spend some of that
time helping you, if we can. But if you ramble, it will be easier to skip time helping you, if we can. But if you ramble, it will be easier to skip
over you and help someone else who gets right to the point. over you and help someone else who gets right to the point.
### Help us help you ### ### Help us help you
Tell us what you've already tried, and which Tell us what you've already tried, and which
documentation pages you've already read. Put yourself in your readers' shoes. documentation pages you've already read. Put yourself in your readers' shoes.
@ -106,7 +104,7 @@ provide your hardware details is by [generating and submitting a Hardware
Compatibility List (HCL) report][hcl-howto], then linking to it in your Compatibility List (HCL) report][hcl-howto], then linking to it in your
message. [Ask questions the smart way.][smart-questions] message. [Ask questions the smart way.][smart-questions]
### Be patient ### ### Be patient
Do not "bump" a thread more than once every three days *at Do not "bump" a thread more than once every three days *at
most*. If it seems like your messages to the mailing lists are consistently most*. If it seems like your messages to the mailing lists are consistently
@ -116,7 +114,7 @@ likely that no one who knows the answer has had time to reply yet. Remember
that the devs are very busy working on Qubes. They usually only have a chance that the devs are very busy working on Qubes. They usually only have a chance
to answer questions on the mailing lists once every several days. to answer questions on the mailing lists once every several days.
### Be a good community member ### ### Be a good community member
As with any social community, members earn different reputations for themselves As with any social community, members earn different reputations for themselves
over time. We want these discussion venues to be friendly, productive places over time. We want these discussion venues to be friendly, productive places
@ -135,7 +133,7 @@ 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 other choice but to post anonymously.) You can read our project's [Code of
Conduct][coc] for more information. Conduct][coc] for more information.
### Report issues and submit changes in the right places ### ### 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] are good places to ask questions and discuss
things. However, if you're submitting a more formal report, we'd prefer that things. However, if you're submitting a more formal report, we'd prefer that
@ -144,21 +142,21 @@ 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 don't simply point it out in a discussion venue. Instead, [submit the
change][contributing to the documentation]. change][contributing to the documentation].
### Moderation ### ### Moderation
The moderation team aims to enforce our [Code of Conduct][coc]. The moderation team aims to enforce our [Code of Conduct][coc].
Beyond this, users should not expect any specific action from the moderation team. 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. 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. 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.
### Specific mailing list rules and notes ### ### Specific mailing list rules and notes
#### Use the correct list #### #### Use the correct list
Send your message to the correct list. Read the sections below to determine Send your message to the correct list. Read the sections below to determine
which list is correct for your message. which list is correct for your message.
#### Do not top-post #### #### Do not top-post
[Top-posting] is placing your reply above the quoted message to which you're [Top-posting] is placing your reply above the quoted message to which you're
replying. Please refrain from doing this. Instead, either [interleave] your replying. Please refrain from doing this. Instead, either [interleave] your
@ -166,28 +164,28 @@ 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] by placing your entire reply below
the quoted message to which you're replying. the quoted message to which you're replying.
#### Use proper subject lines #### #### Use proper subject lines
Include a precise and informative subject line. This will allow others to Include a precise and informative subject line. This will allow others to
easily find your thread in the future and use it as a reference. (Bad: "Help! easily find your thread in the future and use it as a reference. (Bad: "Help!
Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working Qubes problems!" Good: "R2B2 Installation problem: Apple keyboard not working
in installer.") in installer.")
#### Do not send duplicates #### #### Do not send duplicates
If your message is not successfully sent to the list, it probably got caught If your message is not successfully sent to the list, it probably got caught
in the spam filter. We check the spam filter regularly, so please be patient, in the spam filter. We check the spam filter regularly, so please be patient,
and your message should be approved (and your email address added to the and your message should be approved (and your email address added to the
whitelist) within a few days. whitelist) within a few days.
#### Keep the list CCed #### #### Keep the list CCed
Keep the mailing list CCed throughout the conversation unless there's a Keep the mailing list CCed throughout the conversation unless there's a
special need for privacy (in which case, use PGP encryption). This increases special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be the likelihood that a greater quantity of useful information will be
available to everyone in the future. available to everyone in the future.
#### Quote appropriately #### #### Quote appropriately
If you're replying to a thread (whether your own or If you're replying to a thread (whether your own or
someone else's), you should make sure to quote enough from previous messages someone else's), you should make sure to quote enough from previous messages
@ -198,7 +196,7 @@ in itself. Do not quote advertisements in signatures or inline PGP signature
blocks. (Quoting the latter interferes with the ability of programs like blocks. (Quoting the latter interferes with the ability of programs like
Enigmail to properly quote replies thereafter). Enigmail to properly quote replies thereafter).
#### English not required #### #### English not required
If you do not speak English, you should feel free to post in your own If you do not speak English, you should feel free to post in your own
language. However, bear in mind that most members of the list can only read language. However, bear in mind that most members of the list can only read
@ -207,7 +205,7 @@ of consideration for those readers. If you choose to write in English, please
do not apologize for doing so poorly, as it is unnecessary. We understand and do not apologize for doing so poorly, as it is unnecessary. We understand and
will ask for clarification if needed. will ask for clarification if needed.
#### Suggestions #### #### Suggestions
While we're generally open to hearing suggestions for new features, please 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], and it's rather
@ -219,7 +217,7 @@ Please note, however, that it's always a good idea to field a discussion of
your idea on the `qubes-devel` list before putting in a lot of hard work on your idea on the `qubes-devel` list before putting in a lot of hard work on
something that we may not be able or willing to accept. something that we may not be able or willing to accept.
#### Google Groups #### #### Google Groups
While the mailing lists are implemented as Google Group web forums, a Google While the mailing lists are implemented as Google Group web forums, a Google
account is in no way required, expected, or encouraged. Many discussants account is in no way required, expected, or encouraged. Many discussants
@ -231,14 +229,12 @@ example, we encourage discussants to use [Split GPG] to sign all of their
messages to the lists, but we do not endorse the use of these Google Groups 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].
## Mailing lists
## Mailing lists ##
This section covers each of our individual [mailing lists][wiki-ml], with This section covers each of our individual [mailing lists][wiki-ml], with
details about the purpose of each list and how to use it. details about the purpose of each list and how to use it.
### qubes-announce
### qubes-announce ###
This is a read-only list for those who wish to receive only very important, 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 infrequent messages. Only the core Qubes team can post to this list. Only
@ -251,26 +247,25 @@ required. Any email address will work.) To unsubscribe, send a blank email to
`qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional `qubes-announce+unsubscribe@googlegroups.com`. This list also has an optional
[Google Groups web interface][qubes-announce-web]. [Google Groups web interface][qubes-announce-web].
### qubes-users
### qubes-users ###
This list is for helping users solve various daily problems with Qubes OS. This list is for helping users solve various daily problems with Qubes OS.
Examples of topics or questions suitable for this list include: Examples of topics or questions suitable for this list include:
* [HCL] reports * [HCL] reports
* Installation problems * Installation problems
* Hardware compatibility problems * Hardware compatibility problems
* Questions of the form: "How do I...?" * Questions of the form: "How do I...?"
Please try searching both the Qubes website and the archives of the mailing Please try searching both the Qubes website and the archives of the mailing
lists before sending a question. In addition, please make sure that you have 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 read and understood the following basic documentation prior to posting to the
list: list:
* The [Installation Guide], [System Requirements], and [HCL] (for problems * The [Installation Guide], [System Requirements], and [HCL] (for problems
related to installing Qubes OS) related to installing Qubes OS)
* The [User FAQ] * The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS) * The [documentation] (for questions about how to use Qubes OS)
You don't have to subscribe in order to post to this list. However, subscribing 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 makes your messages less likely to be marked as spam and allows you to receive
@ -283,20 +278,19 @@ send a blank email to `qubes-users+unsubscribe@googlegroups.com`. This list
also has an optional [Google Groups web interface][qubes-users-web] and also has an optional [Google Groups web interface][qubes-users-web] and
[traditional mail archive][qubes-users-archive]. [traditional mail archive][qubes-users-archive].
### qubes-devel
### qubes-devel ###
This list is primarily intended for people who are interested in contributing to This list is primarily intended for people who are interested in contributing to
Qubes or who are willing to learn more about its architecture and Qubes or who are willing to learn more about its architecture and
implementation. Examples of topics and questions suitable for this list include: implementation. Examples of topics and questions suitable for this list include:
* Questions about why we made certain architecture or implementation decisions. * Questions about why we made certain architecture or implementation decisions.
* For example: "Why did you implement XYZ this way and not the other way?" * For example: "Why did you implement XYZ this way and not the other way?"
* Questions about code layout and where code is for certain functionality. * Questions about code layout and where code is for certain functionality.
* Discussions about proposed new features, patches, etc. * Discussions about proposed new features, patches, etc.
* For example: "I would like to implement feature XYZ." * For example: "I would like to implement feature XYZ."
* Contributed code and patches. * Contributed code and patches.
* Security discussions which are relevant to Qubes in some way. * Security discussions which are relevant to Qubes in some way.
You must be subscribed in order to post to this list. To subscribe, send a You must be subscribed in order to post to this list. To subscribe, send a
blank email to `qubes-devel+subscribe@googlegroups.com`. (Note: A Google blank email to `qubes-devel+subscribe@googlegroups.com`. (Note: A Google
@ -307,18 +301,17 @@ unsubscribe, send a blank email to `qubes-devel+unsubscribe@googlegroups.com`.
This list also has an optional [Google Groups web interface][qubes-devel-web] This list also has an optional [Google Groups web interface][qubes-devel-web]
and [traditional mail archive][qubes-devel-archive]. and [traditional mail archive][qubes-devel-archive].
### qubes-project
### qubes-project ###
This list is for non-technical discussion and coordination around the This list is for non-technical discussion and coordination around the
Qubes OS project. Qubes OS project.
Examples of topics or question suitable for this list include: Examples of topics or question suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events * Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies * Project funding applications and strategies
* FOSS governance discussions * FOSS governance discussions
* Most Github issues tagged "[business]" * Most Github issues tagged "[business]"
You don't have to subscribe in order to post to this list. However, subscribing 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 makes your messages less likely to be marked as spam and allows you to receive
@ -330,17 +323,16 @@ immediately, please allow time for moderation to occur. To unsubscribe, send a
blank email to `qubes-project+unsubscribe@googlegroups.com`. This list also 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][qubes-project-web].
### qubes-translation
### qubes-translation ###
This list is for discussion around the localization and translation of Qubes OS, This list is for discussion around the localization and translation of Qubes OS,
its documentation, and the website. its documentation, and the website.
Examples of topics or question suitable for this list include: 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], the translation platform we use
* Who is managing localization for a given language * Who is managing localization for a given language
* Most Github issues tagged "[localization]" * Most Github issues tagged "[localization]"
You don't have to subscribe in order to post to this list. However, subscribing 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 makes your messages less likely to be marked as spam and allows you to receive
@ -353,8 +345,7 @@ unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`. This list also has an `qubes-translation+unsubscribe@googlegroups.com`. This list also has an
optional [Google Groups web interface][qubes-translation-web]. optional [Google Groups web interface][qubes-translation-web].
## Forum
## Forum ##
We have a community forum for Qubes OS users: We have a community forum for Qubes OS users:
@ -368,7 +359,7 @@ 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], we're pleased to be
able to create this space for our community. able to create this space for our community.
### Why was this forum created? ### ### Why was this forum created?
Previously, the only option for a forum-like experience was to interact with Previously, the only option for a forum-like experience was to interact with
our mailing lists via Google Groups, but we understand all too well that the our mailing lists via Google Groups, but we understand all too well that the
@ -379,7 +370,7 @@ ease-of-use, and modern social features that today's forums support. Moreover,
Discourse features email integration for those who still prefer the traditional Discourse features email integration for those who still prefer the traditional
mailing list format. mailing list format.
### How is this different from our mailing lists? ### ### How is this different from our mailing lists?
To be clear, this is *not* a replacement for the mailing lists. This forum is To be clear, this is *not* a replacement for the mailing lists. This forum is
simply an *additional* place for discussion. Certain types of discussions simply an *additional* place for discussion. Certain types of discussions
@ -392,7 +383,7 @@ users simply appreciate the ability to add a "reaction" to a message instead of
having to add an entirely new reply. Whatever your reasons, it's up to you to having to add an entirely new reply. Whatever your reasons, it's up to you to
decide where and how you want to join the conversation. decide where and how you want to join the conversation.
### Does this split the community? ### ### Does this split the community?
Many open-source projects (such as Fedora and Debian) have both mailing lists Many open-source projects (such as Fedora and Debian) have both mailing lists
and forums (and additional discussion venues). In fact, Qubes already had and forums (and additional discussion venues). In fact, Qubes already had
@ -418,15 +409,13 @@ Generally speaking, these are not intended to be primary support venues.
Rather, these are primarily intended to be a way to more widely disseminate items published on the [news](/news/) page. Rather, these are primarily intended to be a way to more widely disseminate items published on the [news](/news/) page.
If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news. If you use one of these platforms, you may find it convenient to follow the Qubes OS Project there as a way of receiving Qubes news.
## Unofficial chat channels
## Unofficial chat channels ##
The following unofficial chat channels are maintained by the community: The following unofficial chat channels are maintained by the community:
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org> * Matrix, Qubes-related: <https://matrix.to/#/#cybersec-qubes_os:matrix.org>
* Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org> * Matrix, strictly Qubes: <https://matrix.to/#/#Qubes-OS:matrix.org>
* `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/> * `#qubes` channel on freenode.net via traditional IRC clients or: <https://webchat.freenode.net/>
[mailing lists]: #mailing-lists [mailing lists]: #mailing-lists
[wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list [wiki-ml]: https://en.wikipedia.org/wiki/Electronic_mailing_list
@ -473,4 +462,3 @@ The following unofficial chat channels are maintained by the community:
[IRC]: #unofficial-chat-channels [IRC]: #unofficial-chat-channels
[Reddit]: https://www.reddit.com/r/Qubes/ [Reddit]: https://www.reddit.com/r/Qubes/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

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

@ -4,21 +4,17 @@ title: Canary Checklist
permalink: /security/canaries/checklist/ permalink: /security/canaries/checklist/
--- ---
Canary Checklist # Canary Checklist
================
Preparation ## Preparation
-----------
* Draft canary and push to private repository * Draft canary and push to private repository
* Finalize canary, sign, and add signed tags * Finalize canary, sign, and add signed tags
Announcement ## Announcement
------------
* Push canary to public repository
* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media
* Set a reminder for the next canary
* Push canary to public repository
* Publish a [news post](/news/) using the [Canary Template](/security/canaries/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media
* Set a reminder for the next canary

1
project-security/canary-template.md
View File

@ -58,4 +58,3 @@ Footnotes
``` ```
~~~ ~~~

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

@ -5,22 +5,18 @@ permalink: /security/bulletins/checklist/
redirect_from: /doc/security-bulletins/checklist/ redirect_from: /doc/security-bulletins/checklist/
--- ---
Security Bulletin Checklist # Security Bulletin Checklist
===========================
Preparation ## Preparation
-----------
* Draft QSB and push to private repository * Draft QSB and push to private repository
* Build fixed packages * Build fixed packages
* Finalize QSB, sign, and add signed tags * Finalize QSB, sign, and add signed tags
Announcement ## Announcement
------------
* Upload packages to `security-testing` and `current-testing` repositories
* Push QSB to public repository
* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media
* Upload packages to `security-testing` and `current-testing` repositories
* Push QSB to public repository
* Publish a [news post](/news/) using the [QSB Template](/security/bulletins/template/)
* Send the content of the news post to the appropriate [mailing lists](/support/)
* Share link to news post on social media

1
project-security/security-bulletins-template.md
View File

@ -80,4 +80,3 @@ https://www.qubes-os.org/security/
``` ```
~~~ ~~~

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

@ -20,18 +20,17 @@ Qubes Security Pack
The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains: The **Qubes Security Pack** (`qubes-secpack`) is a Git repository that contains:
* [Qubes PGP keys](https://keys.qubes-os.org/keys/) * [Qubes PGP keys](https://keys.qubes-os.org/keys/)
* [Qubes Security Bulletins (QSBs)](/security/bulletins/) * [Qubes Security Bulletins (QSBs)](/security/bulletins/)
* [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries) * [Qubes warrant canaries](https://github.com/QubesOS/qubes-secpack/tree/master/canaries)
* [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund) * [Qubes Bitcoin fund information](https://github.com/QubesOS/qubes-secpack/tree/master/fund)
* Security-related information and announcements (e.g., key revocations) * Security-related information and announcements (e.g., key revocations)
While `qubes-secpack` itself is independent of any particular host, its current While `qubes-secpack` itself is independent of any particular host, its current
official location is: official location is:
<https://github.com/QubesOS/qubes-secpack> <https://github.com/QubesOS/qubes-secpack>
History and Rationale History and Rationale
--------------------- ---------------------
@ -40,6 +39,7 @@ rationale in an
[email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ) [email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ)
to the Qubes mailing lists: to the Qubes mailing lists:
```
Hello, Hello,
A new Qubes Security Bulletin has been just released and is available here: A new Qubes Security Bulletin has been just released and is available here:
@ -126,6 +126,7 @@ to the Qubes mailing lists:
[3] Deterministic builds are required because it's the only way we can [3] Deterministic builds are required because it's the only way we can
implement multiple signature scheme for distributed binaries. implement multiple signature scheme for distributed binaries.
```
How to Obtain, Verify, and Read How to Obtain, Verify, and Read
------------------------------- -------------------------------
@ -133,8 +134,9 @@ How to Obtain, Verify, and Read
The following example demonstrates one method of obtaining the `qubes-secpack`, The following example demonstrates one method of obtaining the `qubes-secpack`,
verifying its contents, and reading them. verifying its contents, and reading them.
1. Clone the `qubes-secpack` repo. 1. Clone the `qubes-secpack` repo.
```shell_session
$ git clone https://github.com/QubesOS/qubes-secpack.git $ git clone https://github.com/QubesOS/qubes-secpack.git
Cloning into 'qubes-secpack'... Cloning into 'qubes-secpack'...
remote: Counting objects: 195, done. remote: Counting objects: 195, done.
@ -142,9 +144,11 @@ verifying its contents, and reading them.
Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done. Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
Resolving deltas: 100% (47/47), done. Resolving deltas: 100% (47/47), done.
Checking connectivity... done. Checking connectivity... done.
```
2. Import the included PGP keys. 2. Import the included PGP keys.
```shell_session
$ gpg --import qubes-secpack/keys/*/* $ gpg --import qubes-secpack/keys/*/*
gpg: directory `/home/user/.gnupg' created gpg: directory `/home/user/.gnupg' created
gpg: new configuration file `/home/user/.gnupg/gpg.conf' created gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
@ -172,9 +176,11 @@ verifying its contents, and reading them.
gpg: Total number processed: 17 gpg: Total number processed: 17
gpg: imported: 17 (RSA: 17) gpg: imported: 17 (RSA: 17)
gpg: no ultimately trusted keys found gpg: no ultimately trusted keys found
```
3. Verify and trust the Qubes Master Signing Key. 3. Verify and trust the Qubes Master Signing Key.
```shell_session
$ gpg --edit-key 36879494 $ gpg --edit-key 36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it. This is free software: you are free to change and redistribute it.
@ -214,6 +220,7 @@ verifying its contents, and reading them.
unless you restart the program. unless you restart the program.
gpg> q gpg> q
```
**Important!** **Important!**
@ -224,8 +231,9 @@ verifying its contents, and reading them.
step, ensuring they match. You can read more about digital signatures and step, ensuring they match. You can read more about digital signatures and
key verification [here](/security/verifying-signatures/). key verification [here](/security/verifying-signatures/).
4. Verify signed Git tags. 4. Verify signed Git tags.
```shell_session
$ cd qubes-secpack/ $ cd qubes-secpack/
$ git tag -v `git describe` $ git tag -v `git describe`
object 2bb7f0b966593d8ed74e140a04d60c68b96b164e object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
@ -237,11 +245,13 @@ verifying its contents, and reading them.
gpg: Signature made 2016-07-12T08:01:46 PDT gpg: Signature made 2016-07-12T08:01:46 PDT
gpg: using RSA key 0x4E6829BC92C7B3DC gpg: using RSA key 0x4E6829BC92C7B3DC
gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full] gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full]
```
(The final line of output confirms that the signature is good.) (The final line of output confirms that the signature is good.)
5. Verify detached PGP signatures. 5. Verify detached PGP signatures.
```shell_session
$ cd canaries/ $ cd canaries/
$ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC gpg: Signature made Mon Jan 5 20:21:40 2015 UTC using RSA key ID 92C7B3DC
@ -249,8 +259,9 @@ verifying its contents, and reading them.
$ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt $ gpg --verify canary-001-2015.txt.sig.marmarek canary-001-2015.txt
gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A gpg: Signature made Mon Jan 5 20:13:37 2015 UTC using RSA key ID 1830E06A
gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" gpg: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>"
```
(The fourth and final lines of output confirm that the two signatures are (The fourth and final lines of output confirm that the two signatures are
good.) good.)
The same procedures can be applied to any directory or file in the The same procedures can be applied to any directory or file in the
@ -258,4 +269,3 @@ The same procedures can be applied to any directory or file in the
signatures) are provided to ensure that the system is robust (e.g., against a signatures) are provided to ensure that the system is robust (e.g., against a
potential failure in Git tag-based verification) and to give users more options potential failure in Git tag-based verification) and to give users more options
to verify the files. to verify the files.

35
project-security/security.md
View File

@ -14,8 +14,7 @@ redirect_from:
- /trac/wiki/SecurityPage/ - /trac/wiki/SecurityPage/
--- ---
Qubes OS Project Security Center # Qubes OS Project Security Center
================================
- [Security FAQ] - [Security FAQ]
- [Security Goals] - [Security Goals]
@ -26,50 +25,46 @@ Qubes OS Project Security Center
- [Why and How to Verify Signatures] - [Why and How to Verify Signatures]
- [PGP Keys] - [PGP Keys]
## Reporting Security Issues in Qubes OS
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! 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 ## Security Updates
----------------
Qubes security updates are obtained by [Updating Qubes OS]. Qubes security updates are obtained by [Updating Qubes OS].
The Qubes Security Team ## 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] that is responsible for ensuring the security of Qubes OS and the Qubes OS Project.
In particular, the QST is responsible for: In particular, the QST is responsible for:
- Responding to [reported security issues] - Responding to [reported security issues]
- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS - Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS
- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS - Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- Writing, signing, and publishing [Security Bulletins] - Writing, signing, and publishing [Security Bulletins]
- Writing, signing, and publishing [Canaries] - Writing, signing, and publishing [Canaries]
- Generating, safeguarding, and using the project's [PGP Keys] - Generating, safeguarding, and using the project's [PGP 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. 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: The Qubes Security Team can be contacted via email at the following address:
security at qubes-os dot org ```
security at qubes-os dot org
```
### Security Team PGP Key
### Security Team PGP Key ###
Please use the [Security Team PGP Key] to encrypt all emails sent to this address. 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]. 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 see [Why and How to Verify Signatures] for information about how to verify these keys.
### Members of the Security Team ### ### Members of the Security Team
- [Marek Marczykowski-Górecki] - [Marek Marczykowski-Górecki]
- [Simon Gaiser (aka HW42)] - [Simon Gaiser (aka HW42)]
- [Joanna Rutkowska] ([emeritus, canaries only]) - [Joanna Rutkowska] ([emeritus, canaries only])
[Security FAQ]: /faq/#general--security [Security FAQ]: /faq/#general--security
[Security Goals]: /security/goals/ [Security Goals]: /security/goals/
[Security Pack]: /security/pack/ [Security Pack]: /security/pack/

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

@ -9,11 +9,9 @@ redirect_from:
- /wiki/VerifyingSignatures/ - /wiki/VerifyingSignatures/
--- ---
On Digital Signatures and Key Verification # On Digital Signatures and Key Verification
==========================================
What Digital Signatures Can and Cannot Prove ## What Digital Signatures Can and Cannot Prove
--------------------------------------------
Most people --- even programmers --- are confused about the basic concepts underlying digital signatures. Most people --- even programmers --- are confused about the basic concepts underlying digital signatures.
Therefore, most people should read this section, even if it looks trivial at first sight. Therefore, most people should read this section, even if it looks trivial at first sight.
@ -39,20 +37,17 @@ Anybody can generate a GPG key pair that purports to belong to "The Qubes Projec
The next section explains how to verify the validity of the Qubes signing keys in the process of verifying a Qubes ISO. 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], not just verifying ISOs.)
## How to Verify Qubes ISO Signatures
How to Verify Qubes ISO Signatures
----------------------------------
This section will guide you through the process of verifying a Qubes ISO by checking its PGP signature. 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: There are three basic steps in this process:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK] 2. [Get the Release Signing Key][RSK]
3. [Verify your Qubes ISO][signature file] 3. [Verify your Qubes ISO][signature file]
If you run into any problems, please consult the [Troubleshooting FAQ] below. If you run into any problems, please consult the [Troubleshooting FAQ] below.
### Preparation ### Preparation
Before we begin, you'll need a program that can verify PGP signatures. Before we begin, you'll need a program that can verify PGP signatures.
@ -70,7 +65,6 @@ Open a terminal to enter commands.
The commands below will use `gpg2`, but if that doesn't work for you, try `gpg` instead. The commands below will use `gpg2`, but if that doesn't work for you, try `gpg` instead.
If that still doesn't work, please consult the documentation for your specific program (see links above). If that still doesn't work, please consult the documentation for your specific program (see links above).
### 1. Get the Qubes Master Signing Key and verify its authenticity ### 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. 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.
@ -80,27 +74,37 @@ This Qubes Master Signing Key was generated on and is kept only on a dedicated,
There are several ways to get the Qubes Master Signing Key. 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]):
```shell_session
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc $ gpg2 --import /usr/share/qubes/qubes-master-key.asc
```
- If you're on Fedora, you can get it in the `distribution-gpg-keys` package: - If you're on Fedora, you can get it in the `distribution-gpg-keys` package:
```shell_session
$ dnf install distribution-gpg-keys $ dnf install distribution-gpg-keys
```
- If you're on Debian, it may already be included in your keyring. - If you’re on Debian, it may already be included in your keyring.
- Fetch it with GPG: - Fetch it with GPG:
```shell_session
$ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc $ 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][Qubes Master Signing Key], then import it with GPG:
```shell_session
$ gpg2 --import ./qubes-master-signing-key.asc $ 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] (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 $ 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] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
@ -120,9 +124,11 @@ Therefore, if you know the genuine Qubes Master Signing Key fingerprint, then yo
For example, here is the Qubes Master Signing Key fingerprint: For example, here is the Qubes Master Signing Key fingerprint:
pub 4096R/36879494 2010-04-01 ```
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key uid Qubes Master Signing Key
```
But how do you know that this is the real fingerprint? 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][website-trust], so the fingerprint you see here may not be genuine.
@ -130,43 +136,43 @@ That's why we strongly suggest obtaining the fingerprint from *multiple, indepen
Here are some ideas for how to do that: Here are some ideas for how to do that:
- Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)). - Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- Check against PDFs, photographs, and videos in which the fingerprint appears - Check against PDFs, photographs, and videos in which the fingerprint appears
(e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)). (e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key. - Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms. - Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- Repeat the above over Tor. - Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers. - Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.). - Repeat the above on different networks (work, school, internet cafe, etc.).
- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint. - Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- Repeat the above from different computers and devices. - Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place. Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place.
Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match. Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match.
Now that you've imported the authentic Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys). Now that you've imported the authentic Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 ```
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. $ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
This is free software: you are free to change and redistribute it. gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
There is NO WARRANTY, to the extent permitted by law. This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key [ unknown] (1). Qubes Master Signing Key
gpg> fpr gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key [ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.) (by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say 1 = I don't know or won't say
2 = I do NOT trust 2 = I do NOT trust
@ -175,16 +181,17 @@ Now that you've imported the authentic Qubes Master Signing Key, set its trust l
5 = I trust ultimately 5 = I trust ultimately
m = back to the main menu m = back to the main menu
Your decision? 5 Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y Do you really want to set this key to ultimate trust? (y/N) y
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: ultimate validity: unknown trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key [ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct Please note that the shown key validity is not necessarily correct
unless you restart the program. unless you restart the program.
gpg> q gpg> q
```
Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key. Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
@ -192,47 +199,56 @@ Before proceeding to the next step, make sure the Qubes Master Signing Key is in
(Note: We have already verified the authenticity of the key, so this final check is not about security. (Note: We have already verified the authenticity of the key, so this final check is not about security.
Rather, it's just a sanity check to make sure that we've imported the key into our keyring correctly.) Rather, it's just a sanity check to make sure that we've imported the key into our keyring correctly.)
$ gpg2 -k "Qubes Master Signing Key" ```
pub rsa4096 2010-04-01 [SC] $ gpg2 -k "Qubes Master Signing Key"
pub rsa4096 2010-04-01 [SC]
427F11FD0FAA4B080123F01CDDFA1A3E36879494 427F11FD0FAA4B080123F01CDDFA1A3E36879494
uid [ultimate] Qubes Master Signing Key uid [ultimate] Qubes Master Signing Key
```
If you don't see the Qubes Master Signing Key here with a trust level of "ultimate," go back and follow the instructions in this section carefully. If you don't see the Qubes Master Signing Key here with a trust level of "ultimate," go back and follow the instructions in this section carefully.
### 2. Get the Release Signing Key ### 2. Get the Release Signing Key
The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release. The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
There are several ways to get the Release Signing Key for your Qubes release. 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-*`. - 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][copy-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-*`. In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
If you wish to use one of these keys, make sure to import it into your keyring, e.g.: If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
```
$ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-* $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
```
- Fetch it with GPG: - Fetch it with GPG:
```shell_session
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
```
- Download it as a file. - Download it as a file.
You can find the Release Signing Key for your Qubes version on the [Downloads] page. 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 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].
Once you've downloaded your Release Signing Key, import it with GPG: Once you've downloaded your Release Signing Key, import it with GPG:
```shell_session
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc
```
The Release Signing Key should be signed by the Qubes Master Signing Key: The Release Signing Key should be signed by the Qubes Master Signing Key:
$ gpg2 --check-signatures "Qubes OS Release X Signing Key" ```shell_session
pub rsa4096 2017-03-06 [SC] $ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9 5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] Qubes OS Release X Signing Key uid [ full ] Qubes OS Release X Signing Key
sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key
sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key
gpg: 2 good signatures gpg: 2 good signatures
```
This is just an example, so the output you receive will not look exactly the same. This is just an example, so the output you receive will not look exactly the same.
What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix. What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix.
@ -242,14 +258,15 @@ A `sig-` prefix would indicate a bad signature and `sig%` would mean that gpg en
It is not necessary to independently verify the authenticity of the Release Signing Key, since you already verified the authenticity of the Qubes Master Signing Key. It is not necessary to independently verify the authenticity of the Release Signing Key, since you already verified the authenticity of the Qubes Master Signing Key.
Before proceeding to the next step, make sure the Release Signing Key is in your keyring: Before proceeding to the next step, make sure the Release Signing Key is in your keyring:
$ gpg2 -k "Qubes OS Release" ```
pub rsa4096 2017-03-06 [SC] $ gpg2 -k "Qubes OS Release"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9 5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] Qubes OS Release X Signing Key uid [ full ] Qubes OS Release X Signing Key
```
If you don't see the correct Release Signing Key here, go back and follow the instructions in this section carefully. If you don't see the correct Release Signing Key here, go back and follow the instructions in this section carefully.
### 3. Verify your Qubes ISO ### 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] page alongside the ISO.
@ -260,20 +277,20 @@ Download both the ISO and its signature file.
Put both of them in the same directory, then navigate to that directory. Put both of them in the same directory, then navigate to that directory.
Now, you can verify the ISO by executing this GPG command in the directory that contains both files: Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso ```shell_session
gpg: armor header: Version: GnuPG v1 $ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082 gpg: armor header: Version: GnuPG v1
gpg: using PGP trust model gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: Good signature from "Qubes OS Release X Signing Key" gpg: using PGP trust model
gpg: binary signature, digest algorithm SHA256 gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
```
This is just an example, so the output you receive will not look exactly the same. This is just an example, so the output you receive will not look exactly the same.
What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`. What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`.
This confirms that the signature on the ISO is good. This confirms that the signature on the ISO is good.
## How to Verify Qubes ISO Digests
How to Verify Qubes ISO Digests
-------------------------------
Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`. Each Qubes ISO is also accompanied by a plain text file ending in `.DIGESTS`.
This file contains the output of running several different cryptographic hash functions on the ISO in order to obtain alphanumeric outputs known as "digests" or "hash values." 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."
@ -286,47 +303,51 @@ The digest filename is always the same as the ISO filename followed by `.DIGESTS
Since the digest file is a plain text file, you can open it with any text editor. Since the digest file is a plain text file, you can open it with any text editor.
Inside, you should find text that looks similar to this: Inside, you should find text that looks similar to this:
-----BEGIN PGP SIGNED MESSAGE----- ```
Hash: SHA256 -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso 3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso 1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-----BEGIN PGP SIGNATURE----- -----BEGIN PGP SIGNATURE-----
Version: GnuPG v2 Version: GnuPG v2
iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0 9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf 0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj 2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1 g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
3N/6YZw1gSuvBlTquP27 3N/6YZw1gSuvBlTquP27
=e9oD =e9oD
-----END PGP SIGNATURE----- -----END PGP SIGNATURE-----
```
Four digests have been computed for this ISO. Four digests have been computed for this ISO.
The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512. The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512.
One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs: One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs:
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS ```shell_session
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK Qubes-RX-x86_64.iso: OK
md5sum: WARNING: 23 lines are improperly formatted md5sum: WARNING: 23 lines are improperly formatted
$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS $ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK Qubes-RX-x86_64.iso: OK
sha1sum: WARNING: 23 lines are improperly formatted sha1sum: WARNING: 23 lines are improperly formatted
$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS $ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK Qubes-RX-x86_64.iso: OK
sha256sum: WARNING: 23 lines are improperly formatted sha256sum: WARNING: 23 lines are improperly formatted
$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS $ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK Qubes-RX-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted sha512sum: WARNING: 23 lines are improperly formatted
```
The `OK` response tells us that the hash value for that particular hash function matches. The `OK` response tells us that the hash value for that particular hash function matches.
The program also warns us that there are 23 improperly formatted lines, but this is to be expected. The program also warns us that there are 23 improperly formatted lines, but this is to be expected.
@ -336,14 +357,16 @@ Therefore, it is safe to ignore these warning lines.
Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.: Another way is to use `openssl` to compute each hash value, then compare them to the contents of the digest file.:
$ openssl dgst -md5 Qubes-RX-x86_64.iso ```shell_session
MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82 $ openssl dgst -md5 Qubes-RX-x86_64.iso
$ openssl dgst -sha1 Qubes-RX-x86_64.iso MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f $ openssl dgst -sha1 Qubes-RX-x86_64.iso
$ openssl dgst -sha256 Qubes-RX-x86_64.iso SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a $ openssl dgst -sha256 Qubes-RX-x86_64.iso
$ openssl dgst -sha512 Qubes-RX-x86_64.iso SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe $ openssl dgst -sha512 Qubes-RX-x86_64.iso
SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
```
(Notice that the outputs match the values from the digest file.) (Notice that the outputs match the values from the digest file.)
@ -351,10 +374,11 @@ 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. Therefore, we should also verify the authenticity of the listed hash values.
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line: Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK] 1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK] 2. [Get the Release Signing Key][RSK]
3. Verify the signature in the digest file: 3. Verify the signature in the digest file:
```shell_session
$ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256 gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v2 gpg: armor header: Version: GnuPG v2
@ -363,13 +387,12 @@ Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to
gpg: using PGP trust model gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key" gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: textmode signature, digest algorithm SHA256 gpg: textmode signature, digest algorithm SHA256
```
The signature is good. 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][QMSK]), we can be confident that these hash values came from the Qubes devs.
## How to Verify Qubes Repos
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], 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.) (One or both may be present, but only one is required.)
@ -379,19 +402,27 @@ Instead, ask the person who pushed the unsigned commits to sign them.
To verify a signature on a Git tag: To verify a signature on a Git tag:
$ git tag -v <tag name> ```shell_session
$ git tag -v <tag name>
```
or or
$ git verify-tag <tag name> ```shell_session
$ git verify-tag <tag name>
```
To verify a signature on a Git commit: To verify a signature on a Git commit:
$ git log --show-signature <commit ID> ```shell_session
$ git log --show-signature <commit ID>
```
or or
$ git verify-commit <commit ID> ```shell_session
$ 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]) 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. 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.
@ -399,68 +430,56 @@ Since there's no way for you to be certain that all such conditions hold, you're
Also see: [Distrusting the Infrastructure] Also see: [Distrusting the Infrastructure]
## Troubleshooting FAQ
Troubleshooting FAQ
-------------------
### Why am I getting "Can't check signature: public key not found"? ### 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][RSK].
### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"? ### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"?
The problem could be one or more of the following: The problem could be one or more of the following:
- You're trying to verify the wrong file(s). - You're trying to verify the wrong file(s).
Read this page again carefully. Read this page again carefully.
- You're using the wrong GPG command. - You're using the wrong GPG command.
Follow the examples in [Verify your Qubes ISO][signature file] carefully. Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- The ISO or [signature file] is bad (e.g., incomplete or corrupt download). - The ISO or [signature file] is bad (e.g., incomplete or corrupt download).
Try downloading the signature file again from a different source, then try verifying again. 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. If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
### Why am I getting "bash: gpg2: command not found"? ### Why am I getting "bash: gpg2: command not found"?
You don't have `gpg2` installed. You don't have `gpg2` installed.
Please install it using the method appropriate for your environment (e.g., via your package manager). Please install it using the method appropriate for your environment (e.g., via your package manager).
### Why am I getting "No such file or directory"? ### Why am I getting "No such file or directory"?
Your working directory does not contain the required files. Your working directory does not contain the required files.
Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory. Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory.
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"? ### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?
The correct ISO is not in your working directory. The correct ISO is not in your working directory.
### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"? ### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"?
The correct [signature file] is not in your working directory. The correct [signature file] is not in your working directory.
### Why am I getting "no valid OpenPGP data found"? ### 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`. Either you don't have the correct [signature file], or you inverted the arguments to `gpg2`.
([The signature file goes first.][signature file]) ([The signature file goes first.][signature file])
### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."? ### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK]. Either you don't have the [Qubes Master Signing Key][QMSK], or you didn't [set its trust level correctly][QMSK].
### Why am I getting "X signature not checked due to a missing key"? ### 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. 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][QMSK] and the [Release Signing Key][RSK] for your Qubes version.
### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key? ### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key?
This is just a basic part of how OpenPGP works. This is just a basic part of how OpenPGP works.
@ -468,43 +487,35 @@ Anyone can sign anyone else's public key and upload the signed public key to key
Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate). Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
This has no impact on verifying Qubes ISOs, code, or keys. This has no impact on verifying Qubes ISOs, code, or keys.
### Why am I getting "verify signatures failed: unexpected data"? ### 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].
### Why am I getting "not a detached signature"? ### 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].
### Why am I getting "CRC error; [...] no signature found [...]"? ### 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], or the signature file has been modified.
Try downloading it again or from a different source. 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] and the [digest file]?
No, either method is sufficient by itself. No, either method is sufficient by itself.
### Why am I getting "no properly formatted X checksum lines found"? ### 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].
### Why am I getting "WARNING: X lines are improperly formatted"? ### 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][digest file] again.
### Why am I getting "WARNING: 1 listed file could not be read"? ### Why am I getting "WARNING: 1 listed file could not be read"?
The correct ISO is not in your working directory. The correct ISO is not in your working directory.
### I have another problem that isn't mentioned here. ### I have another problem that isn't mentioned here.
Carefully read this page again to be certain that you didn't skip any steps. Carefully read this page again to be certain that you didn't skip any steps.
@ -513,7 +524,6 @@ If your question is about GPG, please see the [GPG documentation].
Still have question? 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] for places where you can ask!
[website-trust]: /faq/#should-i-trust-this-website [website-trust]: /faq/#should-i-trust-this-website
[Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure [Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[verifying repos]: #how-to-verify-qubes-repos [verifying repos]: #how-to-verify-qubes-repos
@ -535,4 +545,3 @@ Please see [Help, Support, Mailing Lists, and Forum] for places where you can as
[GPG documentation]: https://www.gnupg.org/documentation/ [GPG documentation]: https://www.gnupg.org/documentation/
[Help, Support, Mailing Lists, and Forum]: /support/ [Help, Support, Mailing Lists, and Forum]: /support/
[except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544 [except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544

2
project-security/xsa.md
View File

@ -16,9 +16,9 @@ Under the "Is Qubes Affected?" column, there are two possible values: **Yes** or
* **Yes** means that the *security* of Qubes OS *is* affected. * **Yes** means that the *security* of Qubes OS *is* affected.
* **No** means that the *security* of Qubes OS is *not* affected. * **No** means that the *security* of Qubes OS is *not* affected.
Important Notes Important Notes
--------------- ---------------
* For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] as affecting the *security* of Qubes OS. * For the purpose of this tracker, we do *not* classify mere [denial-of-service (DoS) attacks][DoS] 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**. 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. * 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.

10
user/advanced-configuration/awesome.md
View File

@ -19,7 +19,9 @@ redirect_from:
awesome can be installed with the standard dom0 installation mechanisms. awesome can be installed with the standard dom0 installation mechanisms.
$ sudo qubes-dom0-update awesome ```shell_session
$ sudo qubes-dom0-update awesome
```
That's it. After logging out, you can select awesome in the login manager. That's it. After logging out, you can select awesome in the login manager.
@ -27,7 +29,9 @@ That's it. After logging out, you can select awesome in the login manager.
To [contribute code](/doc/contributing/) you may clone the awesome repository as follows: To [contribute code](/doc/contributing/) you may clone the awesome repository as follows:
$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome ```shell_session
$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
```
For build instructions please check the repository _README_. For build instructions please check the repository _README_.
@ -66,6 +70,7 @@ In particular the following events are not meant to cause a focus change:
* mouse move without click (sloppy focus) * mouse move without click (sloppy focus)
For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.: For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window) * windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
* windows shouldn't be able to change their size themselves * windows shouldn't be able to change their size themselves
* windows shouldn't be able to modify their borders in any way * windows shouldn't be able to modify their borders in any way
@ -184,4 +189,3 @@ client.disconnect_signal("request::tag", ewmh.tag)
``` ```
The signal names may change across awesome versions. The signal names may change across awesome versions.

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

@ -49,8 +49,10 @@ From now on any files within the `/var/lib/tor` folder will persist across reboo
You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line. You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots. For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots.
binds+=( '/var/lib/tor' ) ```
binds+=( '/etc/tor/torrc' ) binds+=( '/var/lib/tor' )
binds+=( '/etc/tor/torrc' )
```
## Other Configuration Folders ## ## Other Configuration Folders ##
@ -68,7 +70,6 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir
If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot. If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot.
Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor` Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor`
## Limitations ## ## Limitations ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh. * Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.

2
user/advanced-configuration/config-files.md
View File

@ -50,6 +50,7 @@ The scripts here all run as root.
Intended for use with problematic device drivers. Intended for use with problematic device drivers.
- In NetVMs/ProxyVMs, scripts placed in `/rw/config/network-hooks.d` will be ran when configuring Qubes interfaces. For each script, the `command`, `vif`, `vif_type` and `ip` is passed as arguments (see `/etc/xen/scripts/vif-route-qubes`). For example, consider a PV AppVM `work` with IP `10.137.0.100` and `sys-firewall` as NetVM. Assuming it's Xen domain id is arbitrary `12` then, the following script located at `/rw/config/network-hooks.d/hook-100.sh` in `sys-firewall`: - In NetVMs/ProxyVMs, scripts placed in `/rw/config/network-hooks.d` will be ran when configuring Qubes interfaces. For each script, the `command`, `vif`, `vif_type` and `ip` is passed as arguments (see `/etc/xen/scripts/vif-route-qubes`). For example, consider a PV AppVM `work` with IP `10.137.0.100` and `sys-firewall` as NetVM. Assuming it's Xen domain id is arbitrary `12` then, the following script located at `/rw/config/network-hooks.d/hook-100.sh` in `sys-firewall`:
~~~ ~~~
#!/bin/bash #!/bin/bash
@ -76,7 +77,6 @@ Note that scripts need to be executable (`chmod +x`) to be used.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist. Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist.
GUI and audio configuration in dom0 GUI and audio configuration in dom0
----------------------------------- -----------------------------------

123
user/advanced-configuration/disposablevm-customization.md
View File

@ -12,18 +12,21 @@ redirect_from:
# DisposableVM Customization # DisposableVM Customization
## Introduction ## Introduction
A [DisposableVM](/doc/disposablevm) can be based on any [TemplateBasedVM](/doc/glossary/#templatebasedvm). A [DisposableVM](/doc/disposablevm) can be based on any [TemplateBasedVM](/doc/glossary/#templatebasedvm).
You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs. You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs.
To prepare an AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example: To prepare an AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example:
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True ```shell_session
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
```
Additionally, if you want to have menu entries for starting applications in DisposableVM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature: Additionally, if you want to have menu entries for starting applications in DisposableVM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature:
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1 ```shell_session
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
```
Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information. Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
@ -35,25 +38,27 @@ In particular, the *default* DisposableVM Template is important because it is us
This means that it will have access to everything that you open with this 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 and refrain from making any risky customizations to it. For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM and refrain from making any risky customizations to it.
## Creating a new DisposableVM Template ## Creating a new DisposableVM Template
In Qubes 4.0, you're no longer restricted to a single DisposableVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DisposableVM Template you like. In Qubes 4.0, you're no longer restricted to a single DisposableVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DisposableVM Template you like.
To create new DisposableVM Template, lets say `custom-disposablevm-template`, based on `debian-9` template, use following commands: To create new DisposableVM Template, lets say `custom-disposablevm-template`, based on `debian-9` template, use following commands:
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template ```shell_session
[user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1 [user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
```
Additionally you may want to set it as default DisposableVM Template: Additionally you may want to set it as default DisposableVM Template:
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template ```shell_session
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template
```
The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details. The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details.
If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page. If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page.
## Customization of DisposableVM ## Customization of DisposableVM
_**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._ _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._
@ -63,7 +68,9 @@ This can be done by customizing the DisposableVM Template on which it is based:
1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself). 1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
```shell_session
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
```
2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include: 2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage. - Changing Firefox's default startup settings and homepage.
@ -72,7 +79,6 @@ This can be done by customizing the DisposableVM Template on which it is based:
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). 4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
## Using static DisposableVMs for sys-* ## Using static DisposableVMs for sys-*
You can use a static DisposableVM for `sys-*` as long as it is stateless. You can use a static DisposableVM for `sys-*` as long as it is stateless.
@ -130,7 +136,6 @@ qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2 qubes-prefs clockvm sys-net2
~~~ ~~~
## Adding programs to DisposableVM Application Menu ## Adding programs to DisposableVM Application Menu
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM. For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM.
@ -139,27 +144,27 @@ In order to do that, select "Qube settings" entry in selected base AppVM, go to
Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead. Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
## Create Custom sys-net sys-firewall and sys-usb DisposableVMs ## Create Custom sys-net sys-firewall and sys-usb DisposableVMs
Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem. Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
Functionality is not limited, users can: Functionality is not limited, users can:
* Set custom firewall rule sets and run Qubes VPN scripts. - Set custom firewall rule sets and run Qubes VPN scripts.
* Set DisposableVMs to autostart at system boot. - Set DisposableVMs to autostart at system boot.
* Attach PCI devices with the `--persistent` option. - Attach PCI devices with the `--persistent` option.
Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs. Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate DisposableVM Template for use by each DisposableVM. If DisposableVM Template customization is not needed, then a single DisposableVM Template is used as a template for all DisposableVMs. >_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate DisposableVM Template for use by each DisposableVM. If DisposableVM Template customization is not needed, then a single DisposableVM Template is used as a template for all DisposableVMs.
### Create and configure the DisposableVM Template on which the DisposableVM will be based ### Create and configure the DisposableVM Template on which the DisposableVM will be based
1. Create the DisposableVM Template: 1. Create the DisposableVM Template:
```shell_session
[user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name> [user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
```
2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc. 2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc.
@ -167,46 +172,65 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
3. Set the DisposableVM Template as template for DisposableVMs: 3. Set the DisposableVM Template as template for DisposableVMs:
```shell_session
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true [user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
```
### Create the sys-net DisposableVM ### Create the sys-net DisposableVM
1. Create `sys-net` DisposableVM based on the DisposableVM Template: 1. Create `sys-net` DisposableVM based on the DisposableVM Template:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
```
2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/): 2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm [user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
```
3. Set `disp-sys-net` to provide network for other VMs: 3. Set `disp-sys-net` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true [user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
```
4. Set `disp-sys-net` NetVM to none: 4. Set `disp-sys-net` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm "" [user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
```
5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`: 5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
```shell_session
[user@dom0 ~]$ qvm-pci [user@dom0 ~]$ qvm-pci
```
6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/): 6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/):
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf> [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
```
7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots: 7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true [user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
```
8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): 8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm '' [user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
```
9. _(optional)_ Set `disp-sys-net` as the dom0 time source: 9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
```shell_session
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net [user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
```
10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`. 10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
@ -214,110 +238,147 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
1. Create `sys-firewall` DisposableVM: 1. Create `sys-firewall` DisposableVM:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall [user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
```
2. Set `disp-sys-firewall` to provide network for other VMs: 2. Set `disp-sys-firewall` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true [user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
```
3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`: 3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net [user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```
4. Set `disp-sys-firewall` as NetVM for other AppVMs: 4. Set `disp-sys-firewall` as NetVM for other AppVMs:
```shell_session
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall [user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
```
5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots: 5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true [user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
```
6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): 6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm '' [user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
```
7. _(optional)_ Set `disp-sys-firewall` as the default NetVM: 7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
```shell_session
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall [user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```
### Create the sys-usb DisposableVM ### Create the sys-usb DisposableVM
1. Create the `disp-sys-usb`: 1. Create the `disp-sys-usb`:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb [user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
```
2. Set the `disp-sys-usb` virtualization mode to hvm: 2. Set the `disp-sys-usb` virtualization mode to hvm:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm [user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
```
3. Set `disp-sys-usb` NetVM to none: 3. Set `disp-sys-usb` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb netvm "" [user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
```
4. List all available PCI devices: 4. List all available PCI devices:
```shell_session
[user@dom0 ~]$ qvm-pci [user@dom0 ~]$ qvm-pci
```
5. Attach the USB controller to the `disp-sys-usb`: 5. Attach the USB controller to the `disp-sys-usb`:
>_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset). >_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset).
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf> [user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
```
6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots: 6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true [user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
```
7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template): 7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm '' [user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
```
8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0). 8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0).
9. At this point, your mouse may not work. 9. At this point, your mouse may not work.
Edit the `qubes.InputMouse` policy file in dom0, which is located here: Edit the `qubes.InputMouse` policy file in dom0, which is located here:
```
/etc/qubes-rpc/policy/qubes.InputMouse /etc/qubes-rpc/policy/qubes.InputMouse
```
Add a line like this to the top of the file: Add a line like this to the top of the file:
```
disp-sys-usb dom0 allow,user=root disp-sys-usb dom0 allow,user=root
```
### Starting the DisposableVMs ### Starting the DisposableVMs
Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start. Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start.
Detach PCI device from VM: Detach PCI device from VM:
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
```shell_session
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
```
### Troubleshooting ### Troubleshooting
If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues). If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
## Deleting DisposableVMs ## Deleting DisposableVMs
While working in a DisposableVM, you may want to open a document in another DisposableVM. While working in a DisposableVM, you may want to open a document in another DisposableVM.
For this reason, the property `default_dispvm` may be set to the name of your DisposableVM in a number of VMs: For this reason, the property `default_dispvm` may be set to the name of your DisposableVM in a number of VMs:
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm ```shell_session
default_dispvm - custom-disposablevm-template [user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-disposablevm-template
```
This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property: This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property:
[user@dom0 ~]$ qvm-prefs workvm default_dispvm "" ```shell_session
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
```
You can then delete the DisposableVM Template: You can then delete the DisposableVM Template:
[user@dom0 ~]$ qvm-remove custom-disposablevm-template ```shell_session
This will completely remove the selected VM(s) [user@dom0 ~]$ qvm-remove custom-disposablevm-template
This will completely remove the selected VM(s)
custom-disposablevm-template custom-disposablevm-template
```
If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you: If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you:
[user@dom0 ~]$ journalctl | tail ```shell_session
[user@dom0 ~]$ journalctl | tail
```

1
user/advanced-configuration/gui-configuration.md
View File

@ -52,4 +52,3 @@ EndSection
## GUI Troubleshooting ## GUI Troubleshooting
See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them. See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them.

32
user/advanced-configuration/i3.md
View File

@ -15,7 +15,9 @@ i3 is part of the stable repository (as of Qubes R3.1) and can be installed by
using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3 using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3
window manager and the its Qubes specific configuration: window manager and the its Qubes specific configuration:
$ sudo qubes-dom0-update i3 i3-settings-qubes ```shell_session
$ sudo qubes-dom0-update i3 i3-settings-qubes
```
The Qubes-specific configuration (package `i3-settings-qubes`) can be installed The Qubes-specific configuration (package `i3-settings-qubes`) can be installed
optionally in case you would prefer writing your own configuration (see optionally in case you would prefer writing your own configuration (see
@ -43,7 +45,9 @@ installed through the package manager.
Clone the i3-qubes repository here: Clone the i3-qubes repository here:
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3 ```shell_session
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
```
In this case, the most interesting file is probably In this case, the most interesting file is probably
`i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch `i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch
@ -59,15 +63,19 @@ it.
You'll need to install the build dependencies, which are listed in You'll need to install the build dependencies, which are listed in
build-deps.list. You can verify them and then install them with: build-deps.list. You can verify them and then install them with:
$ sudo dnf install -y $(cat build-deps.list) ```shell_session
$ sudo dnf install -y $(cat build-deps.list)
```
This used to be more complicated, but I finally redid this and use the same This used to be more complicated, but I finally redid this and use the same
buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps
you get the sources and start off the build: you get the sources and start off the build:
$ make get-sources ```shell_session
$ make verify-sources $ make get-sources
$ make rpms $ make verify-sources
$ make rpms
```
### Installing ### Installing
@ -79,17 +87,23 @@ next step.
Now in dom0, copy in the rpm: Now in dom0, copy in the rpm:
$ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm ```shell_session
$ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm
```
Now that the rpm is in dom0 we can proceed with installing it. i3 has some Now that the rpm is in dom0 we can proceed with installing it. i3 has some
dependencies that we can easily install with: dependencies that we can easily install with:
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\ ```shell_session
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\ rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
dzen2 dmenu xorg-x11-fonts-misc libev dzen2 dmenu xorg-x11-fonts-misc libev
```
After that you can just install the generated rpm like any other local package: After that you can just install the generated rpm like any other local package:
$ sudo yum localinstall i3.rpm ```shell_session
$ sudo yum localinstall i3.rpm
```
Log out, select i3, then log in again. Log out, select i3, then log in again.

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

@ -9,7 +9,6 @@ permalink: /doc/installing-contributed-packages/
_This page is for users who wish to install 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]._
Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project. 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]. This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
@ -19,20 +18,28 @@ If you want to install one of these packages, first you need to enable the repos
In dom0, use `qubes-dom0-update`: In dom0, use `qubes-dom0-update`:
sudo qubes-dom0-update qubes-repo-contrib ```bash_session
sudo qubes-dom0-update qubes-repo-contrib
```
In a Fedora-based template, use `dnf`: In a Fedora-based template, use `dnf`:
sudo dnf install qubes-repo-contrib ```bash_session
sudo dnf install qubes-repo-contrib
```
In a Debian-based template, use `apt`: In a Debian-based template, use `apt`:
sudo apt update && sudo apt install qubes-repo-contrib ```bash_session
sudo apt update && sudo apt install qubes-repo-contrib
```
The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM. The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM.
For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be: For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be:
/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo ```
/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo
```
## Installing packages ## Installing packages
@ -42,10 +49,11 @@ After you've installed the repositories, you can install contributed packages.
For example, to install `qvm-screenshot-tool` in dom0: For example, to install `qvm-screenshot-tool` in dom0:
sudo qubes-dom0-update --clean qvm-screenshot-tool ```bash_session
sudo qubes-dom0-update --clean qvm-screenshot-tool
```
Please see the package's README for specific installation and setup instructions. Please see the package's README for specific installation and setup instructions.
[package contributions]: /doc/package-contributions/ [package contributions]: /doc/package-contributions/
[QubesOS-contrib]: https://github.com/QubesOS-contrib/ [QubesOS-contrib]: https://github.com/QubesOS-contrib/

28
user/advanced-configuration/kde.md
View File

@ -15,30 +15,32 @@ Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is
still possible to install KDE by issuing this command in dom0: still possible to install KDE by issuing this command in dom0:
$ sudo qubes-dom0-update @kde-desktop-qubes ```shell_session
$ sudo qubes-dom0-update @kde-desktop-qubes
```
You can also change your default login manager (lightdm) to the new KDE default: sddm You can also change your default login manager (lightdm) to the new KDE default: sddm
* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs: * first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
~~~ ~~~
[XDisplay] [XDisplay]
ServerArguments=-nolisten tcp -background none ServerArguments=-nolisten tcp -background none
~~~ ~~~
* disable the lightdm service: * disable the lightdm service:
~~~ ~~~
$ sudo systemctl disable lightdm $ sudo systemctl disable lightdm
~~~ ~~~
* enable the sddm service: * enable the sddm service:
~~~ ~~~
$ sudo systemctl enable sddm $ sudo systemctl enable sddm
~~~ ~~~
* reboot * reboot
If you encounter performance issues with KDE, try switching back to LightDM. If you encounter performance issues with KDE, try switching back to LightDM.
@ -77,12 +79,12 @@ Removal
If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system. If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system.
The safest way to remove (most of) KDE is: The safest way to remove (most of) KDE is:
~~~ ~~~
sudo dnf remove kdelibs plasma-workspace sudo dnf remove kdelibs plasma-workspace
~~~ ~~~
Mailing List Threads Mailing List Threads
-------------------- --------------------
* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion) * [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)

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

@ -6,8 +6,7 @@ redirect_from:
- /en/doc/managing-vm-kernel/ - /en/doc/managing-vm-kernel/
--- ---
VM kernel managed by dom0 # VM kernel managed by dom0
=========================
By default, VMs kernels are provided by dom0. By default, VMs kernels are provided by dom0.
(See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.) (See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
@ -58,8 +57,7 @@ nopat
[user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor" [user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor"
~~~ ~~~
Installing different kernel using Qubes kernel package ## Installing different kernel using Qubes kernel package
----------------------------------
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages. VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
Generally, the system will keep the three newest available versions. Generally, the system will keep the three newest available versions.
@ -150,8 +148,7 @@ Installation of the new package is unaffected by this event.
The newly installed package is set as the default VM kernel. The newly installed package is set as the default VM kernel.
Installing different VM kernel based on dom0 kernel ## Installing different VM kernel based on dom0 kernel
---------------------------------------------------
It is possible to package a kernel installed in dom0 as a VM kernel. It is possible to package a kernel installed in dom0 as a VM kernel.
This makes it possible to use a VM kernel which is not packaged by Qubes team. This makes it possible to use a VM kernel which is not packaged by Qubes team.
@ -217,20 +214,18 @@ mke2fs 1.42.12 (29-Aug-2014)
--> Done. --> Done.
~~~ ~~~
Kernel files structure ## Kernel files structure
-----------------------
Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there: Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there:
- `vmlinuz` - kernel binary (may not be a Linux kernel) * `vmlinuz` - kernel binary (may not be a Linux kernel)
- `initramfs` - initramfs for the kernel to load * `initramfs` - initramfs for the kernel to load
- `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain) * `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature) * `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present. All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present.
Using kernel installed in the VM ## Using kernel installed in the VM
--------------------------------
Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then: Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then:
@ -278,6 +273,7 @@ If you require `PV` mode, install `grub2-xen` in dom0 and change the template's
Booting to a kernel inside the template is not supported under `PVH`. Booting to a kernel inside the template is not supported under `PVH`.
### Installing kernel in Debian VM ### Installing kernel in Debian VM
#### Distribution kernel #### Distribution kernel
Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM. Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM.
@ -292,7 +288,6 @@ sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-sup
If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".) If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".)
You can safely ignore this error message: You can safely ignore this error message:
`grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map` `grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map`
@ -320,43 +315,50 @@ Start the VM.
The process of using Qubes VM kernel with distribution kernel is complete. The process of using Qubes VM kernel with distribution kernel is complete.
#### Custom kernel #### Custom kernel
Any kernel can be installed. Just make sure to install kernel headers as well. Any kernel can be installed. Just make sure to install kernel headers as well.
If you are building the kernel manually, do this using `dkms` and `initramfs-tools`. If you are building the kernel manually, do this using `dkms` and `initramfs-tools`.
Run DKMS. Replace this <kernel-version> with actual kernel version. Run DKMS. Replace this <kernel-version> with actual kernel version.
sudo dkms autoinstall -k <kernel-version> ```bash_session
sudo dkms autoinstall -k <kernel-version>
```
For example. For example.
sudo dkms autoinstall -k 4.19.0-6-amd64 ```bash_session
sudo dkms autoinstall -k 4.19.0-6-amd64
```
Update initramfs. Update initramfs.
sudo update-initramfs -u ```bash_session
sudo update-initramfs -u
```
The output should look like this: The output should look like this:
$ sudo dkms autoinstall -k 3.16.0-4-amd64 ```shell_session
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn: u2mfn:
Running module version sanity check. Running module version sanity check.
- Original module - Original module
- No original module exists within this kernel - No original module exists within this kernel
- Installation - Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/ - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod.... depmod....
DKMS: install completed. DKMS: install completed.
$ sudo update-initramfs -u $ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
```
#### Troubleshooting #### Troubleshooting
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. 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 [dom0-kernel-upgrade]: /doc/software-update-dom0/#kernel-upgrade

12
user/advanced-configuration/mount-from-other-os.md
View File

@ -26,7 +26,8 @@ Decrypting the Disk
1. Find the disk to be accessed: 1. Find the disk to be accessed:
1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following. 1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following.
In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`. In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`.
```
```
sda 8:0 0 111.8G 0 disk sda 8:0 0 111.8G 0 disk
├─sda1 8:1 0 200M 0 part /boot/efi ├─sda1 8:1 0 200M 0 part /boot/efi
├─sda2 8:2 0 1G 0 part /boot ├─sda2 8:2 0 1G 0 part /boot
@ -36,7 +37,7 @@ Decrypting the Disk
│ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm
│ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm /
│ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm │ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm
│ ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm
├─qubes_dom0-pool00_tdata 253:2 0 84.4G 0 lvm ├─qubes_dom0-pool00_tdata 253:2 0 84.4G 0 lvm
│ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm │ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm
│ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm / │ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm /
@ -50,7 +51,7 @@ Decrypting the Disk
nvme0n1 259:0 0 465.8G 0 disk nvme0n1 259:0 0 465.8G 0 disk
├─nvme0n1p1 259:1 0 1G 0 part ├─nvme0n1p1 259:1 0 1G 0 part
└─nvme0n1p2 259:2 0 464.8G 0 part └─nvme0n1p2 259:2 0 464.8G 0 part
``` ```
2. Decrypt the disk using the command `cryptsetup luksOpen /dev/<disk>`. 2. Decrypt the disk using the command `cryptsetup luksOpen /dev/<disk>`.
@ -72,7 +73,7 @@ Mounting the disk
5. Find the disk to be accessed. The `lsblk` command above may be of use. The following rules apply by default: 5. Find the disk to be accessed. The `lsblk` command above may be of use. The following rules apply by default:
| Disk name | Data type | Explination | | Disk name | Data type | Explanation |
| ----------------------------- | ----------------- | ------------------------------------------- | | ----------------------------- | ----------------- | ------------------------------------------- |
| other\_install/root | dom0 root | The root partition of dom0. | | other\_install/root | dom0 root | The root partition of dom0. |
| other\_install/<vm>-private | VM | The /rw partition of the named VM. | | other\_install/<vm>-private | VM | The /rw partition of the named VM. |
@ -87,11 +88,10 @@ At this point, all files are available in the chosen mountpoint.
Reverting Changes Reverting Changes
----------------------------------------- -----------------------------------------
Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot. Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot.
However, LVM will not allow an VG to be renamed to a name already in use. However, LVM will not allow an VG to be renamed to a name already in use.
Thes steps must occur either in an AppVM or using recovery media. Thes steps must occur either in an AppVM or using recovery media.
1. Unmount any disks that were accessed. 1. Unmount any disks that were accessed.
2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`. 2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`.

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

@ -11,8 +11,7 @@ redirect_from:
- /wiki/ResizeRootDiskImage/ - /wiki/ResizeRootDiskImage/
--- ---
Resizing Disk Images ## Resizing Disk Images
-----------------
By default Qubes uses thin volumes for the disk images. By default Qubes uses thin volumes for the disk images.
This means that space is not actually allocated for the volume until it is used. This means that space is not actually allocated for the volume until it is used.
@ -24,8 +23,7 @@ You should keep an eye on the disk-space widget to see how much free space you a
It is easy to increase the size of disk images. It is easy to increase the size of disk images.
There are risks attached to reducing the size of an image, and in general you should not need to do this. There are risks attached to reducing the size of an image, and in general you should not need to do this.
Increasing the size of Disk Images ## Increasing the size of Disk Images
----------------------------------
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images. There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size. In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size.
@ -45,7 +43,9 @@ Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you
~~~ ~~~
qvm-volume extend <vm_name>:root <size> qvm-volume extend <vm_name>:root <size>
~~~ ~~~
OR OR
~~~ ~~~
qvm-volume extend <vm_name>:private <size> qvm-volume extend <vm_name>:private <size>
~~~ ~~~
@ -63,7 +63,7 @@ If you are **not** using Linux in the qube, you will also need to:
3. Verify available space in the template using `df -h` or OS specific tools. 3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template. 4. Shutdown the template.
#### Windows 7 #### #### Windows 7
1. Click Start 1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management 2. type "diskmgmt.msc" - this takes you to Disk Management
@ -87,8 +87,7 @@ Qubes will automatically grow the filesystem for you on all AppVMs with Qubes pa
Otherwise, you will see that there is unallocated free space at the end of your primary disk. Otherwise, you will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like `fdisk` and `resize2fs` to make this space available. You can use standard linux tools like `fdisk` and `resize2fs` to make this space available.
Decreasing the size of Disk Images ## Decreasing the size of Disk Images
----------------------------------
The number shown for "storage max size" does not mean that the storage is really using that amount. In most cases you need not worry about the size shown. The number shown for "storage max size" does not mean that the storage is really using that amount. In most cases you need not worry about the size shown.
If you have increased the max size, and do not need it, then you *can* reduce the allocated size, but there is a risk of data loss. If you have increased the max size, and do not need it, then you *can* reduce the allocated size, but there is a risk of data loss.
@ -96,10 +95,10 @@ Remember you really dont need to do this.
You can create a new qube, copy your files in to the new qube, and delete the old qube. (Simple and effective.) You can create a new qube, copy your files in to the new qube, and delete the old qube. (Simple and effective.)
Or you can take the risk of reducing the size of the disk. Or you can take the risk of reducing the size of the disk.
For example, to reduce the private storage of qube1 to 1GiB: For example, to reduce the private storage of qube1 to 1GiB:
Open a terminal in dom0: Open a terminal in dom0:
``` ```
qvm-shutdown qube1 qvm-shutdown qube1
sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
@ -108,8 +107,3 @@ 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][fstrim] for information on using fstrim.
[fstrim]: /doc/disk-trim [fstrim]: /doc/disk-trim

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

@ -58,4 +58,3 @@ Further details about how this system works can be found in [Qrexec: command exe
For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*) For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)
[qrexec3]: /doc/qrexec3/ [qrexec3]: /doc/qrexec3/

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

@ -85,10 +85,10 @@ 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][salt-doc-states].
There are many very useful states: There are many very useful states:
* For [managing files][salt-doc-states-file]: Use this to create files or - For [managing files][salt-doc-states-file]: Use this to create files or
directories and change them (append lines, replace text, set their content etc.) directories and change them (append lines, replace text, set their content etc.)
* For [installing and uninstalling][salt-doc-states-pkg] packages. - For [installing and uninstalling][salt-doc-states-pkg] packages.
* For [executing shell commands][salt-doc-states-cmd]. - For [executing shell commands][salt-doc-states-cmd].
With these three states you can define most of the configuration of a VM. With these three states you can define most of the configuration of a VM.
@ -157,19 +157,27 @@ with a `.` in their name.
Now, because we use custom extensions to manage top files (instead of just Now, because we use custom extensions to manage top files (instead of just
enabling them all), to enable a particular top file you should issue command: enabling them all), to enable a particular top file you should issue command:
$ qubesctl top.enable my-new-vm ```
$ qubesctl top.enable my-new-vm
```
To list all enabled top files: To list all enabled top files:
$ qubesctl top.enabled ```
$ qubesctl top.enabled
```
And to disable one: And to disable one:
$ qubesctl top.disable my-new-vm ```
$ qubesctl top.disable my-new-vm
```
To apply the states to dom0 and all VMs: To apply the states to dom0 and all VMs:
$ qubesctl --all state.highstate ```
$ qubesctl --all state.highstate
```
(More information on the `qubesctl` command further down.) (More information on the `qubesctl` command further down.)
@ -228,7 +236,6 @@ If you do so, then you need to pass additional arguments to the `qubesctl` tool:
--app Target all AppVMs --app Target all AppVMs
--all Target all non-disposable VMs (TemplateVMs and AppVMs) --all Target all non-disposable VMs (TemplateVMs and AppVMs)
To apply a state to all templates, call `qubesctl --templates state.highstate`. To apply a state to all templates, call `qubesctl --templates state.highstate`.
The actual configuration is applied using `salt-ssh` (running over `qrexec` The actual configuration is applied using `salt-ssh` (running over `qrexec`
@ -273,14 +280,14 @@ Let's start with a quick example:
It uses the Qubes-specific `qvm.present` state, which ensures that the domain is It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
present (if not, it creates it). present (if not, it creates it).
* The `name` flag informs Salt that the domain should be named `salt-test` (not - The `name` flag informs Salt that the domain should be named `salt-test` (not
`my new and shiny VM`). `my new and shiny VM`).
* The `template` flag informs Salt which template should be used for the domain. - The `template` flag informs Salt which template should be used for the domain.
* The `label` flag informs Salt what color the domain should be. - The `label` flag informs Salt what color the domain should be.
* The `mem` flag informs Salt how much RAM should be allocated to the domain. - The `mem` flag informs Salt how much RAM should be allocated to the domain.
* The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the - The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
domain domain
* The `proxy` flag informs Salt that the domain should be a ProxyVM. - The `proxy` flag informs Salt that the domain should be a ProxyVM.
As you will notice, the options are the same (or very similar) to those used in As you will notice, the options are the same (or very similar) to those used in
`qvm-prefs`. `qvm-prefs`.
@ -297,11 +304,15 @@ without the `.sls` extension.
To enable the particular top file you should issue the command: To enable the particular top file you should issue the command:
$ qubesctl top.enable my-new-vm ```
$ qubesctl top.enable my-new-vm
```
To apply the state: To apply the state:
$ qubesctl state.highstate ```
$ qubesctl state.highstate
```
### Example of Configuring a VM's System from Dom0 ### Example of Configuring a VM's System from Dom0
@ -321,11 +332,15 @@ Then the appropriate top file (`/srv/salt/mc-everywhere.top`):
Now you need to enable the top file: Now you need to enable the top file:
$ qubesctl top.enable mc-everywhere ```
$ qubesctl top.enable mc-everywhere
```
And apply the configuration: And apply the configuration:
$ qubesctl --all state.highstate ```
$ qubesctl --all state.highstate
```
## All Qubes-specific States ## All Qubes-specific States
@ -369,15 +384,16 @@ Ensures the specified domain is running:
qvm.running: qvm.running:
- name: salt-test4 - name: salt-test4
## Virtual Machine Formulae ## Virtual Machine Formulae
You can use these formulae to download, install, and configure VMs in Qubes. You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details. These formulae use pillar data to define default VM names and configuration details.
The default settings can be overridden in the pillar data located in: The default settings can be overridden in the pillar data located in:
``` ```
/srv/pillar/base/qvm/init.sls /srv/pillar/base/qvm/init.sls
``` ```
In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`. In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`). For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`).
@ -472,16 +488,18 @@ Updates dom0
Updates domUs. Example to update all TemplateVMs: Updates domUs. Example to update all TemplateVMs:
sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm ```
sudo qubesctl --skip-dom0 --templates state.sls update.qubes-vm
```
Useful options: Useful options:
- `--max-concurrency` --- Limits how many templates are updated at the same time. - `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM. Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1. The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them. - `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
(Use instead of `--templates` or `--standalones`.) (Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL. - `--show-output` --- Show an update summary instead of just OK/FAIL.
For other options, see `qubesctl --help`. For other options, see `qubesctl --help`.
@ -495,10 +513,10 @@ Additional pillar data is available to ease targeting configurations (for exampl
VM type. Possible values: VM type. Possible values:
- `admin` - Administration domain (`dom0`) - `admin` - Administration domain (`dom0`)
- `template` - Template VM - `template` - Template VM
- `standalone` - Standalone VM - `standalone` - Standalone VM
- `app` - Template based AppVM - `app` - Template based AppVM
### `qubes:template` ### `qubes:template`
@ -508,7 +526,6 @@ Template name on which a given VM is based (if any).
VM which provides network to the given VM VM which provides network to the given VM
## Debugging ## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`. The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
@ -521,8 +538,10 @@ If the log does not contain useful information:
executed in the management VM. executed in the management VM.
5. Get the last two lines: 5. Get the last two lines:
```shell_session
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH" $ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command $ salt-ssh "$target_vm" $salt_command
```
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate). Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
6. Execute them, fix problems, repeat. 6. Execute them, fix problems, repeat.
@ -534,7 +553,9 @@ If the log does not contain useful information:
The fedora-24-minimal package is missing the `sudo` package. The fedora-24-minimal package is missing the `sudo` package.
You can install it via: You can install it via:
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo' ```shell_session
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
```
The `-p` will cause the execution to wait until the package is installed. The `-p` will cause the execution to wait until the package is installed.
Having the `-p` flag is important when using a state with `cmd.run`. Having the `-p` flag is important when using a state with `cmd.run`.
@ -550,13 +571,13 @@ The solution is to shut down the updateVM between each install:
## Further Reading ## Further Reading
* [Salt documentation][salt-doc] - [Salt documentation][salt-doc]
* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd], - [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]) [packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
* [Top files][salt-doc-top] - [Top files][salt-doc-top]
* [Jinja templates][jinja] - [Jinja templates][jinja]
* [Qubes specific modules][salt-qvm-doc] - [Qubes specific modules][salt-qvm-doc]
* [Formulas for default Qubes VMs][salt-virtual-machines-states] - [Formulas for default Qubes VMs][salt-virtual-machines-states]
[salt-doc]: https://docs.saltstack.com/en/latest/ [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-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst

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

@ -8,13 +8,12 @@ redirect_from:
- /wiki/SecondaryStorage/ - /wiki/SecondaryStorage/
--- ---
Storing AppVMs on Secondary Drives # Storing AppVMs on Secondary Drives
==================================
Suppose you have a fast but small primary SSD and a large but slow secondary HDD. Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
You want to store a subset of your AppVMs on the HDD. You want to store a subset of your AppVMs on the HDD.
## Instructions ## ## Instructions
Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks. Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
For example, you can keep templates on one disk and AppVMs on another, without messy symlinks. For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
@ -24,70 +23,94 @@ See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-s
First, collect some information in a dom0 terminal: First, collect some information in a dom0 terminal:
sudo pvs ```
sudo lvs sudo pvs
sudo lvs
```
Take note of the VG and thin pool names for your HDD, then register it with Qubes: Take note of the VG and thin pool names for your HDD, then register it with Qubes:
# <pool_name> is a freely chosen pool name ```shell_session
# <vg_name> is LVM volume group name # <pool_name> is a freely chosen pool name
# <thin_pool_name> is LVM thin pool name # <vg_name> is LVM volume group name
qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2 # <thin_pool_name> is LVM thin pool name
qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
```
Now, you can create qubes in that pool: Now, you can create qubes in that pool:
qvm-create -P <pool_name> --label red <vmname> ```
qvm-create -P <pool_name> --label red <vmname>
```
It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one: It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one:
qvm-clone -P <pool_name> <sourceVMname> <cloneVMname> ```
qvm-remove <sourceVMname> qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
qvm-remove <sourceVMname>
```
If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving. If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
For example: For example:
qvm-prefs <appvmname_based_on_old_template> template <new_template_name> ```
qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
```
In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube. In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
### Example HDD setup ### ### Example HDD setup
Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot): Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb ```
sudo blkid /dev/sdb sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
sudo blkid /dev/sdb
```
Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing: Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
sudo nano /etc/crypttab ```
sudo nano /etc/crypttab
```
And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab: And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none ```
luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
```
Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours): Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
First create the physical volume First create the physical volume
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde ```
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
```
Then create the LVM volume group, we will use for example "qubes" as the <vg_name>: Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde ```
sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
```
And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name): And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
sudo lvcreate -T -n poolhd0 -l +100%FREE qubes ```
sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
```
Finally we will tell Qubes to add a new pool on the just created thin pool Finally we will tell Qubes to add a new pool on the just created thin pool
qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 ```
qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
```
By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal: By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
qvm-create -P poolhd0_qubes --label red unstrusted-hdd ```
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```
[Qubes Backup]: /doc/BackupRestore/ [Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/ [TemplateVM]: /doc/Templates/

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

@ -16,7 +16,6 @@ If during installation you enabled the creation of a USB-qube, your system shoul
**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]!
## Creating and Using a USB qube ## ## Creating and Using a USB qube ##
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB. **Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
@ -29,31 +28,32 @@ The USB controller may be assigned on the **Devices** tab of a qube's settings p
For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller]. For guidance on finding the correct USB controller, see the [according passage on PCI-devices][usb-controller].
You can create a USB qube using the management stack by performing the following steps as root in dom0: You can create a USB qube using the management stack by performing the following steps as root in dom0:
sudo qubesctl state.sls qvm.sys-usb ```
sudo qubesctl state.sls qvm.sys-usb
```
Alternatively, you can create a USB qube manually as follows: 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] 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. 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. 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. If you find a free controller, note its name and proceed to step 2.
2. Create a new qube. 2. Create a new qube.
Give it an appropriate name and color label (recommended: `sys-usb`, red). Give it an appropriate name and color label (recommended: `sys-usb`, red).
3. In the qube's settings, go to the "Devices" tab. 3. In the qube's settings, go to the "Devices" tab.
Find the USB controller that you identified in step 1 in the "Available" list. Find the USB controller that you identified in step 1 in the "Available" list.
Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button. Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
**Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0. **Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive. This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive.
4. Click `OK`. 4. Click `OK`.
Restart the qube. Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot". 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.) (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].
## Enable a USB keyboard for login ## ## 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] before proceeding!
@ -62,12 +62,13 @@ If you use USB keyboard, automatic USB qube creation during installation is disa
Additional steps are required to avoid locking you out from the system. 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].
### Automatic setup ### ### 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]) and execute in dom0:
sudo qubesctl state.sls qvm.usb-keyboard ```
sudo qubesctl state.sls qvm.usb-keyboard
```
The above command will take care of all required configuration, including creating USB qube if not present. The above command will take care of all required configuration, including creating USB qube if not present.
Note that it will expose dom0 to USB devices while entering LUKS passphrase. Note that it will expose dom0 to USB devices while entering LUKS passphrase.
@ -77,17 +78,20 @@ To undo these changes, please follow the section on [**Removing a USB qube**][re
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below. If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
### Manual setup ### ### Manual setup ###
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here: Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputKeyboard ```
/etc/qubes-rpc/policy/qubes.InputKeyboard
```
Add a line like this one to the top of the file: Add a line like this one to the top of the file:
sys-usb dom0 allow ```
sys-usb dom0 allow
```
(Change `sys-usb` to your desired USB qube.) (Change `sys-usb` to your desired USB qube.)
@ -95,14 +99,15 @@ You can now use your USB keyboard to login and for LUKS decryption during boot.
For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to: For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to:
sys-usb dom0 ask,default_target=dom0 ```
sys-usb dom0 ask,default_target=dom0
```
*Don't do that if you want to unlock your device with a USB keyboard!* *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].
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. 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 ## ## 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] before proceeding.
@ -111,21 +116,26 @@ Handling a USB mouse isn't as critical as handling a keyboard, since you can log
If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at: If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at:
/etc/qubes-rpc/policy/qubes.InputMouse ```
/etc/qubes-rpc/policy/qubes.InputMouse
```
The first line should read similar to: The first line should read similar to:
sys-usb dom0 ask,default_target=dom0 ```
sys-usb dom0 ask,default_target=dom0
```
which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0. which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0.
In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file: In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file:
sys-usb dom0 allow ```
sys-usb dom0 allow
```
(Change `sys-usb` to your desired USB qube.) (Change `sys-usb` to your desired USB qube.)
## How to hide all USB controllers from dom0 ## ## 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. (Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
@ -149,7 +159,7 @@ If dom0 cannot read your USB AEM device, AEM will hang.
The procedure to hide all USB controllers from dom0 is as follows: The procedure to hide all USB controllers from dom0 is as follows:
* GRUB2 * GRUB2
1. Open the file `/etc/default/grub` in dom0. 1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`. 2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
@ -158,7 +168,7 @@ The procedure to hide all USB controllers from dom0 is as follows:
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. 5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot. 6. Reboot.
* EFI * EFI
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0. 1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
2. Find the lines that begin with `kernel=`. There may be more than one. 2. Find the lines that begin with `kernel=`. There may be more than one.
@ -166,12 +176,11 @@ The procedure to hide all USB controllers from dom0 is as follows:
4. Save and close the file. 4. Save and close the file.
5. Reboot. 5. Reboot.
## Removing a USB qube ## ## Removing a USB qube ##
**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0. **Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
* GRUB2 * GRUB2
1. Shut down the USB qube. 1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM." 2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
@ -182,7 +191,7 @@ The procedure to hide all USB controllers from dom0 is as follows:
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0. 7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot. 8. Reboot.
* EFI * EFI
1. Shut down the USB qube. 1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM." 2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
@ -192,7 +201,6 @@ The procedure to hide all USB controllers from dom0 is as follows:
6. Save and close the file. 6. Save and close the file.
7. Reboot. 7. Reboot.
[remove your USB-qube]: #removing-a-usb-qube [remove your USB-qube]: #removing-a-usb-qube
[security implications]: /doc/device-handling-security/#usb-security [security implications]: /doc/device-handling-security/#usb-security
[enable your keyboard for login]: #enable-a-usb-keyboard-for-login [enable your keyboard for login]: #enable-a-usb-keyboard-for-login

4
user/common-tasks/backup-emergency-restore-v2.md
View File

@ -123,6 +123,4 @@ encrypted and compressed.
**Note:** You may wish to store a plain text copy of these instructions with **Note:** You may wish to store a plain text copy of these instructions with
your Qubes backups in the event that you fail to recall the above procedure your Qubes backups in the event that you fail to recall the above procedure
while this web page is inaccessible. You may obtain a plaintext version of while this web page is inaccessible. You may obtain a plaintext version of
this file in Git repository housing all the documentation at: this file in Git repository housing all the documentation on [Github](https://github.com/QubesOS/qubes-doc.git)
https://github.com/QubesOS/qubes-doc.git

1
user/common-tasks/backup-emergency-restore-v3.md
View File

@ -137,4 +137,3 @@ any GNU/Linux system with the following procedure.
repository: repository:
https://github.com/QubesOS/qubes-doc.git https://github.com/QubesOS/qubes-doc.git

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

@ -18,7 +18,6 @@ mind. No special Qubes-specific tools are required to access data backed up by
Qubes. In the event a Qubes system is unavailable, you can access your data on Qubes. In the event a Qubes system is unavailable, you can access your data on
any GNU/Linux system with the following procedure. any GNU/Linux system with the following procedure.
Required `scrypt` Utility Required `scrypt` Utility
------------------------- -------------------------
@ -71,7 +70,6 @@ any GNU/Linux system.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt" [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
Emergency Recovery Instructions Emergency Recovery Instructions
------------------------------- -------------------------------
@ -185,4 +183,3 @@ Emergency Recovery Instructions
[get and verify the Release 4 Signing Key]: /security/verifying-signatures/#2-get-the-release-signing-key [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 (v2)]: /doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/ [Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/

22
user/common-tasks/backup-restore.md
View File

@ -83,7 +83,6 @@ Creating a backup
This step is optional but strongly recommended. This step is optional but strongly recommended.
A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore. A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
Restoring from a backup Restoring from a backup
----------------------- -----------------------
@ -128,8 +127,7 @@ If the contents from the dom0 backup were instead to overwrite the existing file
However, if you do wish to move all files from the dom0 backup out of the subdirectory into your current dom0 home directory (overwriting any existing files in the process), you may do so by following the instructions [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via). However, if you do wish to move all files from the dom0 backup out of the subdirectory into your current dom0 home directory (overwriting any existing files in the process), you may do so by following the instructions [here](https://stackoverflow.com/questions/20192070/how-to-move-all-files-including-hidden-files-into-parent-directory-via).
Just remember that this can cause unexpected and desired configuration changes in dom0, depending on exactly which files you're adding and replacing. Just remember that this can cause unexpected and desired configuration changes in dom0, depending on exactly which files you're adding and replacing.
Emergency backup recovery without qubes
Emergency backup recovery without Qubes
--------------------------------------- ---------------------------------------
The Qubes backup system has been designed with emergency disaster recovery in mind. The Qubes backup system has been designed with emergency disaster recovery in mind.
@ -138,10 +136,9 @@ In the event a Qubes system is unavailable, you can access your data on any GNU/
Refer to the following for emergency restore of a backup created on: Refer to the following for emergency restore of a backup created on:
* [Qubes R4 or newer](/doc/backup-emergency-restore-v4/) - [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
* [Qubes R3](/doc/backup-emergency-restore-v3/) - [Qubes R3](/doc/backup-emergency-restore-v3/)
* [Qubes R2 or older](/doc/backup-emergency-restore-v2/) - [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
Migrating between two physical machines Migrating between two physical machines
--------------------------------------- ---------------------------------------
@ -154,18 +151,17 @@ Choosing a backup passphrase
Here are some things to consider when selecting a passphrase for your backups: Here are some things to consider when selecting a passphrase for your backups:
* If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase. - If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase. (Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
If your system drive decryption passphrase is already sufficiently strong, it may not.) If your system drive decryption passphrase is already sufficiently strong, it may not.)
* An adversary who has access to your backups may try to substitute one backup for another. - An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM. For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase. If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
* If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong). - If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you. On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
Notes Notes
----- -----
* For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion). - For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
* If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion). - If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

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

@ -9,14 +9,13 @@ redirect_from:
- /wiki/StickMounting/ - /wiki/StickMounting/
--- ---
# Block (Storage) Devices # # Block (Storage) Devices
*This page is part of [device handling in qubes].* *This page is part of [device handling in qubes].*
If you don't know what a "block device" is, just think of it as a fancy way to say "something that stores data". 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
## 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][mass-storage].
In addition to smaller flash memory sticks, this includes things like USB external hard drives.) In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
@ -39,15 +38,16 @@ Click on one and your USB drive will be attached!
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM. However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
See below for more detailed steps. See below for more detailed steps.
## Block Devices in VMs
## Block Devices in VMs ##
If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number.
If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute:
cd ~ ```
mkdir mnt cd ~
sudo mount /dev/xvdi2 mnt mkdir mnt
sudo mount /dev/xvdi2 mnt
```
where `xvdi2` needs to be replaced with the partition you want to mount. where `xvdi2` needs to be replaced with the partition you want to mount.
This will make your drive content accessible under `~/mnt`. This will make your drive content accessible under `~/mnt`.
@ -58,8 +58,7 @@ If several different block-devices are attached to a single VM, the last letter
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
## Command Line Tool Guide ##
The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`.
@ -69,76 +68,89 @@ So make sure you have the drive available in the sourceVM, then list the availab
In case of a USB-drive, make sure it's attached to your computer. In case of a USB-drive, make sure it's attached to your computer.
If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`)
1. In a dom0 console (running as a normal user), list all available block devices: 1. In a dom0 console (running as a normal user), list all available block devices:
```
qvm-block qvm-block
```
This will list all available block devices in your system across all VMs. This will list all available block devices in your system across all VMs.
The name of the qube hosting the block device is displayed before the colon in the device ID. The name of the qube hosting the block device is displayed before the colon in the device ID.
The string after the colon is the ID of the device used within the qube, like so: The string after the colon is the ID of the device used within the qube, like so:
```
sourceVM:sdb Cruzer () 4GiB sourceVM:sdb Cruzer () 4GiB
sourceVM:sdb1 Disk () 2GiB sourceVM:sdb1 Disk () 2GiB
```
2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so: 2. Assuming your block device is attached to `sys-usb` and its device node is `sdb`, we attach the device to a qube with the name `work` like so:
```
qvm-block attach work sys-usb:sdb qvm-block attach work sys-usb:sdb
```
This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc.
You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`.
3. The block device is now attached to the qube. 3. The block device is now attached to the qube.
If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left.
If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible: If you've attached a single partition (e.g. `sdb2` instead of `sdb` in our example), you may need to manually mount before it becomes visible:
```
cd ~ cd ~
mkdir mnt mkdir mnt
sudo mount /dev/xvdi mnt sudo mount /dev/xvdi mnt
```
4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
If you've manually mounted a single partition in the above step, use: If you've manually mounted a single partition in the above step, use:
```
sudo umount mnt sudo umount mnt
```
5. In a dom0 console, detach the device 5. In a dom0 console, detach the device
```
qvm-block detach work sys-usb:sdb qvm-block detach work sys-usb:sdb
```
6. You may now remove the device or attach it to another qube. 6. You may now remove the device or attach it to another qube.
## Recovering From Premature Device Destruction
## 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][premature removal].
To recover from this error state, in dom0 run To recover from this error state, in dom0 run
virsh detach-disk targetVM xvdi ```
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. 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?
### 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] 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. 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: If this isn't an option, you can manually recover from the situation by following these steps:
1. Physically connect the device back. 1. Physically connect the device back.
You can use any device as long as it will be detected under the same name (for example, `sdb`). You can use any device as long as it will be detected under the same name (for example, `sdb`).
2. Attach the device manually to the same VM using the `xl block-attach` command. 2. Attach the device manually to the same VM using the `xl block-attach` command.
It is important to use the same "frontend" device name (by default, `xvdi`). It is important to use the same "frontend" device name (by default, `xvdi`).
You can get it from the `qvm-block` listing: You can get it from the `qvm-block` listing:
```shell_session
[user@dom0 ~]$ qvm-block [user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi') sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi [user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi
```
In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`. In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
In order: In order:
@ -148,21 +160,22 @@ If this isn't an option, you can manually recover from the situation by followin
* `backend=sys-usb` - name of source qube, can be omitted in the case of dom0 * `backend=sys-usb` - name of source qube, can be omitted in the case of dom0
* `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output) * `xvdi` - "frontend" device name (listed at the end of line in `qvm-block` output)
3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command. 3. Now properly detach the device, either using Qubes VM Manager or the `qvm-block -d` command.
## Attaching a File
## Attaching a File ##
To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM. To attach a file as block device to another qube, first turn it into a loopback device inside the sourceVM.
1. In the linux sourceVM run 1. In the linux sourceVM run
```
sudo losetup -f --show /path/to/file 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][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. Afterwards it prints the device-node-name it found.
2. If you want to use the GUI, you're done. 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] and select the `loop0`-device to attach it to another qube.
If you rather use the command line, continue: If you rather use the command line, continue:
@ -170,26 +183,30 @@ To attach a file as block device to another qube, first turn it into a loopback
In dom0, run `qvm-block` to display known block devices. In dom0, run `qvm-block` to display known block devices.
The newly created loop device should show up: The newly created loop device should show up:
```shell_session
~]$ qvm-block ~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY BACKEND:DEVID DESCRIPTION USED BY
sourceVM:loop0 /path/to/file sourceVM:loop0 /path/to/file
```
3. Attach the `loop0`-device using qvm-block as usual: 3. Attach the `loop0`-device using qvm-block as usual:
```
qvm-block a targetVM sourceVM:loop0 qvm-block a targetVM sourceVM:loop0
```
4. After detaching, destroy the loop-device inside the sourceVM as follows: 4. After detaching, destroy the loop-device inside the sourceVM as follows:
```
sudo losetup -d /dev/loop0 sudo losetup -d /dev/loop0
```
## Additional Attach Options
## Additional Attach Options ##
Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option. Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option.
(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
### frontend-dev
### frontend-dev ###
This option allows you to specify the name of the device node made available in the targetVM. This option allows you to specify the name of the device node made available in the targetVM.
This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order.
@ -197,12 +214,13 @@ This defaults to `xvdi` or, if already occupied, the first available device node
usage example: usage example:
qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz ```
qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
```
This command will attach the partition `sda1` to `work` as `/dev/xvdz`. This command will attach the partition `sda1` to `work` as `/dev/xvdz`.
### read-only
### read-only ###
Attach device in read-only mode. Attach device in read-only mode.
Protects the block device in case you don't trust the targetVM. Protects the block device in case you don't trust the targetVM.
@ -211,28 +229,31 @@ If the device is a read-only device, this option is forced true.
usage example: usage example:
qvm-block a work sys-usb:sda1 -o read-only=true ```
qvm-block a work sys-usb:sda1 -o read-only=true
```
There exists a shortcut to set read-only `true`, `--ro`: There exists a shortcut to set read-only `true`, `--ro`:
qvm-block a work sys-usb:sda1 --ro ```
qvm-block a work sys-usb:sda1 --ro
```
The two commands are equivalent. The two commands are equivalent.
### devtype
### devtype ###
Usually, a block device is attached as disk. Usually, a block device is attached as disk.
In case you need to attach a block device as cdrom, this option allows that. In case you need to attach a block device as cdrom, this option allows that.
usage example: usage example:
qvm-block a work sys-usb:sda1 -o devtype=cdrom ```
qvm-block a work sys-usb:sda1 -o devtype=cdrom
```
This option accepts `cdrom` and `disk`, default is `disk`. This option accepts `cdrom` and `disk`, default is `disk`.
[device handling in qubes]: /doc/device-handling/ [device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:/attachment/wiki/Devices/media-removable.png [device manager icon]:/attachment/wiki/Devices/media-removable.png
@ -242,4 +263,3 @@ This option accepts `cdrom` and `disk`, default is `disk`.
[losetup]: https://linux.die.net/man/8/losetup [losetup]: https://linux.die.net/man/8/losetup
[USB]:/doc/usb-devices/ [USB]:/doc/usb-devices/
[1082]: https://github.com/QubesOS/qubes-issues/issues/1082 [1082]: https://github.com/QubesOS/qubes-issues/issues/1082

13
user/common-tasks/copy-from-dom0.md
View File

@ -20,7 +20,9 @@ Since dom0 is special, the processes are different from [copying and pasting tex
To copy a file from dom0 to a VM, simply use `qvm-copy-to-vm`: To copy a file from dom0 to a VM, simply use `qvm-copy-to-vm`:
qvm-copy-to-vm <target_vm> <file> ```
qvm-copy-to-vm <target_vm> <file>
```
The file will arrive in the target VM in the `/home/user/QubesIncoming/dom0/` directory. The file will arrive in the target VM in the `/home/user/QubesIncoming/dom0/` directory.
@ -71,9 +73,12 @@ If you are determined to copy some files to dom0 anyway, you can use the followi
(If you want to copy text, first save it into a text file.) (If you want to copy text, first save it into a text file.)
Run this command in a dom0 terminal: Run this command in a dom0 terminal:
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0 ```
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
```
Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don't want to use `qvm-copy-to-vm`): Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm' ```
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'
```

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

@ -9,7 +9,7 @@ redirect_from:
- /wiki/ExternalDeviceMountPoint/ - /wiki/ExternalDeviceMountPoint/
--- ---
# Device Handling # # Device Handling
This is an overview of device handling in Qubes OS. 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], [USB] and [PCI] devices), please visit their respective pages.
@ -107,13 +107,11 @@ DEVICE_CLASS however is required.
**SYNOPSIS**: **SYNOPSIS**:
`qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
## Actions
## Actions ##
Actions are applicable to every DEVICE_CLASS and expose some additional options. Actions are applicable to every DEVICE_CLASS and expose some additional options.
### Listing Devices
### Listing Devices ###
The `list` action lists known devices in the system. The `list` action lists known devices in the system.
`list` accepts VM-names to narrow down listed devices. `list` accepts VM-names to narrow down listed devices.
@ -121,16 +119,15 @@ Devices available in, as well as attached to the named VMs will be listed.
`list` accepts two options: `list` accepts two options:
- `--all` - equivalent to specifying every VM name after `list`. - `--all` - equivalent to specifying every VM name after `list`.
No VM-name implies `--all`. No VM-name implies `--all`.
- `--exclude` - exclude VMs from `--all`. - `--exclude` - exclude VMs from `--all`.
Requires `--all`. Requires `--all`.
**SYNOPSIS** **SYNOPSIS**
`qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]` `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]`
### Attaching Devices
### Attaching Devices ###
The `attach` action assigns an exposed device to a VM. The `attach` action assigns an exposed device to a VM.
This makes the device available in the VM it's attached to. This makes the device available in the VM it's attached to.
@ -139,15 +136,14 @@ Required argument are targetVM and sourceVM:deviceID.
`attach` accepts two options: `attach` accepts two options:
- `--persistent` - attach device on targetVM-boot. - `--persistent` - attach device on targetVM-boot.
If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
- `--option`, `-o` - set additional options specific to DEVICE_CLASS. - `--option`, `-o` - set additional options specific to DEVICE_CLASS.
**SYNOPSIS** **SYNOPSIS**
`qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]` `qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]`
### Detaching Devices
### Detaching Devices ###
The `detach` action removes an assigned device from a targetVM. The `detach` action removes an assigned device from a targetVM.
It won't be available afterwards anymore. It won't be available afterwards anymore.
@ -160,7 +156,6 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
**SYNOPSIS** **SYNOPSIS**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]` `qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/block-devices/ [block]:/doc/block-devices/
[USB]:/doc/usb-devices/ [USB]:/doc/usb-devices/
[PCI]:/doc/pci-devices/ [PCI]:/doc/pci-devices/
@ -168,4 +163,3 @@ If no specific `sourceVM:deviceID` combination is given, *all devices of that DE
[device manager icon]: /attachment/wiki/Devices/media-removable.png [device manager icon]: /attachment/wiki/Devices/media-removable.png
[eject icon]: /attachment/wiki/Devices/media-eject.png [eject icon]: /attachment/wiki/Devices/media-eject.png
[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692 [i4692]: https://github.com/QubesOS/qubes-issues/issues/4692

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

@ -9,7 +9,7 @@ redirect_from:
- /wiki/DisposableVMs/ - /wiki/DisposableVMs/
--- ---
# DisposableVMs # # DisposableVMs
A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed. A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser. DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser.
@ -24,23 +24,21 @@ While running, DisposableVMs will appear in Qubes VM Manager with the name `disp
This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM. This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
## Security
## Security ##
If a [DisposableVM Template] becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised. If a [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. 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. 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. For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM.
### DisposableVMs and Local Forensics ### ### DisposableVMs and Local Forensics
At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM. At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion). For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/). When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## DisposableVMs and Networking
## DisposableVMs and Networking ##
Similarly to how AppVMs are based on their underlying [TemplateVM](/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](/doc/glossary/#disposablevm-template). Similarly to how AppVMs are based on their underlying [TemplateVM](/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](/doc/glossary/#disposablevm-template).
R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one. R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one.
@ -50,7 +48,9 @@ If you have included the Whonix option in your install, there will also be a `wh
You can set any AppVM to have the ability to act as a DisposableVM Template with: You can set any AppVM to have the ability to act as a DisposableVM Template with:
qvm-prefs <vmname> template_for_dispvms True ```
qvm-prefs <vmname> template_for_dispvms True
```
The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`. The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM Template you specified. By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM Template you specified.
@ -59,7 +59,9 @@ You can change this behaviour for individual VMs: in the Application Menu, open
Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM. Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM.
This can also be changed from the command line with: This can also be changed from the command line with:
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE> ```
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
```
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default. For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings. You can even set an AppVM that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings.
@ -80,14 +82,17 @@ Different DisposableVM Templates with individual NetVM settings can be added to
**Important Notes:** **Important Notes:**
Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command: Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command:
qvm-features <DISPOSABLEVM> appmenus-dispvm 1 ```
qvm-features <DISPOSABLEVM> appmenus-dispvm 1
```
To launch a DisposableVM Template from the command line, in dom0 please type the following: To launch a DisposableVM Template from the command line, in dom0 please type the following:
qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp ```
qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
```
## Opening a file in a DisposableVM via GUI
## Opening a file in a DisposableVM via GUI ##
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "View in DisposableVM" or "Edit in DisposableVM". In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "View in DisposableVM" or "Edit in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content. Wait a few seconds and the default application for this file type should appear displaying the file content.
@ -98,7 +103,7 @@ If you have edited the file and saved the changes, the changed file will be save
![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png) ![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png)
## Opening a fresh web browser instance in a new DisposableVM ## ## Opening a fresh web browser instance in a new DisposableVM
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM. Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**. This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
@ -108,7 +113,7 @@ Once you close the viewing application the whole DisposableVM will be destroyed.
![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png) ![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png)
## Opening a file in a DisposableVM via command line (from AppVM) ## ## Opening a file in a DisposableVM via command line (from AppVM)
Use the `qvm-open-in-dvm` command from a terminal in your AppVM: Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
@ -118,8 +123,7 @@ Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM. Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
## Starting an arbitrary program in a DisposableVM from an AppVM
## Starting an arbitrary program in a DisposableVM from an AppVM ##
Sometimes it can be useful to start an arbitrary program in a DisposableVM. Sometimes it can be useful to start an arbitrary program in a DisposableVM.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited. The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
@ -132,8 +136,7 @@ Starting an arbitrary program can be done from an AppVM by running
The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`. The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
## Starting an arbitrary application in a DisposableVM via command line from dom0
## Starting an arbitrary application in a DisposableVM via command line from dom0 ##
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks. The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited. The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
@ -147,8 +150,7 @@ $ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`. The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.) (The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube
### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube ###
Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home). Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in DisposableVMs. However, sometimes you want to open email links in DisposableVMs.
@ -164,9 +166,11 @@ This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, o
#### Example of RPC policies to allow this behavior #### Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL` In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
~~~ ~~~
@anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow @anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
~~~ ~~~
This line means: This line means:
- FROM: Any VM - FROM: Any VM
- TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` - TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
@ -176,13 +180,11 @@ In other words, any VM will be allowed to create a new DisposableVM based on `<O
More information about RPC policies for DisposableVMs can be found [here][qrexec]. More information about RPC policies for DisposableVMs can be found [here][qrexec].
## Customizing DisposableVMs
## Customizing DisposableVMs ##
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile. You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template. These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/). Full instructions can be found [here](/doc/disposablevm-customization/).
[DisposableVM Template]: /doc/glossary/#disposablevm-template [DisposableVM Template]: /doc/glossary/#disposablevm-template
[qrexec]: /doc/qrexec/#qubes-rpc-administration [qrexec]: /doc/qrexec/#qubes-rpc-administration

1
user/common-tasks/full-screen-mode.md
View File

@ -70,4 +70,3 @@ global: {
~~~ ~~~
Be sure to restart the VM(s) after modifying this file, for the changes to take effect. Be sure to restart the VM(s) after modifying this file, for the changes to take effect.

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

@ -27,10 +27,10 @@ So, creating a large number of qubes is cheap: each one needs only as much disk
If you've installed Qubes OS using the default options, a few qubes have already been created for you: If you've installed Qubes OS using the default options, a few qubes have already been created for you:
- work - work
- personal - personal
- untrusted - untrusted
- vault - vault
Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors. Each qube, apart from having a distinct name, is also assigned a **label**, which is one of several predefined colors.
The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube. The trusted window manager uses these colors in order to draw colored borders around the windows of applications running in each qube.
@ -57,31 +57,29 @@ 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][dom0-precautions].
(That's what your qubes are for!) (That's what your qubes are for!)
GUI and command-line tools GUI and command-line tools
-------------------------- --------------------------
All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal. All aspects of Qubes OS can be controlled using command-line tools run in a dom0 terminal.
Opening a terminal in dom0 can be done in several ways: Opening a terminal in dom0 can be done in several ways:
- Go to the Application Launcher and click **Terminal Emulator**. - Go to the Application Launcher and click **Terminal Emulator**.
- Press `Alt+F3`, type `xfce terminal` and press Enter twice. - Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**. - 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][tools].
Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets: Alternatively, you can use a suite of GUI tools, most of which are available through desktop widgets:
- The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage. - The **Domains Widget** allows you to manage running qubes, turn them on and off, and monitor memory usage.
- The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes. - The **Devices Widget** allows you to attach and detach devices -- such as USB drives and cameras -- to qubes.
- The **Disk Space Widget** will notify you if you're ever running out of disk space. - The **Disk Space Widget** will notify you if you're ever running out of disk space.
- The **Updates Widget** will inform you when template updates are available. - The **Updates Widget** will inform you when template updates are available.
![q40_widgets.png](/attachment/wiki/GettingStarted/r4.0-q40_widgets.png) ![q40_widgets.png](/attachment/wiki/GettingStarted/r4.0-q40_widgets.png)
For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system. For an overview of the entire system, you can use the **Qube Manager** (go to the Application Launcher → System Tools → Qube Manager), which displays the states of all the qubes in your system.
Starting apps Starting apps
------------- -------------
@ -100,15 +98,18 @@ If you'd like to add more, enter the qube's **Qube Settings** and add them on th
To start apps from the terminal in dom0, type: To start apps from the terminal in dom0, type:
$ qvm-run <qube_name> <app_command> [arguments] ```shell_session
$ qvm-run <qube_name> <app_command> [arguments]
```
e.g.: e.g.:
$ qvm-run untrusted firefox ```shell_session
$ qvm-run untrusted firefox
```
This command will start the qube if it is not already running. This command will start the qube if it is not already running.
Adding, removing, and listing qubes Adding, removing, and listing qubes
----------------------------------- -----------------------------------
@ -117,10 +118,9 @@ If you need to add or remove qubes, simply use the Qube Manager's **Add** and **
You can also add, remove, and list qubes from the command line using the following tools: You can also add, remove, and list qubes from the command line using the following tools:
- `qvm-create` - `qvm-create`
- `qvm-remove` - `qvm-remove`
- `qvm-ls` - `qvm-ls`
How many qubes do I need? How many qubes do I need?
------------------------- -------------------------
@ -136,7 +136,6 @@ You'll also be able to easily [copy][copy-files] any files you need to the newly
Still not sure? 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][partitioning], which describes how one of the Qubes OS architects partitions her digital life into security domains.
Important tasks Important tasks
--------------- ---------------
@ -149,12 +148,12 @@ The [Qubes backup system] allows you to do this securely and easily.
Here are some other tasks you're likely to want to perform. 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] section of the documentation.)
* [Copying and Pasting Text Between Domains][copy-paste] - [Copying and Pasting Text Between Domains][copy-paste]
* [Copying and Moving Files Between Domains][copy-files] - [Copying and Moving Files Between Domains][copy-files]
* [Copying from (and to) dom0] - [Copying from (and to) dom0]
* [Fullscreen Mode] - [Fullscreen Mode]
* [DisposableVMs] - [DisposableVMs]
* [Device Handling] (block, USB, and PCI devices) - [Device Handling] (block, USB, and PCI devices)
If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page. If you encounter any problems, please visit the [Help, Support, and Mailing Lists] page.

1
user/common-tasks/optical-discs.md
View File

@ -22,4 +22,3 @@ To access an optical disc via USB follow the [typical procedure for attaching a
Typically this would be `sr0`. Typically this would be `sr0`.
For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`. For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`.
You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`. You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`.

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

@ -9,7 +9,7 @@ redirect_from:
- /wiki/AssigningDevices/ - /wiki/AssigningDevices/
--- ---
# PCI Devices # # PCI Devices
*This page is part of [device handling in qubes].* *This page is part of [device handling in qubes].*
@ -19,8 +19,7 @@ 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. 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]** before deviating from default behavior.
## Introduction
## Introduction ##
Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. Unlike other devices ([USB], [block], 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. 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.
@ -37,53 +36,56 @@ While PCI device can only be used by one powered on VM at a time, it *is* possib
This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM. This means that you can use the device in one VM, shut that VM down, start up a different VM (to which the same device is now attached), then use the device in that VM.
This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices. This can be useful if, for example, you have only one USB controller, but you have multiple security domains which all require the use of different USB devices.
## Attaching Devices Using the GUI
## Attaching Devices Using the GUI ##
The qube settings for a VM offers the "Devices"-tab. The qube settings for a VM offers the "Devices"-tab.
There you can attach PCI-devices to a qube. There you can attach PCI-devices to a qube.
1. To reach the settings of any qube either 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]\[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`. - 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!) - Click the Domain Manager, hover the VM you want to attach a device to and select "settings" in the additional menu. (only running VMs!)
2. Select the "Devices" tab on the top bar. 2. Select the "Devices" tab on the top bar.
3. Select a device you want to attach to the qube and click the single arrow right! (`>`) 3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
4. You're done. 4. You're done.
If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached.
5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab).
If that doesn't help, read on to learn how to disable the strict reset requirement! If that doesn't help, read on to learn how to disable the strict reset requirement!
## `qvm-pci` Usage
## `qvm-pci` Usage ##
The `qvm-pci` tool allows PCI attachment and detachment. 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`][qvm-device].
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0: To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
qvm-pci ```
qvm-pci
```
This will show you the `backend:BDF` (Bus_Device.Function) address of each PCI device. This will show you the `backend:BDF` (Bus_Device.Function) address of each PCI device.
It will look something like `dom0:00_1a.0`. It will look something like `dom0:00_1a.0`.
Once you've found the address of the device you want to attach, then attach it like this: Once you've found the address of the device you want to attach, then attach it like this:
qvm-pci attach targetVM sourceVM:[BDF] --persistent ```
qvm-pci attach targetVM sourceVM:[BDF] --persistent
```
Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option. Since PCI devices have to be attached on bootup, attaching has to happen with the `--persistant` option.
For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this: For example, if `00_1a.0` is the BDF of the device you want to attach to the "work" domain, you would do this:
qvm-pci attach work dom0:00_1a.0 --persistent ```
qvm-pci attach work dom0:00_1a.0 --persistent
```
## Possible Issues
## Possible Issues ##
Visit the [PCI Troubleshooting guide](/doc/pci-troubleshooting/) to see issues that may arise due to PCI devices and how to troubleshoot them. Visit the [PCI Troubleshooting guide](/doc/pci-troubleshooting/) to see issues that may arise due to PCI devices and how to troubleshoot them.
## Additional Attach Options ## ## Additional Attach Options
Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option. Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option.
(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).)
@ -91,28 +93,29 @@ Attaching a PCI device through the commandline offers additional options, specif
`qvm-pci` exposes two additional options. `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][security considerations]! **Make sure you understand them before continuing!**
### no-strict-reset
### no-strict-reset ###
Do not require PCI device to be reset before attaching it to another VM. Do not require PCI device to be reset before attaching it to another VM.
This may leak usage data even without malicious intent! This may leak usage data even without malicious intent!
usage example: usage example:
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true ```
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
```
### permissive
### permissive ###
Allow write access to full PCI config space instead of whitelisted registers. 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].
usage example: usage example:
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true ```
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
```
## Bringing PCI Devices Back to dom0
## Bringing PCI Devices Back to dom0 ##
By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0. By default, when a device is detached from a VM (or when a VM with an attached PCI device is shut down), the device is *not* automatically attached back to dom0.
@ -122,20 +125,21 @@ A device which was previously attached to a VM less trusted than dom0 (which, in
In order to re-enable the device in dom0, either: In order to re-enable the device in dom0, either:
* Reboot the physical machine. (Best practice) - Reboot the physical machine. (Best practice)
or or
* Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver. - Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver, and attach it back to the original driver.
Replace `<BDF>` with your full device, for example `0000:00:1c.2`: Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
```
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias` MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1` MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
```
It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting! It is **strongly discouraged to reattach PCI devices to dom0**, especially if they don't support resetting!
[device handling in qubes]: /doc/device-handling/ [device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-handling-security/#pci-security [security considerations]: /doc/device-handling-security/#pci-security
@ -145,4 +149,3 @@ or
[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png [domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
[qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling [qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack [side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack

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

@ -42,13 +42,17 @@ In order to update dom0 from the command line, start a console in dom0 and then
To check and install updates for dom0 software: To check and install updates for dom0 software:
$ sudo qubes-dom0-update ```
$ sudo qubes-dom0-update
```
## How to install a specific package ## How to install a specific package
To install additional packages in dom0 (usually not recommended): To install additional packages in dom0 (usually not recommended):
$ sudo qubes-dom0-update anti-evil-maid ```
$ sudo qubes-dom0-update anti-evil-maid
```
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0).
However, this is only for advanced users who really understand what they are doing. However, this is only for advanced users who really understand what they are doing.
@ -97,17 +101,19 @@ You can re-install in a similar fashion to downgrading.
If you've installed a package such as anti-evil-maid, you can remove it with the following command: If you've installed a package such as anti-evil-maid, you can remove it with the following command:
sudo dnf remove anti-evil-maid ```
sudo dnf remove anti-evil-maid
```
## Testing repositories ## Testing repositories
There are three Qubes dom0 [testing] repositories: There are three Qubes dom0 [testing] repositories:
* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable - `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository (`current`) repository
* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages - `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages
that qualify as security fixes that qualify as security fixes
* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`) - `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
repository; mostly experimental debugging packages repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
@ -135,12 +141,14 @@ This section describes upgrading the kernel in dom0 and domUs.
The packages `kernel` and `kernel-latest` are for dom0. The packages `kernel` and `kernel-latest` are for dom0.
In the `current` repository: 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] (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing] (useful for [troubleshooting newer hardware])
In the `current-testing` repository: In the `current-testing` repository:
- `kernel`: the latest LTS kernel from kernel.org at the time it was built.
- `kernel-latest`: the latest release from kernel.org at the time it was built. - `kernel`: the latest LTS kernel from kernel.org at the time it was built.
- `kernel-latest`: the latest release from kernel.org at the time it was built.
### domU ### domU
@ -160,11 +168,13 @@ from the update command), you may need to manually rebuild the EFI or grub confi
your system uses. your system uses.
*EFI*: Replace the example version numbers with the one you are upgrading to. *EFI*: Replace the example version numbers with the one you are upgrading to.
~~~ ~~~
sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64 sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64
~~~ ~~~
*Grub2* *Grub2*
~~~ ~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~ ~~~
@ -183,16 +193,20 @@ The procedure varies depending on if you are booting with UEFI or grub.
On the next kernel update, the default will revert to the newest. On the next kernel update, the default will revert to the newest.
*EFI* *EFI*
~~~ ~~~
sudo nano /boot/efi/EFI/qubes/xen.cfg sudo nano /boot/efi/EFI/qubes/xen.cfg
~~~ ~~~
In the `[global]` section at the top, change the `default=` line to match one of the three boot entries listed below. In the `[global]` section at the top, change the `default=` line to match one of the three boot entries listed below.
For example, For example,
~~~ ~~~
default=4.19.67-1.pvops.qubes.x86_64 default=4.19.67-1.pvops.qubes.x86_64
~~~ ~~~
*Grub2* *Grub2*
~~~ ~~~
sudo nano /etc/default/grub sudo nano /etc/default/grub
[update the following two lines, add if needed] [update the following two lines, add if needed]
@ -201,12 +215,13 @@ GRUB_SAVEDEFAULT=true
[save and exit nano] [save and exit nano]
sudo grub2-mkconfig -o /boot/grub2/grub.cfg sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~ ~~~
Then, reboot. Then, reboot.
Once the grub menu appears, choose "Advanced Options for Qubes (with Xen hypervisor)". Once the grub menu appears, choose "Advanced Options for Qubes (with Xen hypervisor)".
Next, the top menu item (for example, "Xen hypervisor, version 4.8.5-9.fc25"). Next, the top menu item (for example, "Xen hypervisor, version 4.8.5-9.fc25").
Select the kernel you want as default, and it will be remembered for next boot. Select the kernel you want as default, and it will be remembered for next boot.
## Updating over Tor ### ## Updating over Tor
Requires installed [Whonix](/doc/privacy/whonix/). Requires installed [Whonix](/doc/privacy/whonix/).
@ -215,8 +230,9 @@ See the UpdateVM setting.
Choose your desired Whonix-Gateway ProxyVM from the list. Choose your desired Whonix-Gateway ProxyVM from the list.
For example: sys-whonix. For example: sys-whonix.
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix `
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
`
[dom0]: /doc/glossary/#dom0 [dom0]: /doc/glossary/#dom0
[Updating Qubes OS]: /doc/updating-qubes-os/ [Updating Qubes OS]: /doc/updating-qubes-os/
@ -225,4 +241,3 @@ For example: sys-whonix.
[troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/ [troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
[Managing VM kernel]: /doc/managing-vm-kernel/ [Managing VM kernel]: /doc/managing-vm-kernel/
[installing contributed packages]: /doc/installing-contributed-packages/ [installing contributed packages]: /doc/installing-contributed-packages/

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

@ -15,23 +15,21 @@ Updating [domUs], especially [TemplateVMs] and [StandaloneVMs][StandaloneVM] are
It is very import to keep domUs up-to-date with the latest [security] updates. It is very import to keep domUs up-to-date with the latest [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. 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 ## Installing software in TemplateVMs
To permanently install new software in a TemplateVM: To permanently install new software in a TemplateVM:
1. Start the TemplateVM. 1. Start the TemplateVM.
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`. 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). 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. 4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect. 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. 6. (Optional) In the relevant [TemplateBasedVMs]' **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. These new shortcuts will appear in the Applications Menu.
(If you encounter problems, see [here][shortcuts] for troubleshooting.) (If you encounter problems, see [here][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) ![[The Applications tab in Qube Settings](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)](/attachment/wiki/ManagingAppVmShortcuts/r4.1-dom0-appmenu-select.png)
## Updating software in TemplateVMs ## Updating software in TemplateVMs
The recommended way to update your TemplateVMs is to use the **Qubes Update** tool. The recommended way to update your TemplateVMs is to use the **Qubes Update** tool.
@ -43,7 +41,6 @@ You can also update TemplateVMs individually.
In the Qube Manager, select the desired TemplateVM, then click **Update qube**. In the Qube Manager, select the desired TemplateVM, then click **Update qube**.
Advanced users can execute the standard update command for that operating system from the command line, e.g. `dnf update` in Fedora and `apt-get update` in Debian. Advanced users can execute the standard update command for that operating system from the command line, e.g. `dnf update` in Fedora and `apt-get update` in Debian.
## Testing repositories ## 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], you must enable the appropriate testing repositories.
@ -52,9 +49,9 @@ If you wish to install updates that are still in [testing], you must enable the
There are three Qubes VM testing repositories (where `*` denotes the Release): There are three Qubes VM testing repositories (where `*` denotes the Release):
* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository - `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable (`current`) repository
* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes - `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages that qualify as security fixes
* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages - `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option. To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
Example commands: Example commands:
@ -67,23 +64,20 @@ sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-*.repo`. To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in `/etc/yum.repos.d/qubes-*.repo`.
### Debian ### Debian
Debian also has three Qubes VM testing repositories (where `*` denotes the Release): Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
* `*-testing` -- testing packages that will eventually land in the stable (`current`) repository - `*-testing` -- testing packages that will eventually land in the stable (`current`) repository
* `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes - `*-securitytesting` -- a subset of `*-testing` that contains packages that qualify as security fixes
* `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages - `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages
To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`. To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`.
## Contributed package repository ## Contributed package repository
Please see [installing contributed packages]. Please see [installing contributed packages].
## StandaloneVMs ## 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] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
@ -92,12 +86,10 @@ Therefore, it will not be updated when the TemplateVM is updated.
Rather, it must be updated individually. Rather, it must be updated individually.
The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs. The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs.
## Advanced ## Advanced
The following sections cover advanced topics pertaining to installing and updating software in domUs. The following sections cover advanced topics pertaining to installing and updating software in domUs.
### RPMFusion for Fedora TemplateVMs ### 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] 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):
@ -114,7 +106,6 @@ This will permanently enable the RPM Fusion repos.
If you install software from here, it's important to keep these repos enabled so that you can receiving future updates. If you install software from here, it's important to keep these repos enabled so that you can receiving future updates.
If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them. If you only enable these repos temporarily to install a package the Qubes update mechanism may persistently notify you that updates are available, since it cannot download them.
### Reverting changes to a TemplateVM ### Reverting changes to a TemplateVM
Perhaps you've just updated your TemplateVM, and the update broke your template. Perhaps you've just updated your TemplateVM, and the update broke your template.
@ -132,7 +123,6 @@ If you want to undo changes to a TemplateVM, there are three basic methods:
This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations. This is appropriate for both misconfigurations and security concerns, and it can preserve your customizations.
However, it is a bit more complex. However, it is a bit more complex.
#### Root revert #### Root revert
**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.* **Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
@ -145,26 +135,25 @@ Just make sure to **back up** all of your data and changes first!
2. In a dom0 terminal: 2. In a dom0 terminal:
```
qvm-volume revert <template>:root qvm-volume revert <template>:root
```
#### Reinstall the template #### Reinstall the template
Please see [How to Reinstall a TemplateVM]. Please see [How to Reinstall a TemplateVM].
#### Full revert #### Full revert
This is like the simple revert, except: This is like the simple revert, except:
- You must also revert the private volume with `qvm-volume revert <template>:private`. - You must also revert the private volume with `qvm-volume revert <template>:private`.
This requires you to have an old revision of the private volume, which does not exist with the current default config. This requires you to have an old revision of the private volume, which does not exist with the current default config.
However, if you don't have anything important in the private volume (likely for a TemplateVM), then you can work around this by just resetting the private volume with `qvm-volume import --no-resize <template>:private /dev/null`. However, if you don't have anything important in the private volume (likely for a TemplateVM), then you can work around this by just resetting the private volume with `qvm-volume import --no-resize <template>:private /dev/null`.
- The saved revision of the volumes must be uncompromised. - The saved revision of the volumes must be uncompromised.
With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action. With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action.
### Temporarily allowing networking for software installation ### Temporarily allowing networking for software installation
Some third-party applications cannot be installed using the standard repositories and need to be manually downloaded and installed. Some third-party applications cannot be installed using the standard repositories and need to be manually downloaded and installed.
@ -173,7 +162,6 @@ So it is necessary to modify firewall rules to allow less restrictive internet a
As soon as software installation is completed, firewall rules should be returned back to the default state. As soon as software installation is completed, firewall rules should be returned back to the default state.
The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above. The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
### Updates proxy ### Updates proxy
Updates proxy is a service which allows access only from package managers. Updates proxy is a service which allows access only from package managers.
@ -194,7 +182,6 @@ There are two services (`qvm-service`, [service framework]):
Both the old and new names work. Both the old and new names work.
The defaults listed above are applied if the service is not explicitly listed in the services tab. The defaults listed above are applied if the service is not explicitly listed in the services tab.
#### Technical details #### Technical details
The updates proxy uses RPC/qrexec. The updates proxy uses RPC/qrexec.
@ -202,9 +189,9 @@ The proxy is configured in qrexec policy in dom0: `/etc/qubes-rpc/policy/qubes.U
By default this is set to sys-net and/or sys-whonix, depending on firstboot choices. By default this is set to sys-net and/or sys-whonix, depending on firstboot choices.
This new design allows for templates to be updated even when they are not connected to any NetVM. This new design allows for templates to be updated even when they are not connected to any NetVM.
Example policy file in R4.0 (with Whonix installed, but not set as default UpdateVM for all templates): Example policy file in R4.0 (with Whonix installed, but not set as default UpdateVM for all templates):
```
```shell_session
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone # any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
@tag:whonix-updatevm @default allow,target=sys-whonix @tag:whonix-updatevm @default allow,target=sys-whonix
@tag:whonix-updatevm @anyvm deny @tag:whonix-updatevm @anyvm deny
@ -275,6 +262,7 @@ Shutdown the TemplateVM:
```shell_session ```shell_session
[user@snap-demo-AppVM ~]$ snap install <package> [user@snap-demo-AppVM ~]$ snap install <package>
``` ```
When the install is complete you can close the terminal window. When the install is complete you can close the terminal window.
3. Refresh the Applications list for the AppVM. 3. Refresh the Applications list for the AppVM.
@ -283,7 +271,6 @@ Then go to the Applications tab and click "Refresh Applications"
The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running. The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running.
### Autostarting Installed Applications ### Autostarting Installed Applications
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app. If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
@ -303,7 +290,7 @@ yelp.desktop
3. Create the autostart directory: 3. Create the autostart directory:
```shell_session ```
[user@example-AppVM ~]$ mkdir -p ~/.config/autostart [user@example-AppVM ~]$ mkdir -p ~/.config/autostart
``` ```
@ -315,8 +302,6 @@ 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. 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 [domUs]: /doc/glossary/#domu
[TemplateVMs]: /doc/templates/ [TemplateVMs]: /doc/templates/
[StandaloneVM]: /doc/standalone-and-hvm/ [StandaloneVM]: /doc/standalone-and-hvm/
@ -329,4 +314,3 @@ Note that the app will autostart only when the AppVM starts. If you would like t
[How to Reinstall a TemplateVM]: /doc/reinstall-template/ [How to Reinstall a TemplateVM]: /doc/reinstall-template/
[installing contributed packages]: /doc/installing-contributed-packages/ [installing contributed packages]: /doc/installing-contributed-packages/
[shortcuts]: /doc/managing-appvm-shortcuts/ [shortcuts]: /doc/managing-appvm-shortcuts/

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

@ -14,9 +14,9 @@ It is very important to keep your Qubes OS system up-to-date to ensure you have
Fully updating your Qubes OS system means updating: Fully updating your Qubes OS system means updating:
- [Dom0] - [Dom0]
- [TemplateVMs] - [TemplateVMs]
- [StandaloneVMs] (if you have any) - [StandaloneVMs] (if you have any)
You can accomplish this using the **Qubes Update** tool. You can accomplish this using the **Qubes Update** tool.
By default, the Qubes Update tool will appear as an icon in the Notification Area when updates are available, but you can also start the tool manually by selecting it in the Applications Menu under "System Tools." By default, the Qubes Update tool will appear as an icon in the Notification Area when updates are available, but you can also start the tool manually by selecting it in the Applications Menu under "System Tools."
@ -33,7 +33,6 @@ You can always find out when an operating system reaches EOL from the upstream p
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]). 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]. The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
[supported version of Qubes OS]: /doc/supported-versions/#qubes-os [supported version of Qubes OS]: /doc/supported-versions/#qubes-os
[Upgrade Guides]: /doc/upgrade/ [Upgrade Guides]: /doc/upgrade/
[security]: /security/ [security]: /security/

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

@ -6,7 +6,7 @@ redirect_from:
- /doc/usb/ - /doc/usb/
--- ---
# USB Devices # # USB Devices
*This page is part of [device handling in qubes].* *This page is part of [device handling in qubes].*
@ -20,18 +20,16 @@ Whenever possible, attach a [block device] instead.
Examples of valid cases for USB-passthrough: Examples of valid cases for USB-passthrough:
- [microcontroller programming] - [microcontroller programming]
- [external audio devices] - [external audio devices]
- [optical drives] for recording - [optical drives] for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy]. (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].) But it has some [issues][4661].)
## Attaching And Detaching a USB Device
## Attaching And Detaching a USB Device ## ### With Qubes Device Manager
### With Qubes Device Manager ###
Click the device-manager-icon: ![device manager icon] Click the device-manager-icon: ![device manager icon]
A list of available devices appears. A list of available devices appears.
@ -49,51 +47,53 @@ 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] next to it.
Click that and your device will be detached. Click that and your device will be detached.
### With The Command Line Tool
### With The Command Line Tool ###
In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. In dom0, you can use `qvm-usb` from the commandline to attach and detach devices.
Listing available USB devices: Listing available USB devices:
[user@dom0 ~]$ qvm-usb ```shell_session
BACKEND:DEVID DESCRIPTION USED BY [user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
```
Attaching selected USB device: Attaching selected USB device:
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5 ```shell_session
[user@dom0 ~]$ qvm-usb [user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
BACKEND:DEVID DESCRIPTION USED BY [user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
Now, you can use your USB device (camera in this case) in the `work` qube. 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].
When you finish, detach the device. When you finish, detach the device.
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5 ```shell_session
[user@dom0 ~]$ qvm-usb [user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
BACKEND:DEVID DESCRIPTION USED BY [user@dom0 ~]$ qvm-usb
sys-usb:2-4 04ca:300d 04ca_300d BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```
## Maintenance And Customisation
## Maintenance And Customisation ## ### Creating And Using a USB qube
### 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 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][USB-qube howto].
### Installation Of `qubes-usb-proxy`
### Installation Of `qubes-usb-proxy` ###
To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to. To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to.
This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`.
@ -104,15 +104,13 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you
- Fedora: `sudo dnf install qubes-usb-proxy` - Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy` - Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`
### Using USB Keyboards And Other Input Devices
### 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]** 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][keyboard setup].
### Finding The Right USB Controller
### Finding The Right USB Controller ###
Some USB devices are not compatible with the USB pass-through method Qubes employs. Some USB devices are not compatible with the USB pass-through method Qubes employs.
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
@ -122,12 +120,16 @@ If you have multiple USB controllers, you must first figure out which PCI device
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
lsusb ```
lsusb
```
For example, I want to attach a broadband modem to the NetVM. For example, I want to attach a broadband modem to the NetVM.
In the output of `lsusb` it may be listed as something like: In the output of `lsusb` it may be listed as something like:
Bus 003 Device 003: ID 413c:818d Dell Computer Corp. ```
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
```
(In this case, the device isn't fully identified) (In this case, the device isn't fully identified)
@ -136,12 +138,15 @@ Check which other devices are connected to the same bus, since *all* of them wil
To find the right controller, follow the usb bus: To find the right controller, follow the usb bus:
readlink /sys/bus/usb/devices/usb3 ```
readlink /sys/bus/usb/devices/usb3
```
This should output something like: This should output something like:
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ```
../../../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][qvm-pci] to attach the controller to the targetVM.
@ -149,7 +154,6 @@ For example, On R 4.0 the command would look something like
`qvm-pci attach --persistent personal dom0:00_1a.0` `qvm-pci attach --persistent personal dom0:00_1a.0`
[device handling in qubes]: /doc/device-handling/ [device handling in qubes]: /doc/device-handling/
[block device]: /doc/block-devices/ [block device]: /doc/block-devices/
[security considerations]: /doc/device-handling-security/#usb-security [security considerations]: /doc/device-handling-security/#usb-security

12
user/common-tasks/volume-backup-revert.md
View File

@ -26,7 +26,9 @@ inherits the pool default revisions_to_keep.
For the private volume associated with a VM named vmname, you may inspect the For the private volume associated with a VM named vmname, you may inspect the
value of revisions_to_keep from the dom0 CLI as follows: value of revisions_to_keep from the dom0 CLI as follows:
qvm-volume info vmname:private ```
qvm-volume info vmname:private
```
The output of the above command will also display the "Available revisions The output of the above command will also display the "Available revisions
(for revert)" at the bottom. For a very large volume in a small pool, (for revert)" at the bottom. For a very large volume in a small pool,
@ -36,10 +38,14 @@ smaller volume for which you would like to have the future option of reverting,
revisions_to_keep should probably be set to at least 2. To set revisions_to_keep should probably be set to at least 2. To set
revisions_to_keep for this same VM / volume example: revisions_to_keep for this same VM / volume example:
qvm-volume config vmname:private revisions_to_keep 2 ```
qvm-volume config vmname:private revisions_to_keep 2
```
With the VM stopped, you may revert to an older snapshot of the private volume With the VM stopped, you may revert to an older snapshot of the private volume
from the the above list of "Available revisions (for revert)", where the last from the the above list of "Available revisions (for revert)", where the last
item on the list with the largest integer is the most recent snapshot: item on the list with the largest integer is the most recent snapshot:
qvm-volume revert vmname:private <revision> ```
qvm-volume revert vmname:private <revision>
```

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

@ -10,7 +10,6 @@ redirect_from:
In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration. In the present context, "custom installation" refers to things like manual partitioning, setting up LVM and RAID, and manual LUKS encryption configuration.
## Installer Defaults ## Installer Defaults
For reference, these are the typical defaults for a single disk with legacy boot: For reference, these are the typical defaults for a single disk with legacy boot:
@ -58,7 +57,6 @@ Order Action Type Device Mount po
14 Create Format ext4 qubes_dom0-root / 14 Create Format ext4 qubes_dom0-root /
~~~ ~~~
## Typical Partition Schemes ## Typical Partition Schemes
If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example. If you want your partition/LVM scheme to look like the Qubes default but with a few tweaks, follow this example.
@ -75,7 +73,6 @@ sda disk
└──qubes_dom0-swap lvm [SWAP] └──qubes_dom0-swap lvm [SWAP]
~~~ ~~~
## Encryption Defaults ## Encryption Defaults
By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows: By default, `cryptsetup 1.7.5` will create a LUKS/dm-crypt volume as follows:
@ -98,25 +95,28 @@ Default compiled-in device cipher parameters:
This means that, by default, Qubes inherits these upstream defaults: This means that, by default, Qubes inherits these upstream defaults:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238] - AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- SHA-256 - SHA-256
- `/dev/urandom` - `/dev/urandom`
- probably an `iter-time` of one second - probably an `iter-time` of one second
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below. If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
## Example: Custom LUKS Configuration ## Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console. Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
1. (Optional) Wipe the disk: 1. (Optional) Wipe the disk:
```
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync # dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
```
2. Create partitions: 2. Create partitions:
```
# fdisk /dev/sda # fdisk /dev/sda
```
Follow the steps to create two partitions: Follow the steps to create two partitions:
@ -125,26 +125,34 @@ Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual con
4. Create LUKS encrypted volume: 4. Create LUKS encrypted volume:
```
# cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2 # cryptsetup -v --hash sha512 --cipher aes-xts-plain64 --key-size 512 --use-random --iter-time 10000 --verify-passphrase luksFormat /dev/sda2
```
5. Open encrypted volume: 5. Open encrypted volume:
```
# cryptsetup open /dev/sda2 luks # cryptsetup open /dev/sda2 luks
```
6. Create LVM volumes: 6. Create LVM volumes:
```
# pvcreate /dev/mapper/luks # pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks # vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0 # lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00 # lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root # lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root # lvextend -L <size_of_pool00> /dev/qubes_dom0/root
```
8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation. 8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation.
At the disk selection screen, select: At the disk selection screen, select:
```
[x] I will configure partitioning. [x] I will configure partitioning.
[ ] Encrypt my data. [ ] Encrypt my data.
```
9. Decrypt your partition. After decrypting you may assign mount points: 9. Decrypt your partition. After decrypting you may assign mount points:
Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top. Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top.
@ -152,8 +160,6 @@ 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`. 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. 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 [cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption [dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238 [tomb-238]: https://github.com/dyne/Tomb/issues/238

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

@ -19,12 +19,11 @@ If you are interested in offering a mirror for Qubes downloads, thank you!
We greatly appreciate your offer, and we hope these brief instructions are We greatly appreciate your offer, and we hope these brief instructions are
helpful in streamlining the process. helpful in streamlining the process.
* We are happy to provide rsync or HTTP master. * We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once * Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine. every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek]. * For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew]. * For website updates and fixes, please contact [Andrew].
[mirror-list]: /downloads/#mirrors [mirror-list]: /downloads/#mirrors
[Wojtek]: /team/#wojtek-porczyk [Wojtek]: /team/#wojtek-porczyk

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

@ -41,33 +41,32 @@ From a Qubes-specific security perspective, each has certain pros and cons.
Pros: Pros:
* Works via USB, including with a [USB qube]. * Works via USB, including with a [USB qube].
* Non-fixed capacity. * Non-fixed capacity.
(Easy to find one on which the ISO can fit.) (Easy to find one on which the ISO can fit.)
Cons: Cons:
* Rewritable. * Rewritable.
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.) (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. * Untrustworthy firmware.
(Firmware can be malicious even if the drive is new. (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][BadUSB].
Installing from a compromised drive could compromise even a brand new Qubes installation.) Installing from a compromised drive could compromise even a brand new Qubes installation.)
### Optical discs ### Optical discs
Pros: Pros:
* Read-only available. * Read-only available.
(If you use read-only media, you don't have to worry about the ISO being maliciously altered after it has been written to the disc. (If you use read-only media, you don't have to worry about the ISO being maliciously altered after it has been written to the disc.
You then have the option of verifying the signature on multiple different machines.) You then have the option of verifying the signature on multiple different machines.)
Cons: Cons:
* Fixed capacity. * Fixed capacity.
(If the size of the ISO is larger than your disc, it will be inconvenient.) (If the size of the ISO is larger than your disc, it will be inconvenient.)
* Passthrough recording (a.k.a., "burning") is not supported by Xen. * Passthrough recording (a.k.a., "burning") is not supported by Xen.
(This mainly applies if you're upgrading from a previous version of Qubes.) (This mainly applies if you're upgrading from a previous version of Qubes.)
Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are: Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
1. Use a USB optical drive. 1. Use a USB optical drive.
@ -78,7 +77,6 @@ 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. 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/ [AEM]: /doc/anti-evil-maid/
[verify]: /security/verifying-signatures/ [verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf [classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf

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

@ -81,7 +81,9 @@ The size of each Qubes ISO is available on the [downloads] page by hovering over
If you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`: If you choose to use a USB drive, copy the ISO onto the USB device, e.g. using `dd`:
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync ```
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
```
Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`). 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`). Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
@ -124,9 +126,9 @@ From here, you can navigate the boot screen using the arrow keys on your keyboar
Pressing the "Tab" key will reveal options. Pressing the "Tab" key will reveal options.
You can choose one of three options: You can choose one of three options:
* Install Qubes OS * Install Qubes OS
* Test this media and install Qubes OS * Test this media and install Qubes OS
* Troubleshooting * Troubleshooting
Select the option to test this media and install Qubes OS. Select the option to test this media and install Qubes OS.
@ -207,8 +209,8 @@ 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. On the software selection tab, you can choose which software to install in Qubes OS.
Two options are available: Two options are available:
* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes. * **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:** Select this option if you would like to use [Whonix] qubes.
Whonix allows you to use [Tor] securely within Qubes. Whonix allows you to use [Tor] securely within Qubes.
Whonix lets you route some or all of your network traffic through Tor for greater privacy. Whonix lets you route some or all of your network traffic through Tor for greater privacy.
@ -233,7 +235,6 @@ Select the storage device on which you would like to install Qubes OS.
We strongly recommended making a full backup before proceeding. We strongly recommended making a full backup before proceeding.
</div> </div>
Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive. Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive.
The installation destination must have a least 32 GiB of free space available. The installation destination must have a least 32 GiB of free space available.
@ -314,22 +315,22 @@ These are designed to give you a more ready-to-use environment from the get-go.
Let's briefly go over the options: Let's briefly go over the options:
* **Create default system qubes:** * **Create default system qubes:**
These are the core components of the system, required for things like internet access. These are the core components of the system, required for things like internet access.
* **Create default application qubes:** * **Create default application qubes:**
These are how you compartmentalize your digital life. These are how you compartmentalize your digital life.
There's nothing special about the ones the installer creates. There's nothing special about the ones the installer creates.
They're just suggestions that apply to most people. They're just suggestions that apply to most people.
If you decide you don't want them, you can always delete them later, and you can always create your own. If you decide you don't want them, you can always delete them later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:** * **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option. If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:** * **Enabling system and template updates over the Tor anonymity network using Whonix:**
If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor. If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:** * **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the USB controllers. Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:** * **Use sys-net qube for both networking and USB devices:**
You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter. You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:** * **Do not configure anything:**
This is for very advanced users only. This is for very advanced users only.
If you select this option, you'll have to set everything up manually afterward. If you select this option, you'll have to set everything up manually afterward.
@ -381,18 +382,17 @@ Consider giving back to the Qubes community and helping other users by [generati
## Getting help ## Getting help
* We work very hard to make the [documentation] accurate, comprehensive useful and user friendly. * We work very hard to make the [documentation] accurate, comprehensive useful and user friendly.
We urge you to read it! It may very well contain the answers to your questions. 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] it!)
* If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide. * If issues arise during installation, see the [Installation Troubleshooting](/doc/installation-troubleshooting) guide.
* If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask. * If you don't find your answer in the documentation, please see [Help, Support, Mailing Lists, and Forum] for places to ask.
* Please do **not** email individual members of the Qubes team with questions about installation or other problems. * 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] for appropriate places to ask questions.
[QSB #46]: /news/2019/01/23/qsb-46/ [QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/ [system requirements]: /doc/system-requirements/
[Qubes-certified hardware]: /doc/certified-hardware/ [Qubes-certified hardware]: /doc/certified-hardware/
@ -423,4 +423,3 @@ Consider giving back to the Qubes community and helping other users by [generati
[advanced configuration]: /doc/#advanced-configuration [advanced configuration]: /doc/#advanced-configuration
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports [hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
[Get Started]: /getting-started/ [Get Started]: /getting-started/

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

@ -8,7 +8,6 @@ permalink: /doc/supported-versions/
This page details the level and period of support for versions of operating systems in the Qubes ecosystem. This page details the level and period of support for versions of operating systems in the Qubes ecosystem.
## Qubes OS ## Qubes OS
Qubes OS releases are supported for **six months** after each subsequent major Qubes OS releases are supported for **six months** after each subsequent major
@ -26,7 +25,6 @@ past minor releases, are available from our [download mirrors].
| Release 4.0 | 2018-03-28 | TBA | Supported | | Release 4.0 | 2018-03-28 | TBA | Supported |
| Release 4.1 | TBA | TBA | [In development][4.1] | | Release 4.1 | TBA | TBA | [In development][4.1] |
### Note on point releases ### Note on point releases
Please note that point releases, such as 3.2.1 and 4.0.1, do not designate separate, new versions of Qubes OS. Please note that point releases, such as 3.2.1 and 4.0.1, do not designate separate, new versions of Qubes OS.
@ -34,7 +32,6 @@ Rather, they designate their respective major or minor releases, such as 3.2 and
For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1. For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1.
Therefore, point releases are not displayed as separate rows on any of the tables on this page. Therefore, point releases are not displayed as separate rows on any of the tables on this page.
## Dom0 ## Dom0
The table below shows the OS used for dom0 in each Qubes OS release. The table below shows the OS used for dom0 in each Qubes OS release.
@ -49,14 +46,12 @@ The table below shows the OS used for dom0 in each Qubes OS release.
| Release 4.0 | Fedora 25 | | Release 4.0 | Fedora 25 |
| Release 4.1 | Fedora 32 | | Release 4.1 | Fedora 32 |
### Note on dom0 and EOL ### 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.). 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], 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). 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 ## TemplateVMs
The following table shows select [TemplateVM] versions that are currently supported. The following table shows select [TemplateVM] versions that are currently supported.
@ -74,7 +69,6 @@ For upstream EOL information, see [Fedora EOL][fedora-eol] and [Debian EOL][debi
\* Denotes versions for which we have published the packages but have not done extensive testing. \* Denotes versions for which we have published the packages but have not done extensive testing.
### Note on Whonix support ### Note on Whonix support
[Whonix] TemplateVMs are supported by our partner, the [Whonix Project]. [Whonix] TemplateVMs are supported by our partner, the [Whonix Project].
@ -83,15 +77,14 @@ The Whonix Project has set its own support policy for Whonix TemplateVMs in Qube
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. 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.
To be precise: To be precise:
* One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS. * One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release. This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
* One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported. * One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release. This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release.
We aim to announce both types of events one month in advance in order to remind users to upgrade. We aim to announce both types of events one month in advance in order to remind users to upgrade.
[Version Scheme]: /doc/version-scheme/ [Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/ [Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors [download mirrors]: /downloads/#mirrors
@ -106,4 +99,3 @@ We aim to announce both types of events one month in advance in order to remind
[Whonix]: /doc/whonix/ [Whonix]: /doc/whonix/
[Whonix Project]: https://www.whonix.org/ [Whonix Project]: https://www.whonix.org/
[Debian-LTS]: https://wiki.debian.org/LTS [Debian-LTS]: https://wiki.debian.org/LTS

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

@ -13,21 +13,23 @@ Never rely on code that is in testing for critical work!
Releases Releases
-------- --------
How to test upcoming Qubes OS releases: How to test upcoming Qubes OS releases:
* Use [qubes-builder] to build the latest release. * Use [qubes-builder] to build the latest release.
* Test the latest release candidate (RC), if any is currently available. * 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/). * (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 [Version Scheme] for details about release versions and schedules.
See [Release Checklist] for details about the RC process. See [Release Checklist] for details about the RC process.
Updates Updates
------- -------
How to test updates: How to test updates:
* Enable [dom0 testing repositories]. * Enable [dom0 testing repositories].
* Enable [TemplateVM testing repositories]. * Enable [TemplateVM 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. 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. The update remains in `security-testing` or `current-testing` for a minimum of one week.
@ -42,6 +44,7 @@ While this limitation can be inconvenient, the benefits outweigh the costs, sinc
Providing Feedback Providing Feedback
------------------ ------------------
If you're testing new releases or updates, we would be grateful for your feedback. If you're testing new releases or updates, we would be grateful for your feedback.
We use an [automated build process]. We use an [automated build process].
@ -50,7 +53,6 @@ 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. 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] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
[contribute]: /doc/contributing/ [contribute]: /doc/contributing/
[qubes-builder]: /doc/qubes-builder/ [qubes-builder]: /doc/qubes-builder/
[Version Scheme]: /doc/version-scheme/ [Version Scheme]: /doc/version-scheme/
@ -61,4 +63,3 @@ If you [report a bug] in a package that is in a testing repository, please refer
[updates-status]: https://github.com/QubesOS/updates-status/issues [updates-status]: https://github.com/QubesOS/updates-status/issues
[report a bug]: /doc/reporting-bugs/ [report a bug]: /doc/reporting-bugs/
[Providing Feedback]: #providing-feedback [Providing Feedback]: #providing-feedback

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

@ -74,4 +74,3 @@ Be sure to do steps described in this section after *all* your template and stan
~~~ ~~~
4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that. 4. Reboot your system. Please note that if you use Anti Evil Maid, then it won't be able to unseal the passphrase this time, because the Xen, kernel, and initramfs binaries have changed. Once the system boots up again, you could reseal your Anti Evil Maid's passphrase to the new configuration. Please consult Anti Evil Maid documentation for explanation on how to do that.

51
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md
View File

@ -8,8 +8,7 @@ redirect_from:
- /doc/UpgradeToR3.0rc1/ - /doc/UpgradeToR3.0rc1/
--- ---
Upgrading Qubes R2 to R3.0 # Upgrading Qubes R2 to R3.0
======================================
**This instruction is highly experimental, the official way to upgrade from R2 is to backup the data and reinstall the system. Use at your own risk!** **This instruction is highly experimental, the official way to upgrade from R2 is to backup the data and reinstall the system. Use at your own risk!**
@ -19,8 +18,7 @@ Current Qubes R3.0 (R3.0) systems can be upgraded in-place to the latest R3.0 by
Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/doc/backup-restore/) correctly!). Experienced users may be comfortable accepting the risks of upgrading in-place. Such users may wish to first attempt an in-place upgrade. If nothing goes wrong, then some time and effort will have been saved. If something does go wrong, then the user can simply perform a clean installation, and no significant loss will have occurred (as long as the user [backed up](/doc/backup-restore/) correctly!).
Upgrade all Template and Standalone VM(s) ## Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs. By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs.
@ -31,11 +29,15 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there. 1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package: 2. Install `qubes-upgrade-vm` package:
```
sudo yum install qubes-upgrade-vm sudo yum install qubes-upgrade-vm
```
3. Proceed with normal update in the template: 3. Proceed with normal update in the template:
```
sudo yum update sudo yum update
```
You'll need to accept "Qubes Release 3 Signing Key" - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don't need to manually verify it. You'll need to accept "Qubes Release 3 Signing Key" - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don't need to manually verify it.
@ -46,14 +48,18 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there. 1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Update repository definition: 2. Update repository definition:
```
sudo cp /etc/apt/sources.list.d/qubes-r2.list sudo cp /etc/apt/sources.list.d/qubes-r2.list
/etc/apt/sources.list.d/qubes-r3-upgrade.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
3. Proceed with normal update in the template: 3. Proceed with normal update in the template:
```
sudo apt-get update sudo apt-get update
sudo apt-get dist-upgrade sudo apt-get dist-upgrade
```
There will be some error messages during the process, but our tests does There will be some error messages during the process, but our tests does
not revealed any negative consequences. not revealed any negative consequences.
@ -63,21 +69,24 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
4. Shutdown the template VM. 4. Shutdown the template VM.
Upgrading dom0 ## Upgrading dom0
--------------
Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm - you will not be able to start them again. Be sure to do steps described in this section after *all* your template and standalone VMs got updated as described in the section above. Also make sure you haven't shutdown any of: netvm, firewallvm - you will not be able to start them again.
1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole. 1. Open terminal in Dom0. E.g. Start-\>System Settings-\>Konsole.
2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys: 2. Upgrade the `qubes-release` package to the latest version which brings in new repo definitions and R2 signing keys:
```
sudo qubes-dom0-update qubes-release sudo qubes-dom0-update qubes-release
```
This should install `qubes-release-2-12` in your Dom0. This should install `qubes-release-2-12` in your Dom0.
3. Upgrade dom0 to R3.0: 3. Upgrade dom0 to R3.0:
```
sudo qubes-dom0-update --releasever=3.0 sudo qubes-dom0-update --releasever=3.0
```
After this step, until you reboot the system, most of the qvm-* tools will not work. After this step, until you reboot the system, most of the qvm-* tools will not work.
@ -85,7 +94,9 @@ Be sure to do steps described in this section after *all* your template and stan
5. Enable Xen services: 5. Enable Xen services:
```
sudo systemctl enable xenconsoled.service xenstored.service sudo systemctl enable xenconsoled.service xenstored.service
```
6. Reboot the system. 6. Reboot the system.
@ -95,10 +106,11 @@ Please note that if you use Anti Evil Maid, then it won't be able to unseal the
Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template: Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template:
sudo qubes-dom0-update qubes-template-fedora-21 ```
sudo qubes-dom0-update qubes-template-fedora-21
```
Upgrading template on already upgraded dom0 ## Upgrading template on already upgraded dom0
-------------------------------------------
If for some reason you did not upgrade all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be more complicated. This can be the case when you restore backup done on Qubes R2. If for some reason you did not upgrade all the templates and standalone VMs before upgrading dom0, you can still do this, but it will be more complicated. This can be the case when you restore backup done on Qubes R2.
@ -110,17 +122,19 @@ When you start R2 template/standalone VM on R3.0, there will be some limitations
Because of above limitations, you will need to configure some of those manually. The instruction assumes the VM name is `custom-template`, but the same instructions can be applied to a standalone VM. Because of above limitations, you will need to configure some of those manually. The instruction assumes the VM name is `custom-template`, but the same instructions can be applied to a standalone VM.
1.Check the VM network parameters, you will need them later: 1. Check the VM network parameters, you will need them later:
```shell_session
[user@dom0 ~]$ qvm-ls -n custom-template [user@dom0 ~]$ qvm-ls -n custom-template
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+ -------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
name | on | state | updbl | type | netvm | label | ip | ip back | gateway/DNS | name | on | state | updbl | type | netvm | label | ip | ip back | gateway/DNS |
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+ -------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
[custom-template] | | Halted | Yes | Tpl | *firewallvm | black | 10.137.1.53 | n/a | 10.137.1.1 | [custom-template] | | Halted | Yes | Tpl | *firewallvm | black | 10.137.1.53 | n/a | 10.137.1.1 |
```
2. Start the VM from command line:
2.Start the VM from command line: ```shell_session
[user@dom0 ~]$ qvm-start custom-template [user@dom0 ~]$ qvm-start custom-template
--> Loading the VM (type = TemplateVM)... --> Loading the VM (type = TemplateVM)...
--> Starting Qubes DB... --> Starting Qubes DB...
@ -130,18 +144,23 @@ Because of above limitations, you will need to configure some of those manually.
--> Starting the qrexec daemon... --> Starting the qrexec daemon...
Waiting for VM's qrexec agent.............................................................Cannot connect to 'custom-template' qrexec agent for 60 seconds, giving up Waiting for VM's qrexec agent.............................................................Cannot connect to 'custom-template' qrexec agent for 60 seconds, giving up
ERROR: Cannot execute qrexec-daemon! ERROR: Cannot execute qrexec-daemon!
```
You can interrupt with Ctrl-C that qrexec waiting process. You can interrupt with Ctrl-C that qrexec waiting process.
3.Access VM console: 3. Access VM console:
```
[user@dom0 ~]$ virsh -c xen:/// console custom-template [user@dom0 ~]$ virsh -c xen:/// console custom-template
```
4.Configure network according to parameters retrieved in first step: 4. Configure network according to parameters retrieved in first step:
```
ip addr add 10.137.1.53/32 dev eth0 ip addr add 10.137.1.53/32 dev eth0
ip route add 10.137.1.1/32 dev eth0 ip route add 10.137.1.1/32 dev eth0
ip route add via 10.137.1.1 ip route add via 10.137.1.1
echo nameserver 10.137.1.1 > /etc/resolv.conf echo nameserver 10.137.1.1 > /etc/resolv.conf
```
5.Proceed with normal upgrade instruction described on this page. 5. Proceed with normal upgrade instruction described on this page.

34
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md
View File

@ -8,8 +8,7 @@ redirect_from:
- /doc/UpgradeToR3.1rc1/ - /doc/UpgradeToR3.1rc1/
--- ---
Upgrading Qubes R3.0 to R3.1 # Upgrading Qubes R3.0 to R3.1
======================================
**Before attempting either an in-place upgrade or a clean installation, we **Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that users [back up their systems](/doc/backup-restore/).** strongly recommend that users [back up their systems](/doc/backup-restore/).**
@ -17,9 +16,7 @@ strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.0 systems can be upgraded in-place to the latest R3.1 Current Qubes R3.0 systems can be upgraded in-place to the latest R3.1
by following the procedure below. by following the procedure below.
## Upgrade all Template and Standalone VM(s)
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R3.0, there is only one TemplateVM. However, users are By default, in Qubes R3.0, there is only one TemplateVM. However, users are
free to create more TemplateVMs for special purposes, as well as StandaloneVMs. free to create more TemplateVMs for special purposes, as well as StandaloneVMs.
@ -27,8 +24,7 @@ More information on using multiple TemplateVMs, as well as StandaloneVMs, can be
found [here](/doc/software-update-vm/). The steps described in this found [here](/doc/software-update-vm/). The steps described in this
section should be repeated in **all** the user's Template and Standalone VMs. section should be repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates:
### Upgrade Fedora templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM 1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type Manager's right-click menu, choose "Run Command in VM," and type
@ -36,16 +32,19 @@ section should be repeated in **all** the user's Template and Standalone VMs.
2. Install the `qubes-upgrade-vm` package: 2. Install the `qubes-upgrade-vm` package:
```
sudo yum install qubes-upgrade-vm sudo yum install qubes-upgrade-vm
```
3. Proceed with a normal upgrade in the template: 3. Proceed with a normal upgrade in the template:
```
sudo yum upgrade sudo yum upgrade
```
4. Shut down the template VM. 4. Shut down the template VM.
### Upgrade Debian (and Whonix) templates:
### Upgrade Debian (and Whonix) templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM 1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type Manager's right-click menu, choose "Run Command in VM," and type
@ -53,23 +52,27 @@ section should be repeated in **all** the user's Template and Standalone VMs.
2. Update repository definition: 2. Update repository definition:
```
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
3. Proceed with a normal update in the template: 3. Proceed with a normal update in the template:
```
sudo apt-get update sudo apt-get update
sudo apt-get dist-upgrade sudo apt-get dist-upgrade
```
4. Remove unnecessary now file: 4. Remove unnecessary now file:
```
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
5. Shut down the template VM. 5. Shut down the template VM.
## Upgrading dom0
Upgrading dom0
--------------
**Important:** Do not perform the steps described in this section until **all** **Important:** Do not perform the steps described in this section until **all**
your Template and Standalone VMs have been upgraded as described in the previous your Template and Standalone VMs have been upgraded as described in the previous
@ -81,7 +84,9 @@ complete.
2. Upgrade dom0 to R3.1: 2. Upgrade dom0 to R3.1:
```
sudo qubes-dom0-update --releasever=3.1 sudo qubes-dom0-update --releasever=3.1
```
At this point, most of the `qvm-*` tools will stop working until after you At this point, most of the `qvm-*` tools will stop working until after you
reboot the system. reboot the system.
@ -113,5 +118,6 @@ for details.
Once you have upgraded dom0, you can install new templates from Qubes R3.1 Once you have upgraded dom0, you can install new templates from Qubes R3.1
repositories, in particular the new default Fedora 23 template: repositories, in particular the new default Fedora 23 template:
sudo qubes-dom0-update qubes-template-fedora-23 ```
sudo qubes-dom0-update qubes-template-fedora-23
```

44
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md
View File

@ -8,8 +8,7 @@ redirect_from:
- /doc/UpgradeToR3.2rc1/ - /doc/UpgradeToR3.2rc1/
--- ---
Upgrading Qubes R3.1 to R3.2 # Upgrading Qubes R3.1 to R3.2
======================================
**Before attempting either an in-place upgrade or a clean installation, we **Before attempting either an in-place upgrade or a clean installation, we
strongly recommend that users [back up their systems](/doc/backup-restore/).** strongly recommend that users [back up their systems](/doc/backup-restore/).**
@ -17,8 +16,7 @@ strongly recommend that users [back up their systems](/doc/backup-restore/).**
Current Qubes R3.1 systems can be upgraded in-place to the latest R3.2 Current Qubes R3.1 systems can be upgraded in-place to the latest R3.2
by following the procedure below. by following the procedure below.
Upgrading dom0 ## Upgrading dom0
--------------
1. Close Qubes Manager (right click on its tray icon -\> Exit) 1. Close Qubes Manager (right click on its tray icon -\> Exit)
@ -26,7 +24,9 @@ Upgrading dom0
3. Install `qubes-release` package carrying R3.2 repository information. 3. Install `qubes-release` package carrying R3.2 repository information.
```
sudo qubes-dom0-update --releasever=3.2 qubes-release sudo qubes-dom0-update --releasever=3.2 qubes-release
```
If you made any manual changes to repository definitions, new definitions If you made any manual changes to repository definitions, new definitions
will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see will be installed as `/etc/yum.repos.d/qubes-dom0.repo.rpmnew` (you'll see
@ -38,6 +38,7 @@ Upgrading dom0
you need to download few more packages manually, but **do not install you need to download few more packages manually, but **do not install
them** yet: them** yet:
```
sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2 sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2
(...) (...)
Transaction Summary Transaction Summary
@ -50,10 +51,13 @@ Upgrading dom0
Exiting on user command Exiting on user command
Your transaction was saved, rerun it with: Your transaction was saved, rerun it with:
yum load-transaction /tmp/yum_save_tx..... yum load-transaction /tmp/yum_save_tx.....
```
4. Upgrade dom0 to R3.2: 4. Upgrade dom0 to R3.2:
```
sudo qubes-dom0-update sudo qubes-dom0-update
```
You may wish to disable the screensaver "Lock screen" feature for this step, as You may wish to disable the screensaver "Lock screen" feature for this step, as
during the update XScreensaver may encounter an "Authentication failed" issue, during the update XScreensaver may encounter an "Authentication failed" issue,
@ -69,13 +73,16 @@ Upgrading dom0
actual files were modified. During upgrade, you'll see information about actual files were modified. During upgrade, you'll see information about
such cases, like: such cases, like:
```
warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew
```
This will happen for every configuration you have modified manually and for This will happen for every configuration you have modified manually and for
a few that has been modified by Qubes scripts. If you are not sure what to a few that has been modified by Qubes scripts. If you are not sure what to
do about them, below is a list of commands to deal with few common cases do about them, below is a list of commands to deal with few common cases
(either keep the old one, or replace with the new one): (either keep the old one, or replace with the new one):
```
rm -f /etc/group.rpmnew rm -f /etc/group.rpmnew
rm -f /etc/shadow.rpmnew rm -f /etc/shadow.rpmnew
rm -f /etc/qubes/guid.conf.rpmnew rm -f /etc/qubes/guid.conf.rpmnew
@ -83,6 +90,7 @@ Upgrading dom0
mv -f /etc/pam.d/postlogin{.rpmnew,} mv -f /etc/pam.d/postlogin{.rpmnew,}
mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,} mv -f /etc/salt/minion.d/f_defaults.conf{.rpmnew,}
mv -f /etc/dracut.conf{.rpmnew,} mv -f /etc/dracut.conf{.rpmnew,}
```
7. Reboot dom0. 7. Reboot dom0.
@ -95,15 +103,15 @@ Maid passphrase to the new configuration. Please consult the Anti Evil Maid
At first login after upgrade you may got a message like this: At first login after upgrade you may got a message like this:
``
Your saved session type 'kde-plasma' is not valid any more. Your saved session type 'kde-plasma' is not valid any more.
Please select a new one, otherwise 'default' will be used. Please select a new one, otherwise 'default' will be used.
``
This is result of upgrade KDE4 (`kde-plasma`) to KDE5 (`plasma`). Simply choose This is result of upgrade KDE4 (`kde-plasma`) to KDE5 (`plasma`). Simply choose
your favorite desktop environment and continue. your favorite desktop environment and continue.
## Upgrade all Template and Standalone VM(s)
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs. By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs.
However, users are free to create StandaloneVMs More information on using However, users are free to create StandaloneVMs More information on using
@ -111,8 +119,7 @@ multiple TemplateVMs, as well as StandaloneVMs, can be found
[here](/doc/software-update-vm/). The steps described in this section should be [here](/doc/software-update-vm/). The steps described in this section should be
repeated in **all** the user's Template and Standalone VMs. repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates:
### Upgrade Fedora templates: ###
**Note:** This will only upgrade your Fedora template from Qubes 3.1 to Qubes **Note:** This will only upgrade your Fedora template from Qubes 3.1 to Qubes
3.2. This will *not* upgrade your Fedora template from Fedora 23 to Fedora 24. 3.2. This will *not* upgrade your Fedora template from Fedora 23 to Fedora 24.
@ -125,20 +132,25 @@ In order to do that, please see the
2. Install the `qubes-upgrade-vm` package: 2. Install the `qubes-upgrade-vm` package:
```
sudo dnf install --refresh qubes-upgrade-vm sudo dnf install --refresh qubes-upgrade-vm
```
3. Proceed with a normal upgrade in the template: 3. Proceed with a normal upgrade in the template:
```
sudo dnf upgrade --refresh sudo dnf upgrade --refresh
```
4. Add new packages (only needed in default template): 4. Add new packages (only needed in default template):
```
sudo dnf install qubes-mgmt-salt-vm-connector sudo dnf install qubes-mgmt-salt-vm-connector
```
5. Shut down the template VM. 5. Shut down the template VM.
### Upgrade Debian (and Whonix) templates:
### Upgrade Debian (and Whonix) templates: ###
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM 1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type Manager's right-click menu, choose "Run Command in VM," and type
@ -146,22 +158,28 @@ In order to do that, please see the
2. Update repository definition: 2. Update repository definition:
```
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
3. Proceed with a normal update in the template: 3. Proceed with a normal update in the template:
```
sudo apt-get update sudo apt-get update
sudo apt-get dist-upgrade sudo apt-get dist-upgrade
```
4. Add new packages (only needed in default template): 4. Add new packages (only needed in default template):
```
sudo apt-get install qubes-mgmt-salt-vm-connector sudo apt-get install qubes-mgmt-salt-vm-connector
```
5. Remove unnecessary now file: 5. Remove unnecessary now file:
```
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
6. Shut down the template VM. 6. Shut down the template VM.

Some files were not shown because too many files have changed in this diff Show More