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

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

@ -8,16 +8,14 @@ redirect_from:
- /wiki/DevelopmentWorkflow/
---
Development Workflow
====================
# Development Workflow
A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
assumes you're using qubes-builder to build Qubes.
Repositories and committing Code
--------------------------------
# Repositories and committing Code
Qubes is split into a bunch of git repos. This are all contained in the
`qubes-src` directory under qubes-builder. Subdirectories there are separate
@ -149,21 +147,20 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
### Useful [QubesBuilder](/doc/qubes-builder/) commands
1. `make check` - will check if all the code was committed into repository and
1. `make check` - will check if all the code was committed into repository and
if all repository are tagged with signed tag.
2. `make show-vtags` - show version of each component (based on git tags) -
2. `make show-vtags` - show version of each component (based on git tags) -
mostly useful just before building ISO. **Note:** this will not show version
for components containing changes since last version tag
3. `make push` - push change from **all** repositories to git server. You must
3. `make push` - push change from **all** repositories to git server. You must
set proper remotes (see above) for all repositories first.
4. `make prepare-merge` - fetch changes from remote repositories (can be
4. `make prepare-merge` - fetch changes from remote repositories (can be
specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
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
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
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
name.
## Sending packages to different VM
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:
- 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 `local.UpdateApt` qrexec service in target VM (code below)
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
- 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 `local.UpdateApt` qrexec service in target VM (code below)
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
`update_repo.sh` script:

34
developer/building/qubes-builder-details.md
View File

@ -18,28 +18,28 @@ Components Makefile.builder file
Variables for Linux build:
- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
- `RPM_SPEC_FILES` List (space separated) of spec files for RPM package build. Path should be relative to component root directory. [QubesBuilder](/doc/qubes-builder/) will install all BuildRequires (in chroot environment) before the build. In most Qubes components all spec files are kept in *rpm\_spec* directory. This is mainly used for Fedora packages build.
- `ARCH_BUILD_DIRS` List (space separated) of directories with PKGBUILD files for Archlinux package build. Similar to RPM build, [QubesBuilder](/doc/qubes-builder/) will install all makedepends, then build the package.
Most components uses *archlinux* directory for this purpose, so its good to keep this style.
Variables for Windows build:
- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
- `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
- `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
- `CERT_FILENAME` Path to key file (pfx format)
- `CERT_PASSWORD` Key password
- `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
- `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
- `SIGNTOOL` Path to signtool
- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available:
- `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
- `mingw` - MinGW (Windows gcc port). Command used to build: *make all*
- `WIN_SOURCE_SUBDIRS` List of directories in which above command should be run. In most cases it will be only one entry: current directory (*.*).
- `WIN_PREBUILD_CMD` Command to run before build, mostly useful for WDK build (in mingw case, you can use makefile for this purpose). Can be used to set some variables, preprocess some files etc.
- `WIN_SIGN_CMD` Command used to sign resulting binaries. Note that default value is *sign.bat*. If you don't want to sign binaries, specify some placeholder here (eg. *true*). Check existing components (eg. vmm-xen-windows-pvdrivers) for example scripts. This command will be run with certain environment variables:
- `CERT_FILENAME` Path to key file (pfx format)
- `CERT_PASSWORD` Key password
- `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert
- `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
- `SIGNTOOL` Path to signtool
- `WIN_PACKAGE_CMD` Command used to produce installation package (msi or msm). Default value is *wix.bat*, similar to above - use *true* if you don't want this command.
- `WIN_OUTPUT_HEADERS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with public headers of the package - for use in other components.
- `WIN_OUTPUT_LIBS` Directory (relative to `WIN_SOURCE_SUBDIRS` element) with libraries (both DLL and implib) of the package - for use in other components. Note that [QubesBuilder](/doc/qubes-builder/) will copy files specified as *\$(WIN\_OUTPUT\_LIBS)/\*/\** to match WDK directory layout (*\<specified directory\>/\<arch directory\>/\<actual libraries\>*), so you in mingw build you need to place libraries in some additional subdirectory.
- `WIN_BUILD_DEPS` List of components required to build this one. [QubesBuilder](/doc/qubes-builder/) will copy files specified with `WIN_OUTPUT_HEADERS` and `WIN_OUTPUT_LIBS` of those components to some directory and provide its path with `QUBES_INCLUDES` and `QUBES_LIBS` variables. Use those variables in your build scripts (*sources* or *Makefile* - depending on selected compiler). You can assume that the variables are always set and directories always exists, even if empty.
builder.conf settings
---------------------

185
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.**
Building Qubes from scratch
===========================
# Building Qubes from scratch
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
@ -19,27 +18,29 @@ installation ISO, all in a [secure](/news/2016/05/30/build-security/) way.
In order to use it, you should use an rpm-based distro, like Fedora :), and should ensure the following packages are installed:
- sudo
- 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
- sudo
- 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
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.
All files created by the build system are contained within the qubes-builder directory.
@ -49,95 +50,107 @@ The build system is configured via builder.conf 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.:
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
NO_SIGN=1
```shell
cp example-configs/qubes-os-master.conf builder.conf
# 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.
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
%_gpg_path /home/user/.gnupg
%_gpg_name AC1BF9B3 # <-- Key ID used for signing
```bash
%_signature gpg
%_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.
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:
# Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
cd qubes-builder
```shell
# Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
# Verify its integrity:
git tag -v `git describe`
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
# NO_SIGN="1"
# Download all components:
make get-sources
# And now to build all Qubes rpms (this will take a few hours):
make qubes
# ... and then to build the ISO
make iso
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
cd qubes-builder
# Verify its integrity:
git tag -v `git describe`
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
# NO_SIGN="1"
# Download all components:
make get-sources
# And now to build all Qubes rpms (this will take a few hours):
make qubes
# ... and then to build the ISO
make iso
```
And this should produce a shiny new ISO.
You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon:
```shell
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
You can also modify sources somehow if you wish.
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)
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
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:
- 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**
5. Build the Qubes
5. Build the Qubes
`make qubes` actually is just meta target which builds all required
components in correct order. The list of components is configured in
builder.conf. You can also check the current value at the end of `make
help`, or using `make build-info`.
help`, or using `make build-info`.
6. `get-sources` is already done, so continue with the next one. You can skip `sign-all` if you've disabled signing
make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
```shell
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
make iso
```shell
make iso
```
### 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`:
USE_QUBES_REPO_VERSION = $(RELEASE)
```
USE_QUBES_REPO_VERSION = $(RELEASE)
```
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:
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`).
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:
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.
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.
@ -166,26 +185,26 @@ For legacy builds, it will not add the necessary configuration into the build en
Also, once enabled, disabling this setting will not disable repositories in relevant chroots.
And even if it did, there could be some leftover packages installed from those repos (which may or may not be desirable).
**Note**
**Note**
If you are building Ubuntu templates, you cannot use this option.
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.
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:
GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
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
```shell
GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc
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.
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).

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

@ -42,7 +42,7 @@ Get the necessary keys to verify the sources (run these and other commands below
~~~
wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
gpg --import qubes-master-signing-key.asc
gpg --import qubes-master-signing-key.asc
gpg --edit-key 36879494
fpr
# Verify fingerprint! See Note below!
@ -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.
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
-----------------
@ -128,7 +127,6 @@ make iso
Enjoy your new ISO!
Build using manual steps
-----------------

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

@ -4,14 +4,11 @@ title: 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.
Generating a Key
----------------
## Generating a Key
(Note: If you already have a PGP key, you may skip this step.)
@ -56,7 +53,7 @@ Real name: Bilbo Baggins
E-mail address: bilbo@shire.org
Comment:
Comment:
You selected this USER-ID:
"Bilbo Baggins <bilbo@shire.org>"
@ -78,8 +75,7 @@ uid Bilbo Baggins <bilbo@shire.org>
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.
@ -88,8 +84,7 @@ $ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85
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
your Git commits.
@ -112,7 +107,7 @@ your Git commits.
commit -S
~~~
3. (Optional) Create signed tags.
3. (Optional) Create signed tags.
Signed commits are totally sufficient to contribute to Qubes OS.
However, if you have commits which are not signed and you do not want to change them,
you can create a signed tag for the commit and push it before the check.
@ -141,8 +136,7 @@ your Git commits.
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
verified using any of the contributor’s GPG keys uploaded to GitHub. You can
@ -150,16 +144,15 @@ upload your public key on GitHub by adding your public GPG key on the [New GPG
key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
page].
Code Signature Checks
---------------------
## Code Signature Checks
The [signature-checker] checks if code contributions are signed.
Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed:
1. Is the commit signed?
1. Is the commit signed?
If the commit is not signed, you can see the message
> policy/qubesos/code-signing — No signature found
2. If the commit is signed, the key is downloaded from a GPG key server.
2. If the commit is signed, the key is downloaded from a GPG key server.
If you can see the following error message, please check if you have uploaded the key to a key server.
> policy/qubesos/code-signing — Unable to verify (no valid key found)
@ -169,23 +162,29 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s
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:
```
git commit --amend -S
```
This also rewrites the commit so you need to push it forcefully:
```
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,
you can create a signed tag for this commit and push the signature.
You can use the alias from above:
```
git checkout <commit>
git spush
```
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.
@ -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.
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.
One good way to do this is with a program like [Enigmail].
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].
Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[source code]: /doc/source-code/
[developer mailing list]: /support/#qubes-devel
@ -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
[GitHub New GPG key]: https://github.com/settings/gpg/new
[GitHub SSH GPG keys page]: https://github.com/settings/keys

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

@ -17,10 +17,10 @@ Rationale
Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why:
- It eases maintenance tasks, such as adding new functionality or generalizing code later,
- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
- It allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code...
- It eases maintenance tasks, such as adding new functionality or generalizing code later,
- It allows others (as well as the future you!) to easily understand fragments of code and what they were supposed to do, and thus makes it easier to later extend them with newer functionality or bug fixes,
- It allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code...
Often, developers, usually smart ones, undersell the value of proper coding style, thinking that it's much more important how their code works. These developers expect that if their code solves some problem using a nice and neat trick, then that's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, no matter how bright and smart, might not be a good fit for larger projects. Writing a clever exploit for a Black Hat show is one thing - writing useful software supposed to be used and maintained for years is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. At Qubes project, we often took shortcuts and wrote nasty code, and this has always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
@ -29,25 +29,25 @@ And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes
General typographic conventions
-------------------------------
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). If it makes you feel any better, assume this is just an arbitrary choice made to enforce a unified style.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, maintaining shorter line lengths improves readability. It also allows others to have two parallel windows open, side by side, each with different parts of the source code.
- **Naming conventions for any OS *other than Windows***:
- `ClassName`
- `some_variable`, `some_function`, `some_argument`
- **Naming conventions for any OS *other than Windows***:
- `ClassName`
- `some_variable`, `some_function`, `some_argument`
- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
- **Maintain a decent amount of horizontal spacing**, e.g. add a space after `if` or before `{` in C, and similar in other languages. Whether and where to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after or before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use ones like this: `if (condition)` instead.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings (--). This will allow the source code to be easily viewable in various Windows-based programs.
- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
- **Use descriptive names for variables and functions**! Really, at a time when most editors have auto-completion features, there is no excuse for using short variable names.
- **Comments should be indented together with the code**, e.g. like this:
- **Comments should be indented together with the code**, e.g. like this:
~~~
for (...) {
@ -61,33 +61,33 @@ General typographic conventions
File naming conventions
-----------------------
- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
**File naming in Linux/Unix-like systems:**
- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
- Helper, non-executable files in `/usr/share/qubes/`
- Various config files in `/etc/qubes`
- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
- All VM-related configs, images, and other files in `/var/lib/qubes/`
- System-wide temporary files which reflect the current state of system in `/var/run/qubes`
- Logs: either log to the system-wide messages, or to `/var/log/qubes/`
- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
- Helper, non-executable files in `/usr/share/qubes/`
- Various config files in `/etc/qubes`
- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
- All VM-related configs, images, and other files in `/var/lib/qubes/`
- System-wide temporary files which reflect the current state of system in `/var/run/qubes`
- Logs: either log to the system-wide messages, or to `/var/log/qubes/`
**File naming in Windows systems:**
- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
- Other, third-party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
General programming style guidelines
------------------------------------
- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
- Make sure your code compiles and builds without warnings.
- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
- Make sure your code compiles and builds without warnings.
- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
~~~
// Return window id
@ -97,7 +97,7 @@ General programming style guidelines
}
~~~
- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
- Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
~~~
#if 0
@ -117,42 +117,42 @@ General programming style guidelines
> But generally, there is little excuse to keep old, unused code fragments in the code. One should really use the functionality provided by the source code management system, such as git, instead. E.g. create a special branch for storing the old, unused code -- this way you will always be able to merge this code into upstream in the future.
- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
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:
- 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.
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
- Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
- We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html).
- 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.
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
- Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
- We have drastically changed the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html).
Commit message guidelines
-------------------------
Please attempt to follow these conventions when writing your Git commit messages:
* Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters.
* Capitalize the subject line.
* Do not end the subject line with a period.
* Use the imperative mood in the subject line.
* Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*.
- Separate the subject line from the body with a blank line.
- Limit the subject line to approximately 50 characters.
- Capitalize the subject line.
- Do not end the subject line with a period.
- Use the imperative mood in the subject line.
- Wrap the body at 72 characters.
- 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.
Security coding guidelines
--------------------------
- As a general rule: **untrusted input** is our \#1 enemy!
- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
- As a general rule: **untrusted input** is our \#1 enemy!
- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
~~~
read_struct(untrusted_conf);
@ -165,22 +165,22 @@ Security coding guidelines
height = untrusted_conf.height;
~~~
- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
- Use others variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
Python-specific guidelines
--------------------------
- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
C and C++ specific guidelines
-----------------------------
- Do not place code in `*.h` files.
- Use `const` whenever possible, e.g. in function arguments passed via pointers.
- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
- Think about classes hierarchy, before starting to implement specific methods.
- Do not place code in `*.h` files.
- Use `const` whenever possible, e.g. in function arguments passed via pointers.
- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
- Think about classes hierarchy, before starting to implement specific methods.
Bash-specific guidelines
------------------------
- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.
- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.

17
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
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.
* `gui-daemon.git` -- GUI virtualization, Dom0 side.
* `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
* `linux-template-builder.git` -- Scripts and other files used to create Qubes
* `gui-daemon.git` -- GUI virtualization, Dom0 side.
* `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
* `linux-template-builder.git` -- Scripts and other files used to create Qubes
template images.
All of our repositories are available under the [QubesOS GitHub account].
@ -35,9 +35,9 @@ e.g.:
git clone https://github.com/QubesOS/qubes-core-admin.git core-admin
~~~
To build Qubes you do not need to download all these repositories.
To build Qubes you do not need to download all these repositories.
If you use [qubes builder] you can specify *what* you want to build, and download only the repositories needed to build that target.
If you really do want to clone **all** of the repositories, you can use these commands:
~~~
@ -53,21 +53,20 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
(Alternatively, you can pull instead of just fetching.)
How to Send Patches
-------------------
If you want to [contribute code] to the project, there are two ways. Whichever
method you choose, you must [sign your code] before it can be accepted.
* **Preferred**: Use GitHub's [fork & pull requests].
* **Preferred**: Use GitHub's [fork & pull requests].
Opening a pull request on GitHub greatly eases the code review and tracking
process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list] in order to notify people who
do not receive GitHub notifications.
* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
* Send a patch to the [qubes-devel mailing list] (`git format-patch`).
1. Make all the changes in your working directory, i.e. edit files, move them
around (you can use 'git mv' for this), etc.

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

@ -7,14 +7,12 @@ redirect_from:
- /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.
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).
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).
The main purpose is, of course, to deliver much more stable releases.
The integration tests must be run in dom0, but some unit tests can run inside a VM as well.
@ -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:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -h
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
[--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:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
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:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking
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_030_edit_file
[user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
```
Example test run:
@ -115,11 +117,12 @@ Example test run:
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
```
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
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/).
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}
cd ~
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:
- `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_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)
- `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_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)
### 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)
#### 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`.
Again, given the hypothetical `example.py` test:
@ -213,7 +218,7 @@ class SomeTestCase(unittest.TestCase):
# first test that actually use event loop will try to dereference (already
# destroyed) objects, resulting in SEGV
self.loop = quamash.QEventLoop(self.qtapp)
def tearDown(self):
[...]
# process any pending events before destroying the object
@ -237,11 +242,10 @@ class SomeTestCase(unittest.TestCase):
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>
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
[OpenQA]: http://open.qa/

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

@ -6,8 +6,8 @@ permalink: /doc/mount-lvm-image/
# How to mount LVM image
You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0).
You want to read your LVM image (e.g., there is a problem where you can't start any VMs except dom0).
1: make the image available for qubesdb.
From dom0 terminal:
@ -25,7 +25,8 @@ From dom0 terminal:
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
[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
```
```bash
[user@dispXXXX]$ umount /mnt/
```
6: Remove the image from qubesdb
```
```bash
[user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
```
# 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

18
developer/debugging/profiling.md
View File

@ -8,15 +8,13 @@ redirect_from:
- /wiki/Profiling/
---
Profiling
=========
# Profiling
This is a python profiling primer.
For the purpose of this document, `qubes-dev` is name of the domain used for postprocessing profiling stats.
Requirements
------------
## Requirements
~~~
yum install gprof2dot graphviz
@ -30,10 +28,9 @@ mkdir -p ~/profiling
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
@ -43,17 +40,21 @@ You have to select the area in which you suspect less than optimal performance.
Replace
```python
def foo(self, bar):
# function content
```
with
```python
def foo(self, *args, **kwargs):
profile.runctx('self.real_foo(*args, **kwargs)', globals(), locals(),
time.strftime('/home/user/profiling/foo-%Y%m%d-%H%M%S.pstats'))
def real_foo(self, bar):
# function content
```
### 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
~~~
Example
-------
## Example
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/
---
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.
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.
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
# 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
dhclient
```
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).
Development VM
--------------
## Development VM
### SSH
@ -95,12 +94,15 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
`qtb-runtests`:
```bash
#!/bin/sh
ssh testbench python -m qubes.tests.run
```
`qtb-install`:
```bash
#!/bin/sh
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})"
shift
done
```
`qtb-iterate`:
```bash
#!/bin/sh
set -e
@ -136,6 +140,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your `${
make core-admin
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
qtb-runtests
```
### 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)
```bash
#!/bin/sh
set -e
python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
```
`core-admin/.git/hooks/pre-push`:
```bash
#!/bin/sh
exec qtb-iterate
```

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

@ -9,45 +9,43 @@ redirect_from:
- /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:
- QubesDB
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
- Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol
- QubesDB
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
- Qubes RPC (called at VM startup, or when configuration changed)
- 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-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `/qubes-vm-persistence` - what data do persist between VM restarts:
- `full` - all disks
- `rw-only` - only `/rw` disk
- `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `/qubes-netvm-primary-dns` - same as `qubes-primary-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 primary 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
- `/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-persistence` - what data do persist between VM restarts:
- `full` - all disks
- `rw-only` - only `/rw` disk
- `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)
- `/qubes-secondary-dns` - secondary DNS address (only when VM has netvm set)
- `/qubes-netvm-gateway` - same as `qubes-gateway` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-netmask` - same as `qubes-netmask` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM)
- `/qubes-netvm-network` - network address (only when VM serves as network backend - ProxyVM and NetVM); can be also calculated from qubes-netvm-gateway and qubes-netvm-netmask
- `/qubes-netvm-primary-dns` - same as `qubes-primary-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 primary 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
#### Firewall rules in 3.x ####
#### Firewall rules in 3.x
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
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
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
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.
Possible options for a single 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`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
- `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`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but
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`
- `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`
- `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
are forbidden.
@ -117,48 +115,46 @@ Example valid rules:
- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
- `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;
- 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 4.0+ format: used memory size in the VM, in kbytes
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
- `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 4.0+ format: used memory size in the VM, in kbytes
- `/qubes-block-devices` - list of block devices exposed by this VM, each device (subdirectory) should be named in a way that VM can attach the device based on it. Each should contain these entries:
- `desc` - device description (ASCII text)
- `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write
- `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3)
Qubes RPC
---------
## Qubes RPC
Services called by dom0 to provide some VM configuration:
- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
- `qubes.SetMonitorLayout` - provide list of monitors, one per line. Each line contains four numbers: `width height X Y width_mm height_mm` (physical dimensions - `width_mm` and `height_mm` - are optional)
- `qubes.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme
* `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name
2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel)
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
- `qubes.SetDateTime` - set VM time, called periodically by dom0 (can be
triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`.
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
- `qubes.SetGuiMode` - called in HVM to switch between fullscreen and seamless
GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS`
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
- `qubes.ResizeDisk` - called to inform that underlying disk was resized.
Name of disk image is passed on standard input (`root`, `private`, `volatile`,
or other). This is used starting with Qubes 4.0.
Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by
@ -193,19 +189,19 @@ Other Qrexec services installed by default:
can send icon for the same window multiple times to replace previous one (for
example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line
- `qubes.VMShell+WaitForSession` waits for full VM startup first
- `qubes.VMShell+WaitForSession` waits for full VM startup first
- `qubes.VMExec` - call any command in the VM, without using shell, the command
needs to be passed as argument and encoded as follows:
- the executable name and arguments are separated by `+`
- everything except alphanumeric characters, `.` and `_` needs to be
- the executable name and arguments are separated by `+`
- everything except alphanumeric characters, `.` and `_` needs to be
escaped
- bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
- `-` itself can be escaped as `--`
- example: to run `ls -a /home/user`, use
- bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
- `-` itself can be escaped as `--`
- example: to run `ls -a /home/user`, use
`qubes.VMExec+ls+--a+-2Fhome-2Fuser`
- `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM
startup first
Services called in GuiVM:
- `policy.Ask`, `policy.Notify` - confirmation prompt and notifications for
@ -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.
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.

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

@ -8,8 +8,7 @@ redirect_from:
- /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.
@ -17,22 +16,25 @@ User-mode debugging is usually straightforward if it can be done on one machine.
Things get complicated if you need to perform kernel debugging or troubleshoot problems that only manifest on system boot, user logoff or similar. For that you need two Windows VMs: the *host* and the *target*. The *host* will contain [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) installation, your source code and private symbols. The *target* will run the code being debugged. Both will be linked by virtual serial ports.
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
- 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:
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
- 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:
```bash
#!/bin/sh
id1=$(xl domid "$1-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
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
id1=$(xl domid "$1-dm")
@ -40,14 +42,15 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
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 *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.
- Reboot the *target* VM.
- 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:
- 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](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.
- 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:
~~~
Opened \\.\com1
@ -55,7 +58,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
Kernel Debugger connection established.
Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
Executable search path is:
Executable search path is:
... Retry sending the same data packet for 64 times.
The transport connection between host kernel debugger and target Windows seems lost.
please try resync with target, recycle the host debugger, or reboot the target Windows.
@ -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:
```c
#include <errno.h>
#include <stdio.h>
#include <fcntl.h>
@ -85,11 +89,11 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
{
static int count = 0;
static unsigned char buf[17] = {0};
// relay to ouptput port
write(fd2, &c, 1);
fprintf(stderr, "%c", mark);
/* dump all data going over the line
if (count == 0)
fprintf(stderr, "%c", mark);
@ -112,13 +116,13 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
unsigned char c = 0;
struct termios tio;
ssize_t size;
if (argc < 3)
{
fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
return EINVAL;
}
fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
if (fd1 <= 0)
{
@ -182,6 +186,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
close(fd2);
return 0;
}
```
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
>
@ -202,7 +207,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
> Kernel Debugger connection established.
> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
> Executable search path is:
> Executable search path is:
> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
> Machine Name:
@ -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.
## 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.
@ -228,15 +233,17 @@ $ gunzip stubdom-linux-rootfs.gz
$ cpio -i -d -H newc --no-absolute-filenames < 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.
3. Apply changes:
```shell_session
$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
```
## Connect two consoles ##
## Connect two consoles
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.
- 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:
* _[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 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
- 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:
* _[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:
* _[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
- _[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
(Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

50
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.
If you notice a problem or some way it can be improved, please [edit the documentation][contribute]!
## Security
*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.
In cases in which another reviewer is not required, the documentation maintainer may review the pull request (in which case no signed comment is necessary, since it would be redundant with the signed tag).
## Questions, problems, and improvements
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
@ -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].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
## How to contribute
Editing the documentation is easy, so if you see that a change should be made, please contribute it!
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.
* 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.
* 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.
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)
### How to add images
## How to add images
To add an image to a page, use the following syntax in the main document.
This will make the image a hyperlink to the image file, allowing the reader to click on the image in order to view the image by itself.
@ -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.
Do not link to images on other websites.
## Organizational guidelines
### Do not duplicate documentation
@ -231,7 +226,6 @@ To foo:
Once you foo, make sure to close the baz before fooing the next bar.
## Qubes 4.0 ##
### 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:
* 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 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.
@ -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.
Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
* It's hard for readers to miss information they need, since it's all in one place.
* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
* It's hard for readers to miss information they need, since it's all in one place.
In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page.
In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software.
* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions.
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
@ -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].
## 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.
* Syntactically distinguish variables in commands.
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
3. Using all capital letters
## Markdown conventions
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).
* 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.
* If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Use hanging indentations
* If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Use hanging indentations
where appropriate.
* 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 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.:
* 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 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.:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
@ -336,10 +329,12 @@ When making contributions, please try to observe the following style conventions
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.
* 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:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
@ -350,18 +345,17 @@ When making contributions, please try to observe the following style conventions
Hello
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
([This][md] is a great source for learning about Markdown.)
## Git conventions
Please try to write good commit messages, according to the
[instructions in our coding style guidelines][git-commit].
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[issue]: /doc/reporting-bugs/

194
developer/general/gsoc.md
View File

@ -98,17 +98,17 @@ If applicable, links to more information or discussions
**Expected results**:
- Design how Vagrant Qubes provider should look like, including:
- [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
- method for running commands inside (ssh vs qvm-run)
- 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
- Write integration tests
- Design how Vagrant Qubes provider should look like, including:
- [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
- method for running commands inside (ssh vs qvm-run)
- 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
- Write integration tests
**Knowledge prerequisite**:
- Ruby
- Vagrant concepts
- Ruby
- Vagrant concepts
**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.
- Documentation how to configure it securely.
**Knowledge prerequisite**:
- 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
Relevant links:
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [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)
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [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**:
@ -181,21 +181,21 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
**Expected results**:
- Adjust set of VMs and templates included in live edition.
- Update and fix build scripts for recent Qubes OS version.
- Update startup script to mount appropriate directories as either
copy-on-write (device-mapper snapshot), or tmpfs.
- 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
copy-on-write layer and tmpfs (disable logging etc).
- Research option to install the system from live image. If feasible add
this option.
- Adjust set of VMs and templates included in live edition.
- Update and fix build scripts for recent Qubes OS version.
- Update startup script to mount appropriate directories as either
copy-on-write (device-mapper snapshot), or tmpfs.
- 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
copy-on-write layer and tmpfs (disable logging etc).
- Research option to install the system from live image. If feasible add
this option.
**Knowledge prerequisite**:
- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
**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/)
-->
### LogVM(s)
**Project**: LogVM(s)
@ -232,35 +231,36 @@ immune to altering past entries. See
**Expected results**:
- Design a _simple_ protocol for transferring logs. The less metadata (parsed
in log-collecting VM) the better.
- Implement log collecting service. Besides logs itself, should save
information about logs origin (VM name) and timestamp. The service should
_not_ trust sending VM in any of those.
- Implement log forwarder compatible with systemd-journald and rsyslog. A
mechanism (service/plugin) fetching logs in real time from those and sending
to log-collecting VM over qrexec service.
- Document the protocol.
- Write unit tests and integration tests.
- Design a _simple_ protocol for transferring logs. The less metadata (parsed
in log-collecting VM) the better.
- Implement log collecting service. Besides logs itself, should save
information about logs origin (VM name) and timestamp. The service should
_not_ trust sending VM in any of those.
- Implement log forwarder compatible with systemd-journald and rsyslog. A
mechanism (service/plugin) fetching logs in real time from those and sending
to log-collecting VM over qrexec service.
- Document the protocol.
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- syslog
- systemd
- Python/Bash scripting
- syslog
- systemd
- Python/Bash scripting
**Mentor**: [Frédéric Pierret](/team/)
### Whonix IPv6 and nftables support
**Project**: Whonix IPv6 and nftables support
**Brief explanation**: [T509](https://phabricator.whonix.org/T509)
**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
- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39
- 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 - [issue](https://github.com/rustybird/corridor/issues/39)
- port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables
- make connections to IPv6 Tor relays work
- make connections to IPv6 destinations work
@ -293,19 +293,19 @@ immune to altering past entries. See
**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 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).
- (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)
- User documentation
- Automated tests (unit tests, integration tests)
- 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 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) 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
- Automated tests (unit tests, integration tests)
**Knowledge prerequisite**:
- Python scripting
- Linux administration, including handling loop devices, partition tables, filesystems etc
- For optional features, C language and x86 architecture (ACPI tables)
- Python scripting
- Linux administration, including handling loop devices, partition tables, filesystems etc
- For optional features, C language and x86 architecture (ACPI tables)
**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:
- patching window manager to add colorful borders
- 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)
- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
- patching window manager to add colorful borders
- 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)
- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
**Expected results**:
- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- Patch window manager to draw colorful borders (we use only server-side
decorations), there is already very similar patch in
[Cappsule project](https://github.com/cappsule/cappsule-gui).
- Configure GNOME to not make use of dom0 user home in visible way (no search
in files there, no file manager, etc).
- Configure GNOME to not look into external devices plugged in (no auto
mounting, device notifications etc).
- Package above modifications as rpms, preferably as extra configuration files
and/or plugins than overwriting existing files. Exceptions to this rule may
apply if no other option.
- Adjust comps.xml (in installer-qubes-os repo) to define package group with
all required packages.
- Document installation procedure.
- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- Patch window manager to draw colorful borders (we use only server-side
decorations), there is already very similar patch in
[Cappsule project](https://github.com/cappsule/cappsule-gui).
- Configure GNOME to not make use of dom0 user home in visible way (no search
in files there, no file manager, etc).
- Configure GNOME to not look into external devices plugged in (no auto
mounting, device notifications etc).
- Package above modifications as rpms, preferably as extra configuration files
and/or plugins than overwriting existing files. Exceptions to this rule may
apply if no other option.
- Adjust comps.xml (in installer-qubes-os repo) to define package group with
all required packages.
- Document installation procedure.
**Knowledge prerequisite**:
- GNOME architecture
- C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions
- GNOME architecture
- C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions
**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
### 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:
@ -384,22 +385,22 @@ Qubes currently only supports the x86_64 CPU architecture. Xen currently has add
Some related discussion:
- [#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.
- [#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.
**Expected results**:
- 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).
- Aarch64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
- 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).
- Aarch64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- Xen debugging.
- General ARM architecture knowledge.
- Libvirt and Qubes toolstacks (C and python languages).
- Xen debugging.
- General ARM architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
@ -426,17 +427,17 @@ More information and further links can be found in the related issue:
**Expected results**:
- 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).
- ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
- 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).
- ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals
- General ppc64 architecture knowledge.
- Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals
- General ppc64 architecture knowledge.
**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)
**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)
- 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
- documentation and tests
- documentation and tests
**Knowledge prerequisite**:
@ -521,7 +523,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
## Past Projects
You can view the projects we had in 2017 in the [GSoC 2017 archive][2017-archive]. We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive][2020-archive].
You can view the projects we had in 2017 in the [GSoC 2017 archive][2017-archive]. We also participated in GSoC 2020, and you can see the project in the [GSoC 2020 archive][2020-archive].
Here are some successful projects which have been implemented in the past by Google Summer of Code participants.
@ -551,14 +553,14 @@ would override all the user changes there). More details:
files, LVM thin volumes etc).
- template metadata, templates repository - enable the user to browse
available templates (probably should be done in dedicated VM, or DisposableVM)
- manual template removal by users (without it, see problems such
- manual template removal by users (without it, see problems such
as [#5509](https://github.com/QubesOS/qubes-issues/issues/5509)
- Implement the above mechanism:
- tool to download named template - should perform download operation in
some VM (as dom0 have no network access), then transfer the data to dom0,
verify its integrity and then create Template VM and feed it's root
filesystem image with downloaded data.
- tool to browse templates repository - both CLI and GUI (preferably integrated
- tool to browse templates repository - both CLI and GUI (preferably integrated
with existing Template Manager tool)
- integrate both tools - user should be able to choose some template to be
installed from repository browsing tool - see

41
developer/general/gsod.md
View File

@ -29,21 +29,22 @@ Here's a suggested template for adding project ideas:
**Mentor**: Name and email address.
```
### Offline documentation
**Project**: Offline documentation
**Brief explanation**: Qubes OS has thorough documentation on the project website, however a user may find it more convenient to view documentation - especially for troubleshooting network issues -- offline on their Qubes machine. This will improve usability for new users and better support users if they need to troubleshoot anything.
**Expected results**:
**Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
- Recommend workflow and platform for displaying offline documentation
- Test workflow and platform to ensure usability and functionality
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
- Recommend workflow and platform for displaying offline documentation
- Test workflow and platform to ensure usability and functionality
**Knowledge prerequisite**:
**Knowledge prerequisite**:
- [Markdown][markdown]
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
@ -53,14 +54,14 @@ Here's a suggested template for adding project ideas:
**Brief explanation**: When a user first boots Qubes after installing it, there is an opportunity to introduce the user to some of the unique functionality Qubes has.
**Expected results**:
**Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
- Provide visual mock-ups and proposed text
**Knowledge prerequisite**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
- Provide visual mock-ups and proposed text
- some experience with Anaconda would be helpful
**Knowledge prerequisite**:
- some experience with Anaconda would be helpful
**Mentor**: [Marek Marczykowski-Górecki][team]
@ -92,16 +93,16 @@ Additionally, terminology is used inconsistently.
**Brief explanation**: The Qubes OS is missing an installation guide for virtual machines. Users are installing an outdated and unsupported version of Qubes OS (3.2) instead of the supported version. There is unofficial [existing installation guide] for Qubes OS on a virtual box but it is misleading and lacks documentation. Usually, users face some errors and bugs while installing Qubes OS on a virtual machine.[virtual box issue]
**Expected results**:
**Expected results**:
-Provide a new option of installation guide for users working on virtual machines.
-Review existing problems and provide solutions to them.
-Giving a warning for using outdated versions.
**Knowledge prerequisite**:
**Knowledge prerequisite**:
- Experience in virtual boxes and machines.
- Basic Knowledge about Fedora linux architecture.
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
## Past Projects
@ -110,7 +111,7 @@ You can view the project we had in 2019 in the [2019 GSoD archive][2019-qubes-gs
You can also view the project we had in 2020 in the [2020 GSoD archive][2020-qubes-gsod] and the [2020 writer's report][2020-qubes-report].
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
### Consolidate troubleshooting guides
@ -135,14 +136,14 @@ This could be helped by writing consolidated guide with with a clear list of sym
**Project**: Improve Getting Started page
**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](#offline-documentation) or the [firstboot guide](#create-guide-on-firstboot-for-new-users).
**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](#offline-documentation) or the [firstboot guide](#create-guide-on-firstboot-for-new-users).
**Expected results**:
**Expected results**:
- Review the existing page and website, similar pages for other OSes
- Provide visual mock-ups and proposed text
- Provide visual mock-ups and proposed text
**Knowledge prerequisite**:
**Knowledge prerequisite**:
- basic Qubes OS knowledge
- [Markdown][markdown]

3
developer/general/join.md
View File

@ -9,5 +9,4 @@ Joining the Qubes OS Team
The Qubes OS Project does not currently have any open positions.
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/).

79
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
------------------
In order to be accepted, packages must:
* In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines].
* Be thoroughly tested.
* Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review.
* In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines].
* Be thoroughly tested.
* Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review.
(Please note that we always reserve the right to add criteria to this list.)
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].
Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
Please note that the Qubes core developers are very busy.
If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
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).
We appreciate your understanding!
5. You may be asked followup questions.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
If we decide not to accept your contribution, we will state the reason and close the issue.
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called [qubes-skeleton].
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
Please note that the Qubes core developers are very busy.
If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
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).
We appreciate your understanding!
5. You may be asked followup questions.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
If we decide not to accept your contribution, we will state the reason and close the issue.
Update Procedure
----------------
*Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package!
The update procedure is the same for everyone, including the original package contributor.
@ -57,6 +60,7 @@ Please be prepared to read and respond to these comments.
Review Procedure
----------------
This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]).
All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
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:
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].
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request 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.
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].
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request 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:
- Package dependencies,
- Build scripts (including downloaded ones),
- All downloaded components should be verified against static hash,
- RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
- Makefiles,
- Package build [reproducible]
* Package dependencies,
* Build scripts (including downloaded ones),
* All downloaded components should be verified against static hash,
* RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
* Makefiles,
* Package build [reproducible]
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
-------------------
If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise.
As the maintainer of the package, it is your privilege and responsibility to:
* [Review][Review Procedure] each pull request made against the package.
* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
* [Review][Review Procedure] each pull request made against the package.
* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
If you do not wish to be the maintainer of your package, please let us know.
If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
[installing contributed packages]: /doc/installing-contributed-packages/
[Inclusion Criteria]: #inclusion-criteria
[Contribution Procedure]: #contribution-procedure

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

@ -4,8 +4,7 @@ title: 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!
@ -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.
---
## Easy to Understand

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

@ -6,41 +6,36 @@ redirect_from:
- /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).
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).
- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
- If you don't enable Composition (System Setting -\> Desktop -\> Enable desktop effects), which you really should do, then the KDE task bar might get ugly (e.g. half of it might be black). This is some KDE bug that we don't plan to fix.
- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
- Some keyboard layout set by KDE System Settings can cause [keyboard not working at all](https://groups.google.com/group/qubes-devel/browse_thread/thread/77d076b65dda7226). If you hit this issue, you can switch to console (by console login option) and manually edit `/etc/X11/xorg.conf.d/00-system-setup-keyboard.conf` (and `/etc/sysconfig/keyboard`) and place correct keyboard layout settings (details in linked thread). You can check if specific keyboard layout settings are proper using `setxkbmap` tool.
- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
~~~
qvm-prefs -s fedora-17-x64-dvm maxmem 3072
qvm-create-default-dvm --default-template --default-script
~~~
- 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/).
Installation instructions
-------------------------
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
## Upgrading
### From Qubes 1.0-rc1
@ -51,6 +46,5 @@ If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just
If you have Qubes Beta 3 currently installed on your system, you must reinstall from scratch, as we offer no direct upgrade option in the installer (sorry). However, we do offer tools for smooth migration of your AppVMs. In order to do that, please backup your AppVMs using the `qvm-backup` tool [as usual](/doc/backup-restore/). Then, after you install Qubes 1.0 rc1, you can restore them using `qvm-backup-restore` tool. However, because we have changed the default template in RC1, you should tell qvm-back-restore about that by passing `--replace-template` option:
~~~
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/
---
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)
New features since 1.0
----------------------
## New features since 1.0
* Support for generic fully virtualized VMs (without qemu in the TCB!)
* 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
* 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.
Downloads
---------
## Downloads
See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions
-------------------------
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
## Upgrading
### 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/
---
Qubes R3.0 Release Notes
========================
### Qubes R3.0 Release Notes
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
possibilities of using different hypervisors. Currently Qubes OS uses Xen.
@ -27,8 +25,7 @@ New features since 2.0
templates using DispVM.
* 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
@ -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.
Downloads
---------
## Downloads
See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions
-------------------------
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
## Upgrading
### 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.
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/
---
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]
* 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]
Known issues
------------
## Known issues
* 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.
Downloads
---------
## Downloads
See [Qubes Downloads](/downloads/).
Installation instructions
-------------------------
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
## Upgrading
### 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 |
| 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 |
| 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/
---
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]
* 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]
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/).
@ -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.
Downloads
---------
## Downloads
See [Qubes Downloads](/downloads/).
Installation instructions
-------------------------
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
After installation, [manually upgrade to Fedora 26](/news/2018/01/06/fedora-26-upgrade/).
Upgrading
---------
## Upgrading
### 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 |
| 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 |
| <strike>23 Jul 2016</strike><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 |
| ~~16 Jul 2016~~ <br/> 20 Jul 2016 | current-testing freeze before 3.2-rc2 |
| ~~23 Jul 2016~~ <br/> 27 Jul 2016 | 3.2-rc2 release |
| ~~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 |
| 31 Aug 2016 | 3.2-rc3 release |
| 29 Sep 2016 | 3.2 release |

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

@ -40,28 +40,28 @@ Security Notes
These must be set manually.
* The following steps may need to be applied in dom0 and Fedora 26 TemplateVMs in order to receive updates (see [#3737]).
Steps for dom0 updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Terminal Emulator`.
3. In the window that opens, enter this command:
sudo nano /etc/yum.repos.d/qubes-dom0.repo
4. This opens the nano text editor. Change all four instances of `http` to `https`.
5. Press `CTRL+X`, then `Y`, then `ENTER` to save changes and exit.
6. Check for updates normally.
Steps for Fedora 26 TemplateVM updates:
1. Open the Qubes Menu by clicking on the "Q" icon in the top-left corner of the screen.
2. Select `Template: fedora-26`, then `fedora-26: Terminal`.
3. In the window that opens, enter the command for your version:
[Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo
4. This opens the gedit text editor in a window. Change all four instances of `http` to `https`.
5. Click the "Save" button in the top-right corner of the window.
6. Close the window.
@ -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.
We also provide [detailed instruction][upgrade-to-r4.0] for this procedure.
[backup]: /doc/backup-restore/
[github-release-notes]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+4.0%22+label%3Arelease-notes+is%3Aclosed
[custom-ip]: https://github.com/QubesOS/qubes-issues/issues/1477

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 |
| -----------:| --------------------------------------- |
| 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 |
| <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 |
| 6 Nov 2017 | decide whether 4.0-rc2 is the final 4.0 |
| ~~28 Aug 2017~~ <br/>~~11 Sep 2017~~ <br/>~~9 Oct 2017~~ <br/>18 Oct 2017 | current-testing freeze before 4.0-rc2 |
| ~~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
| 20 Nov 2017 | current-testing freeze before 4.0-rc3 |
| 27 Nov 2017 | 4.0-rc3 release |
| 11 Dec 2017 | decide whether 4.0-rc3 is the final 4.0 |
| 1 Jan 2018 | current-testing freeze before 4.0-rc4 |
| <strike>8 Jan 2018</strike><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 |
| ~~8 Jan 2018~~ <br/>31 Jan 2018 | 4.0-rc4 release |
| ~~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 |
| 6 Mar 2018 | 4.0-rc5 release |
| 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
=============
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)

9
developer/releases/schedules.md
View File

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

3
developer/releases/todo.md
View File

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

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

@ -148,23 +148,22 @@ to set the policy using current mechanism.
Volume properties:
- `pool`
- `vid`
- `size`
- `usage`
- `rw`
- `source`
- `save_on_stop`
- `snap_on_start`
- `revisions_to_keep`
- `is_outdated`
- `pool`
- `vid`
- `size`
- `usage`
- `rw`
- `source`
- `save_on_stop`
- `snap_on_start`
- `revisions_to_keep`
- `is_outdated`
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
- `cpu_time` - absolute CPU time (in milliseconds) spent by the VM since its startup, normalized for one CPU
- `cpu_usage` - CPU usage in percents
- `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_usage` - CPU usage in percents
## 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).
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 hash of the file).
- When calling `Replace` or `Remove`, you need to include the current token as

6
developer/services/dom0-secure-updates.md
View File

@ -18,9 +18,9 @@ Normally there should be few reasons for updating software in Dom0. This is beca
However, we anticipate some other situations when updating Dom0 software might be required:
- Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool)
- Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool)
Problems with traditional network-based update mechanisms
---------------------------------------------------------

36
developer/services/dvm-impl.md
View File

@ -20,19 +20,19 @@ DisposableVM is not started like other VMs, by executing equivalent of `xl creat
Preparing a savefile is done by `/usr/lib/qubes/qubes_prepare_saved_domain.sh` script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to "prerun" script. The script executes the following steps:
1. APPVM is started by `qvm-start`
2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created
3. if prerun script was specified, copy it to `qubes_save_script` xenstore key
4. wait for the `qubes_used_mem` key to appear
5. (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then
1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key
3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear
1. APPVM is started by `qvm-start`
2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created
3. if prerun script was specified, copy it to `qubes_save_script` xenstore key
4. wait for the `qubes_used_mem` key to appear
5. (in APPVM) APPVM boots normally, up to the point in `/etc/init.d/qubes_core` script when the presence of `qubes_save_request` key is tested. If it exists, then
1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
2. (in APPVM) the amount of used memory is stored to `qubes_used_mem` xenstore key
3. (in APPVM) busy-waiting for `qubes_restore_complete` xenstore key to appear
6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
7. APPVM private image is detached
8. the domain is saved via `xl save`
9. the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive
6. when `qubes_used_mem` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
7. APPVM private image is detached
8. the domain is saved via `xl save`
9. the COW file volatile.img (cow for root fs and swap) is packed to `saved_cows.tar` archive
The `qubes_prepare_saved_domain.sh` script is lowlevel. It is usually called by `qvm-create-default-dvm` script, that takes care of creating a special AppVM (named template\_name-dvm) to be passed to `qubes_prepare_saved_domain.sh`, as well as copying the savefile to /dev/shm (the latter action is not done if the `/var/lib/qubes/dvmdata/dont_use_shm` file exists).
@ -41,12 +41,12 @@ Restoring a DisposableVM from the savefile
Normally, disposable VM is created when qubes rpc request with target *\$dispvm* is received. Then, as a part of rpc connection setup, the `qfile-daemon-dvm` program is executed; it executes `/usr/lib/qubes/qubes_restore` program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are:
1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
2. restore the COW files from the `saved_cows.tar`
3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible.
4. execute `xl restore` in order to restore a domain.
5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`)
6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue.
1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
2. restore the COW files from the `saved_cows.tar`
3. create the `/var/run/qubes/fast_block_attach` file, whose presence tells the `/etc/xen/scripts/block` script to bypass some redundant checks and execute as fast as possible.
4. execute `xl restore` in order to restore a domain.
5. create the same xenstore keys as normally created when AppVM boots (e.g. `qubes_ip`)
6. create the `qubes_restore_complete` xenstore key. This allows the boot process in DisposableVM to continue.
The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.

8
developer/services/qfilecopy.md
View File

@ -13,15 +13,15 @@ InterVM file copy design
There are two cases when we need a mechanism to copy files between VMs:
- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.
- "regular" file copy - when user instructs file manager to copy a given files/directories to a different VM
- DispVM copy - user selects "open in DispVM" on a file; this file must be copied to a DisposableVM, edited by user, and possibly a modified file copied back from DispVM to VM.
Prior to Qubes Beta1, for both cases, a block device (backed by a file in dom0 with a vfat filesystem on it) was attached to VM, file(s) copied there, and then the device was detached and attached to target VM. In the DispVM case, if a edited file has been modified, another block device is passed to requester VM in order to update the source file.
This has the following disadvantages:
- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement.
- security - VM kernel parses partition table and filesystem metadata from the block device; they are controlled by (potentially untrusted) sender VM.
In Qubes Beta1, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. In Qubes Beta2, even more generic solution (qubes rpc) is used. See the developer docs on qrexec and qubes rpc. In a nutshell, the file sender and the file receiver just read/write from stdin/stdout, and the qubes rpc layer passes data properly - so, no block devices are used.

35
developer/services/qfileexchgd.md
View File

@ -21,37 +21,36 @@ Overview
*qfilexchgd* is a dom0 daemon responsible for managing exchange of block devices ("virtual pendrives") between VMs. It is used for
- copying files between AppVMs
- copying a single file between an AppVM and a DisposableVM
- copying files between AppVMs
- copying a single file between an AppVM and a DisposableVM
*qfilexchgd* is started after first *qubes\_guid* has been started, so that it has access to X display in dom0 to present dialog messages.
*qfilexchgd* is event driven. The sources of events are:
- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary
- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
- trigger of xenstore watch for the changes in `/local/domain` xenstore hierarchy - to detect start/stop of VMs, and maintain vmname-\>vm\_xid dictionary
- trigger of xenstore watch for a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
Copying files between AppVMs
----------------------------
1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1.
2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it.
3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM.
4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates.
1. AppVM1 user runs *qvm-copy-to-vm* script (accessible from Dolphin file manager by right click on a "file(s)-\>Actions-\>Send to VM" menu). It calls */usr/lib/qubes/qubes\_penctl new*, and it writes "new" request to its `device/qpen` xenstore key. *qfilexchgd* creates a new 1G file, makes vfat fs on it, and does block-attach so that this file is attached as `/dev/xvdg` in AppVM1.
2. AppVM1 mounts `/dev/xvdg` on `/mnt/outgoing` and copies requested files there, then unmounts it.
3. AppVM1 writes "send DestVM" request to its `device/qpen` xenstore key (calling */usr/lib/qubes/qubes\_penctl send DestVM*). After getting confirmation by displaying a dialog box in dom0 display, *qfilexchgd* detaches `/dev/xvdg` from AppVM1, attaches it as `/dev/xvdh` to DestVM.
4. In DestVM, udev script for `/dev/xvdh` named *qubes\_add\_pendrive\_script* (see `/etc/udev/rules.d/qubes.rules`) mounts `/dev/xvdh` on `/mnt/incoming`, and then waits for `/mnt/incoming` to become unmounted. A file manager running in DestVM shows a new volume, and user in DestVM may copy files from it. When user in DestVM is done, then user unmounts `/mnt/incoming`. *qubes\_add\_pendrive*\_script then tells *qfilexchgd* to detach `/dev/xvdh` and terminates.
Copying a single file between AppVM and a DisposableVM
------------------------------------------------------
In order to minimize attack surface presented by necessity to process virtual pendrive metadata sent by (potentially compromised and malicious) DisposableVM, AppVM\<-\>DisposableVM file exchange protocol does not use any filesystem.
1. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm*
1. gets a new `/dev/xvdg` (just as described in previous paragraph)
2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents,
3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ`
4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents
5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key.
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.
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. User in AppVM1 runs *qvm-open-in-dvm* (accessible from Dolphin file manager by right click on a "file-\>Actions-\>Open in DisposableVM" menu). *qvm-open-in-dvm*
1. gets a new `/dev/xvdg` (just as described in previous paragraph)
2. computes a new unique transaction seq SEQ by incrementing `/home/user/.dvm/seq` contents,
3. writes the requested file name (say, /home/user/document.txt) to `/home/user/.dvm/SEQ`
4. creates a dvm\_header (see core.git/appvm/dvm.h) on `/dev/xvdg`, followed by file contents
5. writes the "send disposable SEQ" command to its `device/qpen` xenstore key.
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.
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.

49
developer/services/qmemman.md
View File

@ -18,8 +18,8 @@ Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the opti
The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon. All VMs report their memory usage (via xenstore) to *qmemman*, and it makes decisions on whether to balance memory across domains. The actual mechanism to add/remove memory from a domain (*xc.domain\_set\_target\_mem*) is already supported by both PV Linux guests and Windows guests (the latter via PV drivers).
@ -27,24 +27,24 @@ Similarly, when there is need for Xen free memory (for instance, in order to cre
To sum up, *qmemman* pros and cons. Pros:
- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
- works well in practice, with less than 1% CPU consumption in the idle case
- simple, concise implementation
- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
- works well in practice, with less than 1% CPU consumption in the idle case
- simple, concise implementation
Cons:
- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements
- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality
- *qmemman* is notified by a VM about memory usage change not more often than 10 times per second (to limit CPU overhead in VM). Thus, there can be up to 0.1s delay until qmemman starts to react to the new memory requirements
- it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
Interface
---------
*qmemman* listens for the following events:
- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data
- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol.
- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed.
- writes to `/local/domain/domid/memory/meminfo` xenstore keys by *meminfo-writer* process in VM. The content of this key is taken from the VM's `/proc/meminfo` pseudofile ; *meminfo-writer* just strips some unused lines from it. Note that *meminfo-writer* writes its xenstore key only if the VM memory usage has changed significantly enough since the last update (by default 30MB), to prevent flooding with almost identical data
- commands issued over Unix socket `/var/run/qubes/qmemman.sock`. Currently, the only command recognized is to free the specified amount of memory. The QMemmanClient class implements the protocol.
- if the `/var/run/qubes/do-not-membalance` file exists, *qmemman* suspends memory balancing. It is primarily used when allocating memory for a to-be-created domain, to prevent using up the free Xen memory by the balancing algorithm before the domain creation is completed.
Algorithms basics
-----------------
@ -53,28 +53,27 @@ The core VM property is `prefmem`. It denotes the amount of memory that should b
Whenever *meminfo-writer* running in domain A provides new data on memory usage to *qmemman*, the `prefmem` value for A is updated and the following balance algorithm (*qmemman\_algo.balance*) is triggered. Its output is the list of (domain\_id, new\_memory\_target\_to\_be\_set) pairs:
1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains
2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory
3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem`
2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem`
1. TOTAL\_PREFMEM = sum of `prefmem` of all participating domains
2. TOTAL\_MEMORY = sum of all memory assigned to participating domains plus Xen free memory
3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem`
2. redistribute memory reclaimed in the previous step between the rest of domains, proportionally to their `prefmem`
In order to avoid too frequent memory redistribution, it is actually executed only if one of the below conditions hold:
- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB)
- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it
- the sum of memory size changes for all domains is more than MIN\_TOTAL\_MEMORY\_TRANSFER (150MB)
- one of the domains is below its `prefmem`, and more than MIN\_MEM\_CHANGE\_WHEN\_UNDER\_PREF (15MB) would be added to it
Additionally, the balance algorithm is tuned so that XEN\_FREE\_MEM\_LEFT (50MB) is always left as Xen free memory, to make coherent memory allocations in driver domains work.
Whenever *qmemman* is asked to return X megabytes of memory to Xen free pool, the following algorithm (*qmemman\_algo.balloon*) is executed:
1. find all domains ("donors") whose actual memory is greater than its `prefmem`
2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error.
3. shrink donors, proportionally to their `prefmem`, so that X MB should become free
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).
1. find all domains ("donors") whose actual memory is greater than its `prefmem`
2. calculate how much memory can be reclaimed by shrinking donors to their `prefmem`. If it is less than X, return error.
3. shrink donors, proportionally to their `prefmem`, so that X MB should become free
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).
Notes
-----

48
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.
`qrexec-daemon` is responsible for both:
- 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`).
@ -39,9 +40,9 @@ Command line usage:
`qrexec-daemon domain-id domain-name [default user]`
* `domain-id`: Numeric Qubes ID assigned to the associated domain.
* `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.
- `domain-id`: Numeric Qubes ID assigned to the associated domain.
- `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.
### qrexec-client
@ -51,11 +52,11 @@ Used to pass execution and service requests to `qrexec-daemon`.
Command line usage:
* `-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.
* `-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.
* `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example.
- `-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.
- `-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.
- `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
@ -65,8 +66,9 @@ Command line usage:
One instance runs in each active domain.
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.
@ -81,26 +83,30 @@ Command line usage:
`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.
* `service-name`: Requested service name.
* `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint.
- `target-domain-name`: Target domain for the service request. Source is the current domain.
- `service-name`: Requested service name.
- `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint.
## Qrexec protocol details
The qrexec protocol is message-based.
All messages share a common header followed by an optional data packet.
/* uniform for all peers, data type depends on message type */
struct msg_header {
uint32_t type; /* message type */
uint32_t len; /* data length */
};
```c
/* uniform for all peers, data type depends on message type */
struct msg_header {
uint32_t type; /* message type */
uint32_t len; /* data length */
};
```
When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
struct peer_info {
uint32_t version; /* qrexec protocol version */
};
```c
struct peer_info {
uint32_t version; /* qrexec protocol version */
};
```
The client then should reply with its own `MSG_HELLO` and `peer_info`.
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`.
When running in a VM, this is:
```
<service_name> <source>\0
```
When running in dom0, it is:
```
<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`).

76
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
stdin/stdout, and a policy framework to control this all.
## Qrexec basics ##
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:
```shell_session
[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.
@ -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
sections.
## Qubes RPC services ##
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
process in the requesting VM (see example Hello World service described below).
## Qubes RPC administration ##
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
access policy database. Some example of the default services in Qubes are:
```
qubes.Filecopy
qubes.OpenInVM
qubes.ReceiveUpdates
@ -109,10 +109,13 @@ access policy database. Some example of the default services in Qubes are:
qubes.Gpg
qubes.NotifyUpdates
qubes.PdfConvert
```
These files contain lines with the following format:
```
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`,
`$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
name of the program that will be invoked.
### Requesting VM-VM (and VM-Dom0) services execution ###
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]
```
Note that only stdin/stdout is passed between RPC server and client --
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
(example below for `qubes.Filecopy` service):
```shell_session
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
```
and then remove any line(s) ending in "allow" (before the first `##` comment)
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
a trusted to untrusted domain, or vice-versa.
### Qubes RPC "Hello World" service ###
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.
* 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
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
```
* 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
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
```
* 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
```
* 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
```
* 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
```
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
@ -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
surfaces that are exposed to untrusted or less trusted VMs in that case.
# Qubes RPC internals #
(*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
run without modification on Qubes R3.*)
## Dom0 tools implementation ##
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.
* `/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.
* `/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`)
**Note:** None of the above tools are designed to be used by users.
## Linux VMs implementation ##
Players:
* `/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/qrexec-agent`: started by VM bootup scripts, a daemon.
* `/usr/lib/qubes/qubes-rpc-multiplexer`: executes the actual service program,
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.
**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.
## Windows VMs implementation ##
`%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
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.
* `%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
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.
**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.
## All the pieces together at work ##
**Note:** This section is not needed to use qrexec for writing Qubes
@ -298,30 +308,30 @@ vchan connections.
When a user in a source VM executes `qrexec-client-vm` utility, the following
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
each of them, which is the fd number of the accepted socket in agent. These
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
* `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
`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
* `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
* `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.
* 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
the existing process file descriptors (these are the fds of unix socket
created in step 1).
* The second `qrexec-client` connects to the target VM, and executes
* The second `qrexec-client` connects to the target VM, and executes
`qubes-rpc-multiplexer` command there with the rpc action as the cmdline
argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server
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`
process to exit, and then destroys the DispVM.

60
developer/system/architecture.md
View File

@ -18,25 +18,23 @@ 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.
Key Architecture features
-------------------------
- Based on a secure bare-metal hypervisor (Xen)
- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d)
- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
- No networking code in the privileged domain (dom0)
- All user applications run in “AppVMs,” lightweight VMs based on Linux
- Centralized updates of all AppVMs based on the same template
- Qubes GUI virtualization presents applications as if they were running locally
- Qubes GUI provides isolation between apps sharing the same desktop
- Secure system boot based (optional)
- Based on a secure bare-metal hypervisor (Xen)
- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d)
- USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
- No networking code in the privileged domain (dom0)
- All user applications run in “AppVMs,” lightweight VMs based on Linux
- Centralized updates of all AppVMs based on the same template
- Qubes GUI virtualization presents applications as if they were running locally
- Qubes GUI provides isolation between apps sharing the same desktop
- Secure system boot based (optional)
(For those interested in the history of the project, [Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf) is the original 2009 document that started this all.
Please note that this document is for historical interest only.
For the latest information, please see the rest of the [System Documentation](/doc/#system).)
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
the Qubes system include:
- VM-located core agents (implementing e.g. qrexec endpoints used by various
Qubes services)
- VM-customizations (making the VMs lightweight and working well with seamless
GUI virtualization)
- 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),
- GUI domain customizations (Desktop Environment customizations, decoration
coloring plugin, etc)
- The AdminVM distribution (various customizations, special services, such as
for receiving and verifying updates, in the future: custom distro)
- The Xen hypervisor (with a bunch of customization patches, occasional
hardening) or - in the future - some other virtualising or containerizing
software or technology
- Multiple "Qubes Apps" (various services built on top of Qubes qrexec
infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
USB proxies for HID devices, USB proxy for offering USB devices (exposed via
qvm-usb), Yubikey support, USB Armory support, etc)
- 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
- Salt Stack integration
- VM-located core agents (implementing e.g. qrexec endpoints used by various
Qubes services)
- VM-customizations (making the VMs lightweight and working well with seamless
GUI virtualization)
- 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),
- GUI domain customizations (Desktop Environment customizations, decoration
coloring plugin, etc)
- The AdminVM distribution (various customizations, special services, such as
for receiving and verifying updates, in the future: custom distro)
- The Xen hypervisor (with a bunch of customization patches, occasional
hardening) or - in the future - some other virtualising or containerizing
software or technology
- Multiple "Qubes Apps" (various services built on top of Qubes qrexec
infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
USB proxies for HID devices, USB proxy for offering USB devices (exposed via
qvm-usb), Yubikey support, USB Armory support, etc)
- 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
- Salt Stack integration
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.
It consists of two parts:
- `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)
- `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)
Protocol
--------
@ -33,10 +33,10 @@ Each such notification is a 4-byte number in little-endian format.
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.
- `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).
- `0x00020001` -- VM does want to send audio output.
- `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.
- `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.
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.
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)
- object path: `/org/qubesos/audio`
- interface: `org.qubesos.Audio`
- property: `RecAllowed` (which can be set using the `org.freedesktop.DBus.Properties` interface)
- destination: `org.qubesos.Audio.VMNAME` (where `VMNAME` is the VM's name)
- object path: `/org/qubesos/audio`
- interface: `org.qubesos.Audio`
- 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).
Supported commands:
- `audio-input 1\n` - enable audio input
- `audio-input 0\n` - disable audio input
- `audio-input 1\n` - enable 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.
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.
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).

226
developer/system/gui.md
View File

@ -17,23 +17,23 @@ qubes_gui and qubes_guid processes
All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers:
- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below)
- *dummyqsb_drv* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
- *qubes_drv* - it provides a virtual keyboard and mouse (in fact, more, see below)
For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan.
For each AppVM, there is a pair of *qubes_gui* (running in AppVM) and *qubes_guid* (running in dom0) processes connected over vchan.
The main responsibilities of *qubes_gui* are:
- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer
- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0
- receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events
- receive information about window size/position change, apply them to the local window
- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer
- instruct the local Xorg server to notify it about window creation, configuration and damage events; pass information on these events to dom0
- receive information about keyboard and mouse events from dom0, tell *qubes_drv* to fake appropriate events
- receive information about window size/position change, apply them to the local window
The main responsibilities of *qubes_guid* are:
- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui*
- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data)
- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
- receive information about window size/position change, apply them to the local window
- create a window in dom0 whenever an information on window creation in AppVM is received from *qubes_gui*
- whenever the local window receives XEvent, pass information on it to AppVM (particularly, mouse and keyboard data)
- whenever AppVM signals damage event, tell local Xorg server to repaint a given window fragment
- receive information about window size/position change, apply them to the local window
Note that keyboard and mouse events are passed to AppVM only if a window belonging to this AppVM has focus.
AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTEST extension will report the status of local AppVM keyboard only) or synthesize and pass events to other AppVMs.
@ -41,30 +41,30 @@ AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTES
Window content updates implementation
-------------------------------------
Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp).
As that channel has limited throughput, this impacts video performance.
Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp).
As that channel has limited throughput, this impacts video performance.
In the case of Qubes, *qubes_gui* does not transfer all changed pixels via vchan. Instead, for each window, upon its creation or size change, *qubes_gui*
- asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window
- passes this information via `MFNDUMP` message to *qubes_guid* in dom0
- asks *qubes_drv* driver for the list of physical memory frames that hold the composition buffer of a window
- passes this information via `MFNDUMP` message to *qubes_guid* in dom0
Now, *qubes_guid* has to tell the dom0 Xorg server about the location of the buffer.
There is no supported way (e.g. Xorg extension) to do this zero-copy style.
Now, *qubes_guid* has to tell the dom0 Xorg server about the location of the buffer.
There is no supported way (e.g. Xorg extension) to do this zero-copy style.
The following method is used in Qubes:
- in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory.
- *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension
- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages*
- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this.
- in dom0, the Xorg server is started with *LD_PRELOAD*-ed library named *shmoverride.so*. This library hooks all function calls related to shared memory.
- *qubes_guid* creates a shared memory segment, and then tells Xorg to attach it via *MIT-SHM* extension
- when Xorg tries to attach the segment (via glibc *shmat*) *shmoverride.so* intercepts this call and instead maps AppVM memory via *xc_map_foreign_pages*
- since then, we can use MIT-SHM functions, e.g. *XShmPutImage* to draw onto a dom0 window. *XShmPutImage* will paint with DRAM speed; actually, many drivers use DMA for this.
The important detail is that *xc_map_foreign_pages* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*).
The important detail is that *xc_map_foreign_pages* verifies that a given mfn range actually belongs to a given domain id (and the latter is provided by trusted *qubes_guid*).
Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message.
To sum up, this solution has the following benefits:
- window updates at DRAM speed
- no changes to Xorg code
- minimal size of the supporting code
- window updates at DRAM speed
- no changes to Xorg code
- minimal size of the supporting code
![gui.png](/attachment/wiki/GUIdocs/gui.png)
@ -78,14 +78,14 @@ In Qubes, a custom window decorator is used that paints a colourful frame (the c
Clipboard sharing implementation
--------------------------------
Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally.
Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally.
Therefore, the following mechanism is used:
- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0.
- if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents.
- the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally.
- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0.
- if the user wants to copy local AppVM clipboard to qubes clipboard, she must focus on any window belonging to this AppVM, and press **Ctrl-Shift-C**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_REQ` message is sent to AppVM. *qubes-gui* responds with *CLIPBOARD_DATA* message followed by clipboard contents.
- the user focuses on other AppVM window, presses **Ctrl-Shift-V**. This combination is trapped by *qubes-guid*, and `CLIPBOARD_DATA` message followed by qubes clipboard contents is sent to AppVM; *qubes_gui* copies data to the local clipboard, and then user can paste its contents to local applications normally.
This way, the user can quickly copy clipboards between AppVMs.
This way, the user can quickly copy clipboards between AppVMs.
This action is fully controlled by the user, it cannot be triggered/forced by any AppVM.
*qubes_gui* and *qubes_guid* code notes
@ -93,20 +93,20 @@ This action is fully controlled by the user, it cannot be triggered/forced by an
Both applications are structured similarly. They use *select* function to wait for any of these two event sources:
- messages from the local X server
- messages from the vchan connecting to the remote party
- messages from the local X server
- messages from the vchan connecting to the remote party
The XEvents are handled by the *handle_xevent_eventname* function, and messages are handled by *handle_messagename* function. One should be very careful when altering the actual *select* loop, because both XEvents and vchan messages are buffered, and *select* will not wake for each message.
If one changes the number/order/signature of messages, one should increase the *QUBES_GUID_PROTOCOL_VERSION* constant in *messages.h* include file.
*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*.
*qubes_guid* writes debugging information to */var/log/qubes/qubes.domain_id.log* file; *qubes_gui* writes debugging information to */var/log/qubes/gui_agent.log*.
Include these files when reporting a bug.
AppVM -> dom0 messages
-----------------------
Proper handling of the below messages is security-critical.
Proper handling of the below messages is security-critical.
Observe that beside two messages (`CLIPBOARD` and `MFNDUMP`) the rest have fixed size, so the parsing code can be small.
The *override_redirect* window attribute is explained at [Override Redirect Flag](https://tronche.com/gui/x/xlib/window/attributes/override-redirect.html). The *transient_for* attribute is explained at [Transient_for attribute](https://tronche.com/gui/x/icccm/sec-4.html#WM_TRANSIENT_FOR).
@ -115,8 +115,8 @@ Window manager hints and flags are described in the [Extended Window Manager Hin
Each message starts with the following header:
~~~
struct msghdr {
```c
struct msghdr {
uint32_t type;
uint32_t window;
/* This field is intended for use by gui_agents to skip unknown
@ -126,7 +126,7 @@ struct msghdr {
* whatever it wants! */
uint32_t untrusted_len;
};
~~~
```
This header is followed by message-specific data:
@ -164,9 +164,9 @@ struct msg_create {
<tr>
<td>MSG_MAP</td>
<td><pre>
struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
};
</pre></td>
<td>Map a window with given parameters</td>
@ -179,12 +179,12 @@ struct msg_map_info {
<tr>
<td>MSG_CONFIGURE</td>
<td><pre>
struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
};
</pre></td>
<td>Change window position/size/type</td>
@ -192,15 +192,15 @@ struct msg_configure {
<tr>
<td>MSG_MFNDUMP</td>
<td><pre>
struct shm_cmd {
uint32_t shmid;
uint32_t width;
uint32_t height;
uint32_t bpp;
uint32_t off;
uint32_t num_mfn;
uint32_t domid;
uint32_t mfns[0];
struct shm_cmd {
uint32_t shmid;
uint32_t width;
uint32_t height;
uint32_t bpp;
uint32_t off;
uint32_t num_mfn;
uint32_t domid;
uint32_t mfns[0];
};
</pre></td>
<td>Retrieve the array of mfns that constitute the composition buffer of a remote window.
@ -211,8 +211,8 @@ struct shm_cmd {
<tr>
<td>MSG_SHMIMAGE</td>
<td><pre>
struct msg_shmimage {
uint32_t x;
struct msg_shmimage {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
@ -223,8 +223,8 @@ struct msg_shmimage {
<tr>
<td>MSG_WMNAME</td>
<td><pre>
struct msg_wmname {
char data[128];
struct msg_wmname {
char data[128];
};
</pre></td>
<td>Set the window name; only printable characters are allowed</td>
@ -237,16 +237,16 @@ struct msg_wmname {
<tr>
<td>MSG_WINDOW_HINTS</td>
<td><pre>
struct msg_window_hints {
uint32_t flags;
uint32_t min_width;
uint32_t min_height;
uint32_t max_width;
uint32_t max_height;
uint32_t width_inc;
uint32_t height_inc;
uint32_t base_width;
uint32_t base_height;
struct msg_window_hints {
uint32_t flags;
uint32_t min_width;
uint32_t min_height;
uint32_t max_width;
uint32_t max_height;
uint32_t width_inc;
uint32_t height_inc;
uint32_t base_width;
uint32_t base_height;
};
</pre> </td>
<td>Size hints for window manager</td>
@ -254,7 +254,7 @@ struct msg_window_hints {
<tr>
<td>MSG_WINDOW_FLAGS</td>
<td><pre>
struct msg_window_flags {
struct msg_window_flags {
uint32_t flags_set;
uint32_t flags_unset;
};
@ -279,12 +279,12 @@ Proper handling of the below messages is NOT security-critical.
Each message starts with the following header
~~~
struct msghdr {
```c
struct msghdr {
uint32_t type;
uint32_t window;
};
~~~
```
The header is followed by message-specific data:
@ -297,12 +297,12 @@ The header is followed by message-specific data:
<tr>
<td>MSG_KEYPRESS</td>
<td><pre>
struct msg_keypress {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t keycode;
struct msg_keypress {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t keycode;
};
</pre> </td>
<td>Tell *qubes_drv* driver to generate a keypress</td>
@ -310,12 +310,12 @@ struct msg_keypress {
<tr>
<td>MSG_BUTTON</td>
<td><pre>
struct msg_button {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t button;
struct msg_button {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t button;
};
</pre> </td>
<td>Tell *qubes_drv* driver to generate mouseclick</td>
@ -323,11 +323,11 @@ struct msg_button {
<tr>
<td>MSG_MOTION</td>
<td><pre>
struct msg_motion {
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t is_hint;
struct msg_motion {
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t is_hint;
};
</pre> </td>
<td>Tell *qubes_drv* driver to generate motion event</td>
@ -335,12 +335,12 @@ struct msg_motion {
<tr>
<td>MSG_CONFIGURE</td>
<td><pre>
struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
};
</pre> </td>
<td>Change window position/size/type</td>
@ -348,9 +348,9 @@ struct msg_configure {
<tr>
<td>MSG_MAP</td>
<td><pre>
struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
};
</pre> </td>
<td>Map a window with given parameters</td>
@ -363,14 +363,14 @@ struct msg_map_info {
<tr>
<td>MSG_CROSSING</td>
<td><pre>
struct msg_crossing {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t mode;
uint32_t detail;
uint32_t focus;
struct msg_crossing {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t mode;
uint32_t detail;
uint32_t focus;
};
</pre> </td>
<td>Notify window about enter/leave event</td>
@ -378,10 +378,10 @@ struct msg_crossing {
<tr>
<td>MSG_FOCUS</td>
<td><pre>
struct msg_focus {
uint32_t type;
uint32_t mode;
uint32_t detail;
struct msg_focus {
uint32_t type;
uint32_t mode;
uint32_t detail;
};
</pre> </td>
<td>Raise a window, XSetInputFocus</td>
@ -409,8 +409,8 @@ struct msg_focus {
<tr>
<td>MSG_WINDOW_FLAGS</td>
<td><pre>
struct msg_window_flags {
uint32_t flags_set;
struct msg_window_flags {
uint32_t flags_set;
uint32_t flags_unset;
};
</pre> </td>

19
developer/system/networking.md
View File

@ -9,18 +9,15 @@ redirect_from:
- /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.
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:
@ -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|
|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.
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:
```
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:
```
qvm-features ipv4-only-qube ipv6 ''
```
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.
### 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.
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].
Security-critical Qubes-specific Components
-------------------------------------------
The following code components are security-critical in Qubes OS:
- Dom0-side of the libvchan library
- Dom0-side of the GUI virtualization code (`qubes-guid`)
- Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
- Dom0-side in qrexec-related code (`qrexec_daemon`)
- VM memory manager (`qmemman`) that runs in Dom0
- 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)
- Dom0-side of the libvchan library
- Dom0-side of the GUI virtualization code (`qubes-guid`)
- Dom0-side of the sound virtualization code (`pacat-simple-vchan`)
- Dom0-side in qrexec-related code (`qrexec_daemon`)
- VM memory manager (`qmemman`) that runs in Dom0
- 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)
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.
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
- Xen's xenstore backend running in Dom0
- Xen's block backend running in Dom0's kernel
- The RPM program used in Dom0 for verifying signatures on dom0 updates
- Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
- The Xen hypervisor
- Xen's xenstore backend running in Dom0
- Xen's block backend running in Dom0's kernel
- The RPM program used in Dom0 for verifying signatures on dom0 updates
- Somewhat trusted: log viewing software in dom0 that parses VM-influenced logs
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):
- Xen network PV frontends
- VMs' core networking stacks (core TCP/IP code)
- Xen network PV frontends
- 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.
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).
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].
This software is signed by Fedora distribution keys, so it is also critical that the tools used in domains for software updates (`dnf` and `rpm`) are trustworthy.
[Qubes Security Goals]: /security/goals/
[Fedora Project]: https://getfedora.org/
[Understanding and Preventing Data Leaks]: /doc/data-leaks/

3
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`
configuration value from `defaults[pool_config]`, if not overwritten.
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
is that you can store your domains in multiple places.
@ -50,4 +49,4 @@ argument to `qvm-create` to have the VM images stored in pool `foo`. See also
`qvm-create --help`.
While the current API is not as clean and beautiful as the R4 API, it allows
you to write your own storage drivers e.g. for Btrfs today.
you to write your own storage drivers e.g. for Btrfs today.

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

@ -8,59 +8,54 @@ redirect_from:
- /wiki/TemplateImplementation/
---
Overview of VM block devices
============================
# Overview of VM block devices
Every VM has 4 block devices connected:
- **xvda** – base root device (/) – details described below
- **xvdb** – private.img – place where VM always can write.
- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware
- **xvda** – base root device (/) – details described below
- **xvdb** – private.img – place where VM always can write.
- **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware
private.img (xvdb)
------------------
## private.img (xvdb)
This is mounted as /rw and here is placed all VM private data. This includes:
- */home* – which is bind mounted to /rw/home
- */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
- */home* – which is bind mounted to /rw/home
- */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are 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:
- *vmlinuz* – actual kernel
- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules
- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware)
- *vmlinuz* – actual kernel
- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules
- *modules.img* – filesystem image of /lib/modules with matching kernel modules and firmware (/lib/firmware/updates is symlinked to /lib/modules/firmware)
Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
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:
- root.img can be modified while there are AppVMs running – without corrupting the filesystem
- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
- root.img can be modified while there are AppVMs running – without corrupting the filesystem
- multiple AppVMs that are using different versions of root.img (from various points in time) can be running concurrently
There are two layers of the device-mapper snapshot device; the first one enables modifying root.img without stopping the AppVMs and the second one, which is contained in the AppVM, enables temporal modifications to its filesystem. These modifications will be discarded after a restart of the AppVM.
![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png)
Snapshot device in Dom0
-----------------------
## Snapshot device in Dom0
This device consists of:
- root.img – real template filesystem
- root-cow.img – differences between the device as seen by AppVM and the current root.img
- root.img – real template filesystem
- root-cow.img – differences between the device as seen by AppVM and the current root.img
The above is achieved through creating device-mapper snapshots for each version of root.img. When an AppVM is started, a xen hotplug script (/etc/xen/scripts/block-snapshot) reads the inode numbers of root.img and root-cow.img; these numbers are used as the snapshot device's name. When a device with the same name exists the new AppVM will use it – therefore, AppVMs based on the same version of root.img will use the same device. Of course, the device-mapper cannot use the files directly – it must be connected through /dev/loop\*. The same mechanism detects if there is a loop device associated with a file determined by the device and inode numbers – or if creating a new loop device is necessary.
@ -82,31 +77,29 @@ This is done using snapshot-merge device-mapper target (available from 2.6.34 ke
Steps performed by **qvm-revert-template-changes**:
1. Ensure that no other VMs uses this template.
2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
5. Replace *snapshot-merge* d-m target back to *snapshot*.
6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
1. Ensure that no other VMs uses this template.
2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
5. Replace *snapshot-merge* d-m target back to *snapshot*.
6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
Snapshot device in AppVM
------------------------
## Snapshot device in AppVM
Root device is exposed to AppVM in read-only mode. AppVM can write only in:
- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended
- volatile.img – temporary storage, which is discarded after an AppVM restart
- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended
- volatile.img – temporary storage, which is discarded after an AppVM restart
volatile.img is divided into two partitions:
1. changes to root device
2. swap partition
1. changes to root device
2. swap partition
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*.

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

243
introduction/faq.md
View File

@ -20,7 +20,7 @@ redirect_from:
### What is Qubes OS?
Qubes OS is a security-oriented operating system (OS).
The OS is the software that runs all the other programs on a computer.
The OS is the software that runs all the other programs on a computer.
Some examples of popular OSes are Microsoft Windows, Mac OS X, Android, and iOS.
Qubes is free and open-source software (FOSS).
This means that everyone is free to use, copy, and change the software in any way.
@ -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.
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?
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.
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?
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,30 +129,29 @@ 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>
</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 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.)
- 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.
(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">
<i class="fa fa-times"></i> <strong>Cons</strong>
</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.
* 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.)
* 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.
- 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.
(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.
- 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].)
### What is the main concept behind Qubes?
To build security on the "Security by Compartmentalization (or Isolation)" principle.
### What about other approaches to security?
The other two popular [approaches] are “Security by Correctness” and “Security by Obscurity.”
The other two popular [approaches] are “Security by Correctness” and “Security by Obscurity.”
We don't believe either of these approaches are capable of providing reasonable security today, nor do we believe that they will be capable of doing so in the foreseeable future.
### How is Qubes different from other security solutions?
@ -163,8 +160,8 @@ Please see this [article] for a thorough discussion.
### Is Qubes just another Linux distribution?
If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one.
But Qubes is much more than just Xen packaging.
If you really want to call it a distribution, then it's more of a "Xen distribution" than a Linux one.
But Qubes is much more than just Xen packaging.
It has its own VM management infrastructure, with support for template VMs, centralized VM updating, etc.
It also has a very unique GUI virtualization infrastructure.
@ -179,9 +176,9 @@ We believe that this is currently the only practically viable approach to implem
### Does Qubes use full disk encryption (FDE)?
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [LUKS]/[dm-crypt].
Yes, of course!
Full disk encryption is enabled by default.
Specifically, we use [LUKS]/[dm-crypt].
You can even [manually configure your encryption parameters][custom_config] if you like!
### What do all these terms mean?
@ -191,13 +188,13 @@ All Qubes-specific terms are defined in the [glossary]
### Does Qubes run every app in a separate VM?
No! This would not make much sense.
Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,").
Qubes uses lightweight VMs to create security qubes (e.g., "work," "personal," and "banking,").
A typical user would likely need around five qubes.
Very paranoid users, or those who are high-profile targets, might use a dozen or more qubes.
### Why does Qubes use Xen instead of KVM or some other hypervisor?
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).
We discuss this in much greater depth in our [Architecture Specification document].
### How is Qubes affected by Xen Security Advisories (XSAs)?
@ -208,25 +205,25 @@ See the [XSA Tracker].
Whenever starting a discussion about another (micro)kernel or hypervisor in relation to Qubes, we strongly suggest including answers to the following questions first:
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
1. What kinds of containers does it use for isolation? Processes? PV VMs? Fully virtualized VMs (HVMs)? And what underlying h/w technology is used (ring0/3, VT-x)?
2. Does it require specially written/built applications (e.g. patched Firefox)?
3. Does it require custom drivers, or can it use Linux/Windows ones?
4. Does it support VT-d, and does it allow for the creation of untrusted driver domains?
5. Does it support S3 sleep?
6. Does it work on multiple CPUs/Chipsets?
7. What are the performance costs, more or less? (e.g. "XYZ prevents concurrent execution of two domains/processes on shared cores of a single processor", etc.)
8. Other special features? E.g. eliminates cooperative covert channels between VMs?
Here are the answers for Xen 4.1 (which we use as of 2014-04-28):
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
1. PV and HVM Virtual Machines (ring0/3 for PV domains, VT-x/AMD-v for HVMs).
2. Runs unmodified usermode apps (binaries).
3. Runs unmodified Linux drivers (dom0 and driver domains). PV VMs require special written pvdrivers.
4. Full VT-d support including untrusted driver domains.
5. S3 sleep supported well.
6. Works on most modern CPUs/Chipsets.
7. Biggest performance hit on disk operations (especially in Qubes when complex 2-layer mapping used for Linux qubes). No GPU virtualization.
8. Mostly Works<sup>TM</sup> :)
### Which virtualization modes do VMs use?
@ -242,8 +239,8 @@ Stub domains - HVMs | PV |
### What's so special about Qubes' GUI virtualization?
We have designed the GUI virtualization subsystem with two primary goals: security and performance.
Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks.
We have designed the GUI virtualization subsystem with two primary goals: security and performance.
Our GUI infrastructure introduces only about 2,500 lines of C code (LOC) into the privileged domain (Dom0), which is very little, and thus leaves little space for bugs and potential attacks.
At the same time, due to the smart use of Xen shared memory, our GUI implementation is very efficient, so most virtualized applications really feel as if they were executed natively.
### Why passwordless sudo?
@ -253,6 +250,7 @@ Please refer to [this page].
### Why is dom0 so old?
Please see:
- [Installing and updating software in dom0]
- [Note on dom0 and EOL]
@ -283,13 +281,13 @@ We've gone to special effort to set all of this up so that no one has to trust t
### What does it mean to "distrust the infrastructure"?
A core tenet of the Qubes philosophy is "distrust the infrastructure," where "the infrastructure" refers to things like hosting providers, CDNs, DNS services, package repositories, email servers, PGP keyservers, etc.
A core tenet of the Qubes philosophy is "distrust the infrastructure," where "the infrastructure" refers to things like hosting providers, CDNs, DNS services, package repositories, email servers, PGP keyservers, etc.
As a project, we focus on securing endpoints instead of attempting to secure "the middle" (i.e., the infrastructure), since one of our primary goals is to free users from being forced to entrust their security to unknown third parties.
Instead, our aim is for users to be required to trust as few entities as possible (ideally, only themselves and any known persons whom they voluntarily decide to trust).
Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it.
Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so.
We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users.
Users can never fully control all the infrastructure they rely upon, and they can never fully trust all the entities who do control it.
Therefore, we believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so.
We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users.
Since we don't want to encourage or endorse this, we make our distrust of the infrastructure explicit.
Also see: [Should I trust this website?]
@ -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]!
## Users
### Can I watch YouTube videos in qubes?
@ -324,29 +321,28 @@ Absolutely.
### Can I run applications, like games, which require hardware acceleration?
Those won’t fly.
We do not provide GPU virtualization for Qubes.
This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure.
Those won’t fly.
We do not provide GPU virtualization for Qubes.
This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure.
However, Qubes does allow for the use of accelerated graphics (e.g. OpenGL) in dom0’s Window Manager, so all the fancy desktop effects should still work.
AppVMs use a software-only (CPU-based) implementation of OpenGL, which may be good enough for basic games and applications.
For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads:
- [GPU passing to HVM]
- [Clarifications on GPU security]
- [GPU passing to HVM]
- [Clarifications on GPU security]
### Is Qubes a multi-user system?
No.
Qubes does not pretend to be a multi-user system.
Qubes assumes that the user who controls Dom0 controls the whole system.
It is very difficult to **securely** implement multi-user support.
No.
Qubes does not pretend to be a multi-user system.
Qubes assumes that the user who controls Dom0 controls the whole system.
It is very difficult to **securely** implement multi-user support.
See [here] for details.
However, in Qubes 4.x we will be implementing management functionality.
See [Admin API] and [Core Stack] for more details.
### What are the system requirements for Qubes OS?
See the [system requirements].
@ -361,9 +357,9 @@ See [Certified Hardware].
### How much disk space does each qube require?
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner).
This means that each qube needs only as much disk space as is necessary to store its own private data.
This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based.
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner).
This means that each qube needs only as much disk space as is necessary to store its own private data.
This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based.
(These qubes will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
@ -374,7 +370,7 @@ Please see the [system requirements].
Please see the [system requirements] for the latest information.
If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration.
You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation.
You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation.
For more information, see [Qubes-certified hardware](/doc/certified-hardware/).
### Why is VT-x/AMD-V important?
@ -385,24 +381,24 @@ In addition, if your system lacks VT-x/AMD-V, then it also lacks VT-d/ADM-Vi/AMD
(See next question.)
### Why is VT-d/ADM-Vi/AMD IOMMU important?
On a system without VT-d/ADM-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple [DMA attack](#what-is-a-dma-attack) to go from the NetVM to Dom0.
Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d/ADM-Vi/AMD IOMMU.
On a system without VT-d/ADM-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple [DMA attack](#what-is-a-dma-attack) to go from the NetVM to Dom0.
Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d/ADM-Vi/AMD IOMMU.
Therefore, a system running Qubes without VT-d/ADM-Vi/AMD IOMMU would still be significantly more secure than one running Windows, Mac, or Linux.
### What is a DMA attack?
Direct Memory Access (DMA) is mechanism for PCI devices to access system memory (read/write).
Without VT-d/ADM-Vi/AMD IOMMU, any PCI device can access all the memory, regardless of the VM to which it is assigned (or if it is left in dom0).
Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network").
So, without VT-d/ADM-Vi/AMD IOMMU, it gives unlimited access to the whole system.
Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing.
Without VT-d/ADM-Vi/AMD IOMMU, any PCI device can access all the memory, regardless of the VM to which it is assigned (or if it is left in dom0).
Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network").
So, without VT-d/ADM-Vi/AMD IOMMU, it gives unlimited access to the whole system.
Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing.
But since you can read the whole memory, it isn't that hard.
Now, how does this apply to Qubes OS?
The above attack requires access to a PCI device, which means that it can be performed only from the NetVM or USB VM, so someone must first break into one of those VMs.
But this isn't that hard, because there is a lot of complex code handling network traffic.
There is a history of bugs in DHCP clients, DNS clients, etc.
Now, how does this apply to Qubes OS?
The above attack requires access to a PCI device, which means that it can be performed only from the NetVM or USB VM, so someone must first break into one of those VMs.
But this isn't that hard, because there is a lot of complex code handling network traffic.
There is a history of bugs in DHCP clients, DNS clients, etc.
Most attacks on the NetVM and USB VM (but not all of them!) require being somewhat close to the target system, for example, being connected to the same Wi-Fi network, or in the case of a USB VM, having physical access to a USB port.
### Can I use AMD-v instead of VT-x?
@ -433,11 +429,10 @@ You have to restart the NetVM after the TemplateVM has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it poses a security risk for your Qubes OS installation.
You shouldn't do that, because it poses a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting].
It begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running?
See [here][version].
@ -464,31 +459,33 @@ Enable "debug mode" in the qube's settings, either by checking the box labeled "
### I created a usbVM and assigned usb controllers to it. Now the usbVM wont boot.
This is probably because one of the controllers does not support reset.
See the [USB Troubleshooting guide](/doc/usb-troubleshooting/#usbvm-does-not-boot-after-creating-and-assigning-usb-controllers-to-it).
This is probably because one of the controllers does not support reset.
See the [USB Troubleshooting guide](/doc/usb-troubleshooting/#usbvm-does-not-boot-after-creating-and-assigning-usb-controllers-to-it).
### I assigned a PCI device to a qube, then unassigned it/shut down the qube. Why isn't the device available in dom0?
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.
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.
In order to re-enable the device in dom0, either:
* Reboot the physical machine.
- Reboot the physical machine.
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
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
```
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo 0000:<BDF> > /sys/bus/pci/drivers/$MOD/bind
```
See also [here][assign_devices].
### How do I install Flash in a Debian qube?
The Debian way is to install the flashplugin-nonfree package.
The Debian way is to install the flashplugin-nonfree package.
Download this in a qubes, and copy it to a Debian template.
This will make Flash available to every qube using that template.
@ -501,16 +498,18 @@ If you only want Flash available in one qube:
### How do I play video files?
If you're having trouble playing a video file in a qube, you're probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.).
If you're having trouble playing a video file in a qube, you're probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.).
For Debian:
1. (Recommended) Clone an existing Debian TemplateVM
2. Install VLC in that TemplateVM:
$ sudo apt install vlc
```bash_session
$ sudo apt install vlc
```
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].
3. Install VLC in that TemplateVM:
$ sudo dnf install vlc
```bash_session
$ sudo dnf install vlc
```
4. Use VLC to play your video files.
@ -528,23 +529,23 @@ For Fedora:
The recommended approach is to pass only the specific partition you intend to use from [`sys-usb`](/doc/usb/) to another qube via `qvm-block`.
They will show up in the destination qube as `/dev/xvd*` and must be mounted manually.
Another approach is to attach the entire USB drive to your destination qube.
However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table.
Another approach is to attach the entire USB drive to your destination qube.
However, this could theoretically lead to an attack because it forces the destination qube to parse the device's partition table.
If you believe your device is safe, you may proceed to attach it.
In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square).
From the top part of the list, click on the drive you want to attach, then select the qube to attach it to.
In Qubes 4.0, this is accomplished with the Devices Widget located in the tool tray (default top right corner, look for an icon with a yellow square).
From the top part of the list, click on the drive you want to attach, then select the qube to attach it to.
Although you can also attach the entire USB device to a qube by selecting it from the bottom part of the list, in general this approach should not be used because you are exposing the target qube to unnecessary additional attack surface.
Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube.
Although external media such as external hard drives or flash drives plugged in via USB are available in the USB qube, it is not recommended to access them directly from inside the USB qube.
See [Block (Storage) Devices][storage](/doc/block-devices/) for more information.
### My encrypted drive doesn't appear in Debian qube.
This is an issue that affects qubes based on Debian Jessie.
This is an issue that affects qubes based on Debian Jessie.
The problem is fixed in Stretch, and does not affect Fedora-based qubes.
A mixed drive with some encrypted partitions appears correctly in Nautilus.
A mixed drive with some encrypted partitions appears correctly in Nautilus.
The encrypted partitions are identified and the user is prompted for password on attempting to mount the partition.
A fully encrypted drive does not appear in Nautilus.
@ -564,7 +565,7 @@ The decrypted device is now available at `/mnt` - when you have finished using i
### Windows Update is stuck.
This has nothing to do with Qubes.
This has nothing to do with Qubes.
[It's a longstanding Windows bug.](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates)
### Fullscreen Firefox is frozen.
@ -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:
qvm-prefs <HVMname> kernel ""
```
qvm-prefs <HVMname> kernel ""
```
### When I try to install a TemplateVM, it says no match is found.
@ -603,13 +606,14 @@ The full message looks like:
[FAILED] Failed to start Load Kernel Modules.
See 'systemctl status systemd-modules-load.service' for details.
```
This is cosmetic only, and can safely be ignored.
### Why is Qubes so slow and how can I make it faster?
During boot, Qubes starts several virtual machines.
Having so many qubes running at once inevitably strains the resources of your computer and causes slowness.
The most effective way to speed up Qubes is to get more powerful hardware -- a fast CPU, a lot of memory and fast SSDs.
During boot, Qubes starts several virtual machines.
Having so many qubes running at once inevitably strains the resources of your computer and causes slowness.
The most effective way to speed up Qubes is to get more powerful hardware -- a fast CPU, a lot of memory and fast SSDs.
Qubes is slower when reading from the disk because of the VM overhead, which is why we recommend installing it on a fast SSD.
### Could you please make my preference the default?
@ -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.
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
### Are there restrictions on the software that the Qubes developers are willing to use?
@ -631,21 +634,21 @@ 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/)).
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 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 must be built from source, the source code and any builders must be signed.
- 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 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.
(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?
Since 2013 [Xen has not supported 32-bit x86 architecture](https://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only.
In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux.
While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs.
Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface.
So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer.
The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor.
In addition, with features like improved ASLR, it is often more difficult to exploit a bug on x64 Linux than x86 Linux.
While we designed Qubes from the beginning to limit potential attack vectors, we still realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, however simple, might contain some bugs.
Plus since we haven't implemented a separate storage domain, the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface.
So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer.
The 64-bit option provides some (little perhaps, but some) more protection against some classes of attacks, and at the same time does not have any disadvantages except the extra requirement of a 64 bit processor.
And even though Qubes now "needs" a 64 bit processor, it didn't make sense to run Qubes on a system without 3-4GB of memory, and those have 64-bit CPUs anyway.
### What is the recommended build environment for Qubes OS?
@ -662,23 +665,23 @@ See the [Qubes Source Code Repositories](/doc/source-code/) article.
### What is Qubes' attitude toward changing guest distros?
We try to respect each distro's culture, where possible.
We try to respect each distro's culture, where possible.
See the discussion on issue [#1014](https://github.com/QubesOS/qubes-issues/issues/1014) for an example.
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.
* The upstream documentation matches the distribution running in the Qubes VM.
* We're less likely to introduce Qubes-specific issues.
* Each officially supported distribution (ideally) should offer the same set of
- The upstream documentation matches the distribution running in the Qubes VM.
- We're less likely to introduce Qubes-specific issues.
- Each officially supported distribution (ideally) should offer the same set of
Qubes-specific features - a change in one supported distribution should be
followed also in others, including new future distributions.
### Is the I/O emulation component (QEMU) part of the Trusted Computing Base (TCB)?
No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB.
This has been achieved thanks to the careful use of Xen's stub domain feature.
No. Unlike many other virtualization systems, Qubes takes special effort to keep QEMU _outside_ of the TCB.
This has been achieved thanks to the careful use of Xen's stub domain feature.
For more details about how we improved on Xen's native stub domain use, see [here](https://blog.invisiblethings.org/2012/03/03/windows-support-coming-to-qubes.html).
[force_usb2]: https://www.systutorials.com/qa/1908/how-to-force-a-usb-3-0-port-to-work-in-usb-2-0-mode-in-linux
@ -703,7 +706,7 @@ Yes, Qubes natively supports automation via [Salt (SaltStack)][Salt].
There is also the unofficial [ansible-qubes toolkit][ansible].
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
[4.x System Requirements]: /doc/system-requirements/#qubes-release-4x
[4.x System Requirements]: /doc/system-requirements/#qubes-release-4x
[Admin API]: /news/2017/06/27/qubes-admin-api/
[ansible]: https://github.com/Rudd-O/ansible-qubes
[Anti Evil Maid]: /doc/anti-evil-maid/
@ -716,9 +719,9 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
[clipboard]: /doc/copy-paste
[command-line interface]: https://en.wikipedia.org/wiki/Command-line_interface
[commands]: https://en.wikipedia.org/wiki/Command_(computing)
[coreboot]: https://www.coreboot.org/
[coreboot]: https://www.coreboot.org/
[Core Stack]: /news/2017/10/03/core3/
[custom_config]: /doc/custom-install/
[custom_config]: /doc/custom-install/
[Debian is not certified]: https://www.gnu.org/distros/common-distros.en.html
[disposable]: /doc/disposablevm/
[disposable qube]: /doc/dispvm/
@ -726,7 +729,7 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
[dm-crypt]: https://en.wikipedia.org/wiki/Dm-crypt
[doc-signing keys]: https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing
[documentation guidelines]: /doc/doc-guidelines
[documentation on multibooting]: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
[documentation on multibooting]: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
[Enable RPMFusion]: /doc/software-update-domu/#rpmfusion-for-fedora-templatevms
[file]: /doc/copying-files
[firewalls]: /doc/firewall
@ -753,7 +756,7 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
[storage]: /doc/block-devices/
[system requirements]: /doc/system-requirements/
[Tails]: https://tails.boum.org/
[Template]: /doc/template-implementation
[Template]: /doc/template-implementation
[terminal emulator]: https://en.wikipedia.org/wiki/Terminal_emulator
[this message]: https://groups.google.com/group/qubes-devel/msg/6412170cfbcb4cc5
[this page]: /doc/vm-sudo/

3
introduction/intro.html
View File

@ -11,6 +11,7 @@ redirect_from:
---
<h2>What is Qubes OS?</h2>
<a id = "what-is-qubes-os"></a>
<div class="row">
<div class="col-lg-12 col-md-12">
@ -159,6 +160,7 @@ redirect_from:
<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>
@ -336,4 +338,3 @@ redirect_from:
</li>
</ul>
</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]
- [Documentation Guidelines]
[qubes-issues-all]: https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue
[qubes-issues-bug-up-desc]: https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc
[qubes-issues-labels]: https://github.com/QubesOS/qubes-issues/labels
@ -146,4 +145,3 @@ If the issue is closed without one of these specific resolutions, then it means,
[Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

22
introduction/statistics.md
View File

@ -2,7 +2,7 @@
layout: default
title: Statistics
permalink: /statistics/
redirect_from:
redirect_from:
- /counter/
---
@ -12,8 +12,7 @@ redirect_from:
</a>
</div>
FAQ
---
## FAQ
### How often is this graph updated?
@ -39,10 +38,11 @@ tor_users = tor_requests * (plain_users / plain_requests)
```
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.
- `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.
- `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.
- `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.
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:
- The IPv4 addresses that connect to the Qubes update servers
- The number of requests from each IPv4 address
- Standard server access and error logs
- The IPv4 addresses that connect to the Qubes update servers
- The number of requests from each IPv4 address
- Standard server access and error logs
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.
The source code is available [here][source-code].
[tor-methodology]: #how-has-the-methodology-for-counting-tor-users-changed
[TorDNSEL's exit lists]: https://metrics.torproject.org/collector.html#type-tordnsel
[raw-data]: https://tools.qubes-os.org/counter/stats.json
[source-code]: https://github.com/woju/qubes-stats

124
introduction/support.md
View File

@ -13,7 +13,7 @@ redirect_from:
- /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
[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
[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
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
came from the same keyholder.
## Discussion guidelines ##
## Discussion guidelines
Qubes discussions mainly take place on `qubes-users`, `qubes-devel`, and our
[forum], all of which are explained below. Most questions should be directed to
@ -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
guidelines.
### Be polite and respectful ###
### Be polite and respectful
Remember, no one here is under any obligation
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
likely to be ignored.
### Be concise ###
### Be concise
Include only essential information. Most of your readers lead
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
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
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
message. [Ask questions the smart way.][smart-questions]
### Be patient ###
### Be patient
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
@ -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
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
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
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
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
change][contributing to the documentation].
### Moderation ###
### Moderation
The moderation team aims to enforce our [Code of Conduct][coc].
Beyond this, users should not expect any specific action from the moderation team.
Specifically, users should not request that posts or messages be deleted or edited by a moderator.
Users are reminded that, in most venues, anything posted will be sent out as an email to other others, and these emails cannot be deleted from others' inboxes.
### 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
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
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
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
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
in installer.")
#### Do not send duplicates ####
#### Do not send duplicates
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,
and your message should be approved (and your email address added to the
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
special need for privacy (in which case, use PGP encryption). This increases
the likelihood that a greater quantity of useful information will be
available to everyone in the future.
#### Quote appropriately ####
#### Quote appropriately
If you're replying to a thread (whether your own or
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
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
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
will ask for clarification if needed.
#### Suggestions ####
#### Suggestions
While we're generally open to hearing suggestions for new features, please
note that we already have a pretty well defined [roadmap], and it's rather
@ -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
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
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
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
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,
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
[Google Groups web interface][qubes-announce-web].
### qubes-users ###
### qubes-users
This list is for helping users solve various daily problems with Qubes OS.
Examples of topics or questions suitable for this list include:
* [HCL] reports
* Installation problems
* Hardware compatibility problems
* Questions of the form: "How do I...?"
* [HCL] reports
* Installation problems
* Hardware compatibility problems
* Questions of the form: "How do I...?"
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
read and understood the following basic documentation prior to posting to the
list:
* The [Installation Guide], [System Requirements], and [HCL] (for problems
related to installing Qubes OS)
* The [User FAQ]
* The [documentation] (for questions about how to use Qubes OS)
* The [Installation Guide], [System Requirements], and [HCL] (for problems
related to installing Qubes OS)
* The [User FAQ]
* 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
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
[traditional mail archive][qubes-users-archive].
### qubes-devel ###
### qubes-devel
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
implementation. Examples of topics and questions suitable for this list include:
* Questions about why we made certain architecture or implementation decisions.
* 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.
* Discussions about proposed new features, patches, etc.
* For example: "I would like to implement feature XYZ."
* Contributed code and patches.
* Security discussions which are relevant to Qubes in some way.
* Questions about why we made certain architecture or implementation decisions.
* 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.
* Discussions about proposed new features, patches, etc.
* For example: "I would like to implement feature XYZ."
* Contributed code and patches.
* 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
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]
and [traditional mail archive][qubes-devel-archive].
### qubes-project ###
### qubes-project
This list is for non-technical discussion and coordination around the
Qubes OS project.
Examples of topics or question suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
* FOSS governance discussions
* Most Github issues tagged "[business]"
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
@ -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
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,
its documentation, and the website.
Examples of topics or question suitable for this list include:
* Questions about or issues with [Transifex], the translation platform we use
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
* Questions about or issues with [Transifex], the translation platform we use
* Who is managing localization for a given language
* Most Github issues tagged "[localization]"
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
@ -353,8 +345,7 @@ unsubscribe, send a blank email to
`qubes-translation+unsubscribe@googlegroups.com`. This list also has an
optional [Google Groups web interface][qubes-translation-web].
## Forum ##
## Forum
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
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
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
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
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
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
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.
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:
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-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/>
* Matrix, Qubes-related: <https://matrix.to/#/#cybersec-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/>
[mailing lists]: #mailing-lists
[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
[Reddit]: https://www.reddit.com/r/Qubes/
[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/
---
Canary Checklist
================
# Canary Checklist
Preparation
-----------
## Preparation
* Draft canary and push to private repository
* Finalize canary, sign, and add signed tags
Announcement
------------
* Draft canary and push to private repository
* Finalize canary, sign, and add signed tags
* 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
## 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

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/
---
Security Bulletin Checklist
===========================
# Security Bulletin Checklist
Preparation
-----------
## Preparation
* Draft QSB and push to private repository
* Build fixed packages
* Finalize QSB, sign, and add signed tags
Announcement
------------
* Draft QSB and push to private repository
* Build fixed packages
* Finalize QSB, sign, and add signed tags
* 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
## 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

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

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

284
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:
* [Qubes PGP keys](https://keys.qubes-os.org/keys/)
* [Qubes Security Bulletins (QSBs)](/security/bulletins/)
* [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)
* Security-related information and announcements (e.g., key revocations)
* [Qubes PGP keys](https://keys.qubes-os.org/keys/)
* [Qubes Security Bulletins (QSBs)](/security/bulletins/)
* [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)
* Security-related information and announcements (e.g., key revocations)
While `qubes-secpack` itself is independent of any particular host, its current
official location is:
<https://github.com/QubesOS/qubes-secpack>
History and Rationale
---------------------
@ -40,92 +39,94 @@ rationale in an
[email](https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ)
to the Qubes mailing lists:
```
Hello,
A new Qubes Security Bulletin has been just released and is available here:
https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-013-2015.txt
As per the previous discussions about recent problems with verifying
digital signatures on messages sent to Google Groups (thanks to
automatic footer addition by Google), we have decided to change the way
we publish Qubes Security Bulletins, as well as other security-related
info pertinent to the Qubes Project.
Starting today, we will be maintain a Git repository -- "Qubes Security
Pack" -- which will contain all the QSBs released so far, all the keys,
warrant canaries [1], and potentially some additional info or
announcements (e.g. key revocations). The whole repo can be found here:
https://github.com/QubesOS/qubes-secpack
Note that all the keys distributed there should be signed by Qubes
Master Key. The Master Key is also attached in the repo, but should
really be obtained/verified using a different channel.
Additionally, most of the files are signed by core Qubes
developers (currently by Marek and myself) via detached signatures as
well as git tag signatures.
The are several advantages of using Git to distribute all these information:
1) Git repo is a collection of files, some of which can be detached GPG
signatures for other files and we can ensure all these files are
distributed together.
2) Git makes it easy for people to clone and redistribute these
collection of files, as well as to easily host them and view on the Web.
3) Git provides for signed tags mechanisms which is another mean we
utilize to ensure integrity of the distributed files.
A few words about the Warrant Canary which we've just introduced today,
and which can be seen here:
https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt
Even though we're not providing any kind of services (such as e.g. email
hosting), that could be searched or tapped by authorities, there are
other possibilities that worry us [2], in the light of various recent
law "developments", such as those that might be coercing people to hand
over their private keys to authorities.
Until we fully decentralize the root of trust for Qubes, something that
requires the move to deterministic builds [3], and so won't happen
very soon, the possibility of having to disclose any of the Qubes
signing keys to anybody might have pretty serious consequences for those
who decided to entrust Qubes with anything serious. And we would like to
somehow minimize these consequences with this canary thing.
Additionally the canary is a nice way of ensuring "freshness" of our
messaging to the community.
Of course the canary doesn't solve all the problems. E.g. if my signing
keys were somehow stolen without our knowledge, it wouldn't help.
Neither it could help in case me being or becoming a miscreant. And
probably it doesn't address many other potential problems, which could
only be solved one day with a multi-signature scheme. But anyway, until
that time, this is the best we can do, I think.
And congrats to Jann for the very interesting clipboard attack (even
though mostly theoretical, still very cool)!
Thanks,
joanna.
--
The Qubes Security Team
https://www.qubes-os.org/doc/SecurityPage
[1] http://en.wikipedia.org/wiki/Warrant_canary
[2] Especially myself, because I'm currently the Root Of Trust for all
Qubes binaries :/
[3] Deterministic builds are required because it's the only way we can
implement multiple signature scheme for distributed binaries.
```
How to Obtain, Verify, and Read
-------------------------------
@ -133,129 +134,138 @@ How to Obtain, Verify, and Read
The following example demonstrates one method of obtaining the `qubes-secpack`,
verifying its contents, and reading them.
1. Clone the `qubes-secpack` repo.
1. Clone the `qubes-secpack` repo.
$ git clone https://github.com/QubesOS/qubes-secpack.git
Cloning into 'qubes-secpack'...
remote: Counting objects: 195, done.
remote: Total 195 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
Resolving deltas: 100% (47/47), done.
Checking connectivity... done.
```shell_session
$ git clone https://github.com/QubesOS/qubes-secpack.git
Cloning into 'qubes-secpack'...
remote: Counting objects: 195, done.
remote: Total 195 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (195/195), 130.94 KiB | 207.00 KiB/s, done.
Resolving deltas: 100% (47/47), done.
Checking connectivity... done.
```
2. Import the included PGP keys.
2. Import the included PGP keys.
$ gpg --import qubes-secpack/keys/*/*
gpg: directory `/home/user/.gnupg' created
gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
gpg: keyring `/home/user/.gnupg/secring.gpg' created
gpg: keyring `/home/user/.gnupg/pubring.gpg' created
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported
gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported
gpg: key 36879494: public key "Qubes Master Signing Key" imported
gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported
gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported
gpg: Total number processed: 17
gpg: imported: 17 (RSA: 17)
gpg: no ultimately trusted keys found
```shell_session
$ gpg --import qubes-secpack/keys/*/*
gpg: directory `/home/user/.gnupg' created
gpg: new configuration file `/home/user/.gnupg/gpg.conf' created
gpg: WARNING: options in `/home/user/.gnupg/gpg.conf' are not yet active during this run
gpg: keyring `/home/user/.gnupg/secring.gpg' created
gpg: keyring `/home/user/.gnupg/pubring.gpg' created
gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
gpg: key C37BB66B: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 1E30A75D: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 74EADABC: public key "Joanna Rutkowska (Qubes OS signing key) <joanna@invisiblethingslab.com>" imported
gpg: key 65EF29CA: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 34898310: public key "Joanna Rutkowska (Qubes OS Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key B298547C: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@mimuw.edu.pl>" imported
gpg: key AB5EEF90: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key A603BCB6: public key "Marek Marczykowski (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 42CFA724: public key "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" imported
gpg: key 15CE40BF: public key "Wojciech Zygmunt Porczyk (Qubes OS signing key) <woju@invisiblethingslab.com>" imported
gpg: key 36879494: public key "Qubes Master Signing Key" imported
gpg: key 211093A7: public key "Qubes OS Release 1 Signing Key" imported
gpg: key 0A40E458: public key "Qubes OS Release 2 Signing Key" imported
gpg: key 03FA5082: public key "Qubes OS Release 3 Signing Key" imported
gpg: key 92C7B3DC: public key "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" imported
gpg: key 1830E06A: public key "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>" imported
gpg: key 3F48CB21: public key "Qubes OS Security Team <security@qubes-os.org>" imported
gpg: Total number processed: 17
gpg: imported: 17 (RSA: 17)
gpg: no ultimately trusted keys found
```
3. Verify and trust the Qubes Master Signing Key.
3. Verify and trust the Qubes Master Signing Key.
$ gpg --edit-key 36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
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
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
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
trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct
unless you restart the program.
gpg> q
```shell_session
$ gpg --edit-key 36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
**Important!**
In order to verify the authenticity of the Qubes Master Signing Key prior to
trusting it, you should obtain the Qubes Master Signing Key fingerprint from
a trustworthy source (ideally, multiple sources) *other than* this website
and visually compare it (them) to the fingerprint displayed in the preceding
step, ensuring they match. You can read more about digital signatures and
key verification [here](/security/verifying-signatures/).
4. Verify signed Git tags.
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
$ cd qubes-secpack/
$ git tag -v `git describe`
object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
type commit
tag joanna_sec_2bb7f0b9
tagger Joanna Rutkowska <joanna@invisiblethingslab.com> 1468335706 +0000
Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
gpg: Signature made 2016-07-12T08:01:46 PDT
gpg: using RSA key 0x4E6829BC92C7B3DC
gpg: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>" [full]
gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
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
trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct
unless you restart the program.
gpg> q
```
**Important!**
In order to verify the authenticity of the Qubes Master Signing Key prior to
trusting it, you should obtain the Qubes Master Signing Key fingerprint from
a trustworthy source (ideally, multiple sources) *other than* this website
and visually compare it (them) to the fingerprint displayed in the preceding
step, ensuring they match. You can read more about digital signatures and
key verification [here](/security/verifying-signatures/).
4. Verify signed Git tags.
```shell_session
$ cd qubes-secpack/
$ git tag -v `git describe`
object 2bb7f0b966593d8ed74e140a04d60c68b96b164e
type commit
tag joanna_sec_2bb7f0b9
tagger Joanna Rutkowska <joanna@invisiblethingslab.com> 1468335706 +0000
Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e
gpg: Signature made 2016-07-12T08:01:46 PDT
gpg: using RSA key 0x4E6829BC92C7B3DC
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.)
5. Verify detached PGP signatures.
5. Verify detached PGP signatures.
$ cd canaries/
$ 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: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
$ 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: Good signature from "Marek Marczykowski-Górecki (Qubes security pack) <marmarek@invisiblethingslab.com>"
```shell_session
$ cd canaries/
$ 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: Good signature from "Joanna Rutkowska (Qubes Security Pack Signing Key) <joanna@invisiblethingslab.com>"
$ 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: 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
good.)
(The fourth and final lines of output confirm that the two signatures are
good.)
The same procedures can be applied to any directory or file in the
`qubes-secpack`. Two methods of verification (signed Git tags and detached PGP
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
to verify the files.

37
project-security/security.md
View File

@ -2,7 +2,7 @@
layout: doc
title: Security
permalink: /security/
redirect_from:
redirect_from:
- /en/security/
- /en/doc/security/
- /en/doc/qubes-security/
@ -14,8 +14,7 @@ redirect_from:
- /trac/wiki/SecurityPage/
---
Qubes OS Project Security Center
================================
# Qubes OS Project Security Center
- [Security FAQ]
- [Security Goals]
@ -26,50 +25,46 @@ Qubes OS Project Security Center
- [Why and How to Verify Signatures]
- [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!
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].
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.
In particular, the QST is responsible for:
- Responding to [reported security issues]
- Evaluating whether [XSAs][Xen Security Advisory (XSA) Tracker] affect the security of Qubes OS
- Writing, applying, and/or distributing security patches to fix vulnerabilities in Qubes OS
- Writing, signing, and publishing [Security Bulletins]
- Writing, signing, and publishing [Canaries]
- Generating, safeguarding, and using the project's [PGP Keys]
- Responding to [reported security issues]
- 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, signing, and publishing [Security Bulletins]
- Writing, signing, and publishing [Canaries]
- 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.
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.
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.
### Members of the Security Team ###
### Members of the Security Team
- [Marek Marczykowski-Górecki]
- [Simon Gaiser (aka HW42)]
- [Joanna Rutkowska] ([emeritus, canaries only])
[Security FAQ]: /faq/#general--security
[Security Goals]: /security/goals/
[Security Pack]: /security/pack/

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

@ -9,11 +9,9 @@ redirect_from:
- /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.
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.
(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.
There are three basic steps in this process:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. [Verify your Qubes ISO][signature file]
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. [Verify your Qubes ISO][signature file]
If you run into any problems, please consult the [Troubleshooting FAQ] below.
### Preparation
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.
If that still doesn't work, please consult the documentation for your specific program (see links above).
### 1. Get the Qubes Master Signing Key and verify its authenticity
Every file published by the Qubes Project (ISO, RPM, TGZ files and Git repositories) is digitally signed by one of the developer keys or Release Signing Keys.
@ -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.
- 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]):
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc
```shell_session
$ 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.:
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
```shell_session
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
```
The Qubes Master Signing Key is also available in the [Qubes Security Pack] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
@ -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:
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
```
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
```
But how do you know that this is the real fingerprint?
After all, [this website could be compromised][website-trust], so the fingerprint you see here may not be genuine.
@ -130,61 +136,62 @@ That's why we strongly suggest obtaining the fingerprint from *multiple, indepen
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 against PDFs, photographs, and videos in which the fingerprint appears
- Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- Check against PDFs, photographs, and videos in which the fingerprint appears
(e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- Repeat the above from different computers and devices.
- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place.
Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match.
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.
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
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
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
trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct
unless you restart the program.
gpg> q
```
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
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
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
gpg> fpr
pub 4096R/36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
gpg> trust
pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC
trust: unknown validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
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
trust: ultimate validity: unknown
[ unknown] (1). Qubes Master Signing Key
Please note that the shown key validity is not necessarily correct
unless you restart the program.
gpg> q
```
Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
@ -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.
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]
427F11FD0FAA4B080123F01CDDFA1A3E36879494
uid [ultimate] Qubes Master Signing Key
```
$ gpg2 -k "Qubes Master Signing Key"
pub rsa4096 2010-04-01 [SC]
427F11FD0FAA4B080123F01CDDFA1A3E36879494
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.
### 2. Get the Release Signing Key
The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
There are several ways to get the Release Signing Key for your Qubes release.
- 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.
In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
These can be [copied][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-*`.
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:
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
```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
```
- Download it as a file.
You can find the Release Signing Key for your Qubes version on the [Downloads] page.
You can also download all the currently used developers' signing keys, Release Signing Keys, and the Qubes Master Signing Key from the [Qubes Security Pack] and the [Qubes OS Keyserver].
Once you've downloaded your Release Signing Key, import it with GPG:
- Download it as a file.
You can find the Release Signing Key for your Qubes version on the [Downloads] 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].
Once you've downloaded your Release Signing Key, import it with GPG:
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc
```shell_session
$ 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:
$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] 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
```shell_session
$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] 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
gpg: 2 good signatures
gpg: 2 good signatures
```
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix.
@ -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.
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]
5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] Qubes OS Release X Signing Key
```
$ gpg2 -k "Qubes OS Release"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
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.
### 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.
@ -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.
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
gpg: armor header: Version: GnuPG v1
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
```shell_session
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: armor header: Version: GnuPG v1
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
```
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that says `Good signature from "Qubes OS Release X Signing Key"`.
This confirms that the signature on the ISO is good.
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`.
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.
Inside, you should find text that looks similar to this:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
3N/6YZw1gSuvBlTquP27
=e9oD
-----END PGP SIGNATURE-----
```
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
3c951138b8b9867d8657f173c1b58b82 *Qubes-RX-x86_64.iso
1fc9508160d7c4cba6cacc3025165b0f996c843f *Qubes-RX-x86_64.iso
6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a *Qubes-RX-x86_64.iso
de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe *Qubes-RX-x86_64.iso
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
iQIcBAEBCAAGBQJX4XO/AAoJEMsRyh0D+lCCL9sP/jlZ26zhvlDEX/eaA/ANa/6b
Dpsh/sqZEpz1SWoUxdm0gS+anc8nSDoCQSMBxnafuBbmwTChdHI/P7NvNirCULma
9nw+EYCsCiNZ9+WCeroR8XDFSiDjvfkve0R8nwfma1XDqu1bN2ed4n/zNoGgQ8w0
t5LEVDKCVJ+65pI7RzOSMbWaw+uWfGehbgumD7a6rfEOqOTONoZOjJJTnM0+NFJF
Qz5yBg+0FQYc7FmfX+tY801AwSyevj3LKGqZN1GVcU9hhoHH7f2BcbdNk9I5WHHq
doKMnZtcdyadQGwMNB68Wu9+0CWsXvk6E00QfW69M4d6w0gbyoJyUL1uzxgixb5O
qodxrqeitXQSZZvU4kom5zlSjqZs4dGK+Ueplpkr8voT8TSWer0Nbh/VMfrNSt1z
0/j+e/KMjor7XxehR+XhNWa2YLjA5l5H9rP+Ct/LAfVFp4uhsAnYf0rUskhCStxf
Zmtqz4FOw/iSz0Os+IVcnRcyTYWh3e9XaW56b9J/ou0wlwmJ7oJuEikOHBDjrUph
2a8AM+QzNmnc0tDBWTtT2frXcotqL+Evp/kQr5G5pJM/mTR5EQm7+LKSl7yCPoCj
g8JqGYYptgkxjQdX3YAy9VDsCJ/6EkFc2lkQHbgZxjXqyrEMbgeSXtMltZ7cCqw1
3N/6YZw1gSuvBlTquP27
=e9oD
-----END PGP SIGNATURE-----
```
Four digests have been computed for this ISO.
The hash functions used, in order from top to bottom, are MD5, SHA1, SHA256, and SHA512.
One way to verify that the ISO you downloaded matches any of these hash values is by using the respective `*sum` programs:
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
md5sum: WARNING: 23 lines are improperly formatted
$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha1sum: WARNING: 23 lines are improperly formatted
$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha256sum: WARNING: 23 lines are improperly formatted
$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted
```shell_session
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
md5sum: WARNING: 23 lines are improperly formatted
$ sha1sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha1sum: WARNING: 23 lines are improperly formatted
$ sha256sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha256sum: WARNING: 23 lines are improperly formatted
$ sha512sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
sha512sum: WARNING: 23 lines are improperly formatted
```
The `OK` response tells us that the hash value for that particular hash function matches.
The program also warns us that there are 23 improperly formatted lines, but this is to be expected.
@ -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.:
$ openssl dgst -md5 Qubes-RX-x86_64.iso
MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
$ openssl dgst -sha1 Qubes-RX-x86_64.iso
SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
$ openssl dgst -sha256 Qubes-RX-x86_64.iso
SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
$ openssl dgst -sha512 Qubes-RX-x86_64.iso
SHA512(Qubes-RX-x86_64.iso)= de1eb2e76bdb48559906f6fe344027ece20658d4a7f04ba00d4e40c63723171c62bdcc869375e7a4a4499d7bff484d7a621c3acfe9c2b221baee497d13cd02fe
```shell_session
$ openssl dgst -md5 Qubes-RX-x86_64.iso
MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
$ openssl dgst -sha1 Qubes-RX-x86_64.iso
SHA1(Qubes-RX-x86_64.iso)= 1fc9508160d7c4cba6cacc3025165b0f996c843f
$ openssl dgst -sha256 Qubes-RX-x86_64.iso
SHA256(Qubes-RX-x86_64.iso)= 6b998045a513dcdd45c1c6e61ace4f1b4e7eff799f381dccb9eb0170c80f678a
$ 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.)
@ -351,25 +374,25 @@ However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a m
Therefore, we should also verify the authenticity of the listed hash values.
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. Verify the signature in the digest file:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
2. [Get the Release Signing Key][RSK]
3. Verify the signature in the digest file:
```shell_session
$ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v2
gpg: original file name=''
gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: textmode signature, digest algorithm SHA256
```
$ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v2
gpg: original file name=''
gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: textmode signature, digest algorithm SHA256
The signature is good.
If our copy of the `Qubes OS Release X Signing Key` is being validated by the authentic Qubes Master Signing Key (see [above][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.
(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:
$ git tag -v <tag name>
```shell_session
$ git tag -v <tag name>
```
or
$ git verify-tag <tag name>
```shell_session
$ git verify-tag <tag name>
```
To verify a signature on a Git commit:
$ git log --show-signature <commit ID>
```shell_session
$ git log --show-signature <commit ID>
```
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.
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,112 +430,92 @@ Since there's no way for you to be certain that all such conditions hold, you're
Also see: [Distrusting the Infrastructure]
Troubleshooting FAQ
-------------------
## Troubleshooting FAQ
### Why am I getting "Can't check signature: public key not found"?
You don't have the correct [Release Signing Key][RSK].
### Why am I getting "BAD signature from 'Qubes OS Release X Signing Key'"?
The problem could be one or more of the following:
- You're trying to verify the wrong file(s).
Read this page again carefully.
- You're using the wrong GPG command.
Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- 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.
If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
- You're trying to verify the wrong file(s).
Read this page again carefully.
- You're using the wrong GPG command.
Follow the examples in [Verify your Qubes ISO][signature file] carefully.
- 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.
If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
### Why am I getting "bash: gpg2: command not found"?
You don't have `gpg2` installed.
Please install it using the method appropriate for your environment (e.g., via your package manager).
### Why am I getting "No such file or directory"?
Your working directory does not contain the required files.
Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory.
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?
The correct ISO is not in your working directory.
### Why am I getting "can't open `Qubes-RX-x86_64.iso.asc' / verify signatures failed: file open error"?
The correct [signature file] is not in your working directory.
### Why am I getting "no valid OpenPGP data found"?
Either you don't have the correct [signature file], or you inverted the arguments to `gpg2`.
([The signature file goes first.][signature file])
### 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].
### Why am I getting "X signature not checked due to a missing key"?
You don't have the keys that created those signatures in your keyring.
For present purposes, you don't need them as long as you have the [Qubes Master Signing Key][QMSK] and the [Release Signing Key][RSK] for your Qubes version.
### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key?
This is just a basic part of how OpenPGP works.
Anyone can sign anyone else's public key and upload the signed public key to keyservers.
Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate).
This has no impact on verifying Qubes ISOs, code, or keys.
### Why am I getting "verify signatures failed: unexpected data"?
You're not verifying against the correct [signature file].
### Why am I getting "not a detached signature"?
You're not verifying against the correct [signature file].
### 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.
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]?
No, either method is sufficient by itself.
### Why am I getting "no properly formatted X checksum lines found"?
You're not checking the correct [digest file].
### Why am I getting "WARNING: X lines are improperly formatted"?
Read [How to Verify Qubes ISO Digests][digest file] again.
### Why am I getting "WARNING: 1 listed file could not be read"?
The correct ISO is not in your working directory.
### I have another problem that isn't mentioned here.
Carefully read this page again to be certain that you didn't skip any steps.
@ -513,7 +524,6 @@ If your question is about GPG, please see the [GPG documentation].
Still have question?
Please see [Help, Support, Mailing Lists, and Forum] for places where you can ask!
[website-trust]: /faq/#should-i-trust-this-website
[Distrusting the Infrastructure]: /faq/#what-does-it-mean-to-distrust-the-infrastructure
[verifying repos]: #how-to-verify-qubes-repos
@ -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/
[Help, Support, Mailing Lists, and Forum]: /support/
[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.
* **No** means that the *security* of Qubes OS is *not* affected.
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.
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.

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

@ -19,15 +19,19 @@ redirect_from:
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.
## Development
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_.
@ -66,6 +70,7 @@ In particular the following events are not meant to cause a focus change:
* mouse move without click (sloppy focus)
For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
* windows shouldn't be able to change their size themselves
* windows shouldn't be able to modify their borders in any way
@ -184,4 +189,3 @@ client.disconnect_signal("request::tag", ewmh.tag)
```
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.
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 ##
@ -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.
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 ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.

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

@ -16,16 +16,16 @@ Qubes-specific VM config files
------------------------------
These files are placed in `/rw`, which survives a VM restart.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
The scripts here all run as root.
- `/rw/config/rc.local` - script runs at VM startup.
- `/rw/config/rc.local` - script runs at VM startup.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
Example usage:
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
rm -rf /var/lib/bluetooth
rm -rf /var/lib/bluetooth
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~
@ -34,10 +34,10 @@ The scripts here all run as root.
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
Good place to write custom firewall rules.
- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
Good place to write custom firewall rules.
~~~
/etc/qubes/qubes-firewall.d
@ -45,11 +45,12 @@ The scripts here all run as root.
/rw/config/qubes-firewall-user-script
~~~
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
The file is used only in a VM with PCI devices attached.
Intended for use with problematic device drivers.
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
The file is used only in a VM with PCI devices attached.
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`:
~~~
#!/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.
GUI and audio configuration in dom0
-----------------------------------
@ -115,31 +115,31 @@ VM: {
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
**Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
Note that this will cause much higher CPU usage in dom0. It's enabled by
default, disabling it may save CPU in dom0.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
Note that this will cause much higher CPU usage in dom0. It's enabled by
default, disabling it may save CPU in dom0.
- `trayicon_mode` - defines the trayicon coloring mode. Options are
- `bg` - color full icon background to the VM color
- `border1` - add 1px border at the icon edges
- `border2` - add 1px border 1px from the icon edges
- `tint` - tinttint icon to the VM color, can be used with additional
modifiers (you can enable multiple of them)
modifiers (you can enable multiple of them)
- `tint+border1,tint+border2` - same as tint, but also add a border
- `tint+saturation50` - same as tint, but reduce icon saturation by 50%
- `tint+whitehack` - same as tint, but change white pixels (0xffffff) to
almost-white (0xfefefe)
almost-white (0xfefefe)
- `log level` - defines the log options logs can take. It can
have a value of 0 (only errors), 1 (some basic messages), and 2 (debug).

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

@ -12,18 +12,21 @@ redirect_from:
# DisposableVM Customization
## Introduction
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.
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:
[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.
@ -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.
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
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:
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
[user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
```shell_session
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
[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:
[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.
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
_**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)._
@ -61,17 +66,18 @@ _**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM,
It is possible to change the settings for each new DisposableVM.
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).
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
```shell_session
[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:
- Changing Firefox's default startup settings and homepage.
- Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
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 default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
## Using static DisposableVMs for sys-*
@ -130,7 +136,6 @@ qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
~~~
## Adding programs to DisposableVM Application Menu
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.
## 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.
Functionality is not limited, users can:
* Set custom firewall rule sets and run Qubes VPN scripts.
* Set DisposableVMs to autostart at system boot.
* Attach PCI devices with the `--persistent` option.
- Set custom firewall rule sets and run Qubes VPN scripts.
- Set DisposableVMs to autostart at system boot.
- 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.
>_**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
1. Create the DisposableVM Template:
[user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
```shell_session
[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.
@ -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:
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
```shell_session
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
```
### Create the sys-net DisposableVM
1. Create `sys-net` DisposableVM based on the DisposableVM Template:
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
```shell_session
[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/):
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
```
3. Set `disp-sys-net` to provide network for other VMs:
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
```
4. Set `disp-sys-net` NetVM to none:
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
```
5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
[user@dom0 ~]$ qvm-pci
```shell_session
[user@dom0 ~]$ qvm-pci
```
6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/):
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
```
7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
```
8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
```
9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
```shell_session
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
```
10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
@ -214,110 +238,147 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
1. Create `sys-firewall` DisposableVM:
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
```shell_session
[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:
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
```
3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```
4. Set `disp-sys-firewall` as NetVM for other AppVMs:
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
```shell_session
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
```
5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
```
6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
```
7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```shell_session
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```
### Create the sys-usb DisposableVM
1. Create the `disp-sys-usb`:
[user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
```shell_session
[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:
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
```
3. Set `disp-sys-usb` NetVM to none:
[user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
```
4. List all available PCI devices:
[user@dom0 ~]$ qvm-pci
```shell_session
[user@dom0 ~]$ qvm-pci
```
5. Attach the USB controller to the `disp-sys-usb`:
>_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/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:
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
```
7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
```
8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0).
9. At this point, your mouse may not work.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
/etc/qubes-rpc/policy/qubes.InputMouse
```
/etc/qubes-rpc/policy/qubes.InputMouse
```
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
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:
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
Detach PCI device from VM:
```shell_session
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
```
### Troubleshooting
If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
## Deleting DisposableVMs
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:
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-disposablevm-template
```shell_session
[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:
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
```shell_session
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
```
You can then delete the DisposableVM Template:
[user@dom0 ~]$ qvm-remove custom-disposablevm-template
This will completely remove the selected VM(s)
custom-disposablevm-template
```shell_session
[user@dom0 ~]$ qvm-remove custom-disposablevm-template
This will completely remove the selected VM(s)
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:
[user@dom0 ~]$ journalctl | tail
```shell_session
[user@dom0 ~]$ journalctl | tail
```

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

@ -51,5 +51,4 @@ EndSection
## 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.

36
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
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
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:
$ 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
`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
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
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:
$ make get-sources
$ make verify-sources
$ make rpms
```shell_session
$ make get-sources
$ make verify-sources
$ make rpms
```
### Installing
@ -79,17 +87,23 @@ next step.
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
dependencies that we can easily install with:
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
dzen2 dmenu xorg-x11-fonts-misc libev
```shell_session
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
dzen2 dmenu xorg-x11-fonts-misc libev
```
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.

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.
If you want to contribute a package, please see [package contributions]._
Qubes OS contributed packages are available under the [QubesOS-contrib] GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations][package contributions].
@ -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`:
sudo qubes-dom0-update qubes-repo-contrib
```bash_session
sudo qubes-dom0-update qubes-repo-contrib
```
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`:
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.
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
@ -42,10 +49,11 @@ After you've installed the repositories, you can install contributed packages.
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.
[package contributions]: /doc/package-contributions/
[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
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
* 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]
ServerArguments=-nolisten tcp -background none
~~~
~~~
* disable the lightdm service:
* disable the lightdm service:
~~~
~~~
$ sudo systemctl disable lightdm
~~~
~~~
* enable the sddm service:
* enable the sddm service:
~~~
~~~
$ sudo systemctl enable sddm
~~~
~~~
* reboot
* reboot
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.
The safest way to remove (most of) KDE is:
~~~
sudo dnf remove kdelibs plasma-workspace
~~~
Mailing List Threads
--------------------
* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)
* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)

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

@ -6,8 +6,7 @@ redirect_from:
- /en/doc/managing-vm-kernel/
---
VM kernel managed by dom0
=========================
# VM kernel managed by dom0
By default, VMs kernels are provided by dom0.
(See [here][dom0-kernel-upgrade] for information about upgrading kernels in dom0.)
@ -58,8 +57,7 @@ nopat
[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.
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.
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.
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.
~~~
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:
- `vmlinuz` - kernel binary (may not be a Linux kernel)
- `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)
- `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
* `vmlinuz` - kernel binary (may not be a Linux kernel)
* `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)
* `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.
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:
@ -246,7 +241,7 @@ If you'd like to use a different kernel than default, continue reading.
Install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
@ -256,8 +251,8 @@ Replace the version numbers in the example below with the ones appropriate to th
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
@ -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`.
### Installing kernel in Debian VM
#### Distribution kernel
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".)
You can safely ignore this error message:
`grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map`
@ -311,52 +306,59 @@ Depends on `Virtualization` mode setting:
The `Kernel` setting of the `Virtualization` mode setting:
* If `Virtualization` is set to `PVH` -> `Kernel` -> choose `pvgrub2-pvh` -> OK
* If `Virtualization` is set to `PV` -> `Kernel` -> choose `pvgrub2` -> OK
* If `Virtualization` is set to `HVM` -> `Kernel` -> choose `none` -> OK
* If `Virtualization` is set to `PVH` -> `Kernel` -> choose `pvgrub2-pvh` -> OK
* If `Virtualization` is set to `PV` -> `Kernel` -> choose `pvgrub2` -> OK
* If `Virtualization` is set to `HVM` -> `Kernel` -> choose `none` -> OK
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
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`.
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.
sudo dkms autoinstall -k 4.19.0-6-amd64
```bash_session
sudo dkms autoinstall -k 4.19.0-6-amd64
```
Update initramfs.
sudo update-initramfs -u
```bash_session
sudo update-initramfs -u
```
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:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
```
#### 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

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

@ -24,33 +24,34 @@ Decrypting the Disk
-----------------
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.
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
├─sda1 8:1 0 200M 0 part /boot/efi
├─sda2 8:2 0 1G 0 part /boot
└─sda3 8:3 0 110.6G 0 part
└─luks-fed62fc2-2674-266d-2667-2667259cbdec 253:0 0 110.6G 0 crypt
├─qubes_dom0-pool00_tmeta 253:1 0 88M 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-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-pool00_tdata 253:2 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-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-swap 253:5 0 4G 0 lvm [SWAP]
sdb 8:16 0 447.1G 0 disk
├─sdb1 8:17 0 549M 0 part
└─sdb2 8:18 0 446.6G 0 part
sr0 11:0 1 1024M 0 rom
nvme0n1 259:0 0 465.8G 0 disk
├─nvme0n1p1 259:1 0 1G 0 part
└─nvme0n1p2 259:2 0 464.8G 0 part
```
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`.
```
sda 8:0 0 111.8G 0 disk
├─sda1 8:1 0 200M 0 part /boot/efi
├─sda2 8:2 0 1G 0 part /boot
└─sda3 8:3 0 110.6G 0 part
└─luks-fed62fc2-2674-266d-2667-2667259cbdec 253:0 0 110.6G 0 crypt
├─qubes_dom0-pool00_tmeta 253:1 0 88M 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-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-pool00_tdata 253:2 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-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-swap 253:5 0 4G 0 lvm [SWAP]
sdb 8:16 0 447.1G 0 disk
├─sdb1 8:17 0 549M 0 part
└─sdb2 8:18 0 446.6G 0 part
sr0 11:0 1 1024M 0 rom
nvme0n1 259:0 0 465.8G 0 disk
├─nvme0n1p1 259:1 0 1G 0 part
└─nvme0n1p2 259:2 0 464.8G 0 part
```
2. Decrypt the disk using the command `cryptsetup luksOpen /dev/<disk>`.
@ -58,13 +59,13 @@ Accessing LVM Logical Volumes
-----------------------------
3. If using an AppVM or standard Linux, LVM should automatically discover the Qubes LVM configuration. In this case, continue to step 4.
1. Qubes uses the default name `qubes_dom0` for it's LVM VG.
This will conflict with the name of the VG of the currently installed system.
To read both, you will have to rename the VG.
*Note:* If this is not reversed, the Qubes install being accessed will not be bootable.
2. Find the UUID of the vg to be accessed using the command `vgdisplay`.
This will be the VG named `qubes_dom0` which is not marked active.
3. The command `vgrename <UUID> other_install` will rename the VG.
1. Qubes uses the default name `qubes_dom0` for it's LVM VG.
This will conflict with the name of the VG of the currently installed system.
To read both, you will have to rename the VG.
*Note:* If this is not reversed, the Qubes install being accessed will not be bootable.
2. Find the UUID of the vg to be accessed using the command `vgdisplay`.
This will be the VG named `qubes_dom0` which is not marked active.
3. The command `vgrename <UUID> other_install` will rename the VG.
4. Run the command `vgscan` to add any new VGs to the device list.
Mounting the disk
@ -72,12 +73,12 @@ Mounting the disk
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/<vm>-private | VM | The /rw partition of the named VM. |
| other\_install/<vm>-root | templateVM root | The root partition of the named TemplateVM. |
| other\_install/pool00\_tmeta | LVM Metadata | The metadata LV of this disk. |
| 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>-root | templateVM root | The root partition of the named TemplateVM. |
| other\_install/pool00\_tmeta | LVM Metadata | The metadata LV of this disk. |
6. Mount the disk using the command `mount /dev/other_install/<lv name> <mountpoint>`.
*Note:* Any compromised data which exists in the volume to be mounted will be accessible here.
@ -87,11 +88,10 @@ At this point, all files are available in the chosen mountpoint.
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.
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.
1. Unmount any disks that were accessed.
2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`.

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

@ -11,21 +11,19 @@ redirect_from:
- /wiki/ResizeRootDiskImage/
---
Resizing Disk Images
-----------------
## Resizing 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.
So a 2GB private volume with 100M of files will only use 100M.
So a 2GB private volume with 100M of files will only use 100M.
This explains how you can have *many* qubes with large private volumes on quite a small disk.
This is called over provisioning.
This is called over provisioning.
You should keep an eye on the disk-space widget to see how much free space you actually have.
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.
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.
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.
@ -33,7 +31,7 @@ In most cases, the GUI tool Qube Settings (available for every qube from the Sta
![vm-settings-disk-image.png](/attachment/wiki/DiskSize/r4.0-vm-settings-disk-image.png)
In case of standalone qubes and templates, just change the Disk Storage settings above.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings.
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
See also the OS-specific follow-up instructions below.
@ -45,30 +43,32 @@ Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you
~~~
qvm-volume extend <vm_name>:root <size>
~~~
OR
~~~
qvm-volume extend <vm_name>:private <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
**Make sure changes in the Template between reboots don't exceed 10G.**
It is recommended that you restart (or start and then shutdown, if it is not running) the template after resizing the root image.
If you are **not** using Linux in the qube, you will also need to:
1. Start the template.
2. Resize the filesystem using OS appropriate tools.
3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template.
1. Start the template.
2. Resize the filesystem using OS appropriate tools.
3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template.
#### Windows 7 ####
#### Windows 7
1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management
3. Right-click on your existing volume, select "Extend Volume..."
4. Click through the wizard.
1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management
3. Right-click on your existing volume, select "Extend Volume..."
4. Click through the wizard.
No reboot required.
@ -87,19 +87,18 @@ 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.
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.
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.
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.)
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:
```
qvm-shutdown qube1
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.
[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).*)
[qrexec3]: /doc/qrexec3/

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

@ -9,7 +9,7 @@ permalink: /doc/salt/
Since the Qubes R3.1 release we have included the Salt (also called SaltStack)
management engine in dom0 as default (with some states already configured).
Salt allows administrators to easily configure their systems.
In this guide we will show how it is set up and how you can modify it for your
In this guide we will show how it is set up and how you can modify it for your
own purpose.
In the current form the **API is provisional** and subject to change between
@ -20,48 +20,48 @@ In the current form the **API is provisional** and subject to change between
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site][salt-doc], though we
must warn you that it is not easy to read if you just start working with Salt
For more exhaustive documentation, visit [official site][salt-doc], though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
### The Salt Architecture
Salt is a client-server model, where the server (called *master*) manages
its clients (called *minions*).
In typical situations, it is intended that the administrator interacts only
In typical situations, it is intended that the administrator interacts only
with the master and keeps the configurations there.
In Qubes, we don't have a master.
Instead we have one minion which resides in `dom0` and manages domains from
Instead we have one minion which resides in `dom0` and manages domains from
there.
This setup is also supported by Salt.
Salt is a management engine (similar to Ansible, Puppet, and Chef), that
Salt is a management engine (similar to Ansible, Puppet, and Chef), that
enforces a particular state of a minion system.
A *state* is an end effect *declaratively* expressed by the administrator.
This is the most important concept in the entire engine.
All configurations (i.e., the states) are written in YAML.
A *pillar* is a data back-end declared by the administrator.
When states become repetitive, instead of pure YAML they can be written using a
template engine (preferably Jinja2); which can use data structures specified in
When states become repetitive, instead of pure YAML they can be written using a
template engine (preferably Jinja2); which can use data structures specified in
pillars.
A *formula* is a ready to use, packaged solution that combines a state and a
A *formula* is a ready to use, packaged solution that combines a state and a
pillar (possibly with some file templates and other auxiliary files).
There are many formulas made by helpful people all over the Internet.
A *grain* is some data that is also available in templates, but its value is not
directly specified by administrator.
For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
the grain `"os"`. It also contains other information about the kernel,
For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
the grain `"os"`. It also contains other information about the kernel,
hardware, etc.
A *module* is a Python extension to Salt that is responsible for actually
enforcing the state in a particular area.
It exposes some *imperative* functions for the administrator.
For example, there is a `system` module that has a `system.halt` function that,
For example, there is a `system` module that has a `system.halt` function that,
when issued, will immediately halt a domain.
There is another function called `state.highstate` which will synchronize the
There is another function called `state.highstate` which will synchronize the
state of the system with the administrator's configuration/desires.
### Configuration
@ -73,9 +73,9 @@ A state is written in YAML and looks like this:
stateid:
cmd.run: #this is the execution module. in this case it will execute a command on the shell
- name: echo 'hello world' #this is a parameter of the state.
- name: echo 'hello world' #this is a parameter of the state.
The stateid has to be unique throughout all states running for a minion and can
The stateid has to be unique throughout all states running for a minion and can
be used to order the execution of the references state.
`cmd.run` is an execution module.
It executes a command on behalf of the administrator.
@ -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 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.)
* For [installing and uninstalling][salt-doc-states-pkg] packages.
* For [executing shell commands][salt-doc-states-cmd].
- For [installing and uninstalling][salt-doc-states-pkg] packages.
- For [executing shell commands][salt-doc-states-cmd].
With these three states you can define most of the configuration of a VM.
@ -114,14 +114,14 @@ You can also [order the execution][salt-doc-states-order] of your states:
- order: 1
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
The official documentation has more details on the
[require][salt-doc-states-req] and [order][salt-doc-states-ord] arguments.
#### State Files
When configuring a system you will write one or more state files (`*.sls`) and
put (or symlink) them into the main Salt directory `/srv/salt/`.
Each state file contains multiple states and should describe some unit of
Each state file contains multiple states and should describe some unit of
configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
@ -138,7 +138,7 @@ Their structure looks like this:
In most cases, the environment will be called `base`.
The `target_matching_clause` will be used to select your minions (VMs).
It can be either the name of a VM or a regular expression.
If you are using a regular expressions, you need to give Salt a hint you are
If you are using a regular expressions, you need to give Salt a hint you are
doing so:
environment:
@ -147,9 +147,9 @@ doing so:
- statefile
For each target you can write a list of state files.
Each line is a path to a state file (without the `.sls` extension) relative to
Each line is a path to a state file (without the `.sls` extension) relative to
the main directory.
Each `/` is exchanged with a `.`, so you can't reference files or directories
Each `/` is exchanged with a `.`, so you can't reference files or directories
with a `.` in their name.
### Enabling Top Files and Applying the States
@ -157,19 +157,27 @@ with a `.` in their name.
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:
$ qubesctl top.enable my-new-vm
```
$ qubesctl top.enable my-new-vm
```
To list all enabled top files:
$ qubesctl top.enabled
```
$ qubesctl top.enabled
```
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:
$ qubesctl --all state.highstate
```
$ qubesctl --all state.highstate
```
(More information on the `qubesctl` command further down.)
@ -178,13 +186,13 @@ To apply the states to dom0 and all VMs:
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja][jinja].
Jinja is similar to Python and in many cases behaves in a similar fashion, but
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation][jinja-tmp].
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation][jinja-call-salt-functions].
## Salt Configuration, QubesOS layout
@ -192,7 +200,7 @@ about your system can be found in the official
All Salt configuration files are in the `/srv/` directory, as usual.
The main directory is `/srv/salt/` where all state files reside.
States are contained in `*.sls` files.
However, the states that are part of the standard Qubes distribution are mostly
However, the states that are part of the standard Qubes distribution are mostly
templates and the configuration is done in pillars from formulas.
The formulas are in `/srv/formulas`, including stock formulas for domains in
@ -206,7 +214,7 @@ It accepts all the same arguments of the vanilla tool.
Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
You can also use the `qubes` pillar module to select VMs with a particular
property (see below).
If you do so, then you need to pass additional arguments to the `qubesctl` tool:
@ -228,16 +236,15 @@ If you do so, then you need to pass additional arguments to the `qubesctl` tool:
--app Target all AppVMs
--all Target all non-disposable VMs (TemplateVMs and AppVMs)
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`
instead of `ssh`).
Which means you don't need to install anything special in a VM you want to
Which means you don't need to install anything special in a VM you want to
manage.
Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
Beginning with Qubes 4.0 and after [QSB #45], we implemented two changes:
@ -273,16 +280,16 @@ Let's start with a quick example:
It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
present (if not, it creates it).
* The `name` flag informs Salt that the domain should be named `salt-test` (not
- The `name` flag informs Salt that the domain should be named `salt-test` (not
`my new and shiny VM`).
* The `template` flag informs Salt which template should be used for the domain.
* The `label` flag informs Salt what color the domain should be.
* The `mem` flag informs Salt how much RAM should be allocated to the domain.
* The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
- The `template` flag informs Salt which template should be used for the domain.
- The `label` flag informs Salt what color the domain should be.
- The `mem` flag informs Salt how much RAM should be allocated to the domain.
- The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
domain
* The `proxy` flag informs Salt that the domain should be a ProxyVM.
- 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`.
This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file.
@ -292,21 +299,25 @@ A separate `*.top` file should be also written:
dom0:
- my-new-vm
**Note** The third line should contain the name of the previous state file,
**Note** The third line should contain the name of the previous state file,
without the `.sls` extension.
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:
$ qubesctl state.highstate
```
$ qubesctl state.highstate
```
### Example of Configuring a VM's System from Dom0
Lets make sure that the `mc` package is installed in all templates.
Similar to the previous example, you need to create a state file
Similar to the previous example, you need to create a state file
(`/srv/salt/mc-everywhere.sls`):
mc:
@ -321,11 +332,15 @@ Then the appropriate top file (`/srv/salt/mc-everywhere.top`):
Now you need to enable the top file:
$ qubesctl top.enable mc-everywhere
```
$ qubesctl top.enable mc-everywhere
```
And apply the configuration:
$ qubesctl --all state.highstate
```
$ qubesctl --all state.highstate
```
## All Qubes-specific States
@ -369,15 +384,16 @@ Ensures the specified domain is running:
qvm.running:
- name: salt-test4
## Virtual Machine Formulae
You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details.
The default settings can be overridden in the pillar data located in:
```
/srv/pillar/base/qvm/init.sls
```
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`).
@ -472,22 +488,24 @@ Updates dom0
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:
- `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
(Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL.
- `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
(Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL.
For other options, see `qubesctl --help`.
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configurations (for example all templates).
Additional pillar data is available to ease targeting configurations (for example all templates).
**Note:** This list is subject to change in future releases.
@ -495,10 +513,10 @@ Additional pillar data is available to ease targeting configurations (for exampl
VM type. Possible values:
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `standalone` - Standalone VM
- `app` - Template based AppVM
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `standalone` - Standalone VM
- `app` - Template based AppVM
### `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
## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
@ -517,12 +534,14 @@ If the log does not contain useful information:
1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
2. When your VM is being started (yellow) press Ctrl-z on qubesctl.
3. Open terminal in disp-mgmt-VM_NAME.
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
executed in the management VM.
5. Get the last two lines:
```shell_session
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command
```
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
6. Execute them, fix problems, repeat.
@ -534,8 +553,10 @@ If the log does not contain useful information:
The fedora-24-minimal package is missing the `sudo` package.
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.
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
* [Salt documentation][salt-doc]
* [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
- [Salt documentation][salt-doc]
- [Salt states][salt-doc-states] ([files][salt-doc-states-file], [commands][salt-doc-states-cmd],
[packages][salt-doc-states-pkg], [ordering][salt-doc-states-order])
* [Top files][salt-doc-top]
* [Jinja templates][jinja]
* [Qubes specific modules][salt-qvm-doc]
* [Formulas for default Qubes VMs][salt-virtual-machines-states]
- [Top files][salt-doc-top]
- [Jinja templates][jinja]
- [Qubes specific modules][salt-qvm-doc]
- [Formulas for default Qubes VMs][salt-virtual-machines-states]
[salt-doc]: https://docs.saltstack.com/en/latest/
[salt-qvm-doc]: https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst

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

@ -8,15 +8,14 @@ redirect_from:
- /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.
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.
These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
@ -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:
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:
# <pool_name> is a freely chosen pool name
# <vg_name> is LVM volume group name
# <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
```shell_session
# <pool_name> is a freely chosen pool name
# <vg_name> is LVM volume group name
# <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:
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:
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.
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.
### 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):
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:
sudo nano /etc/crypttab
```
sudo nano /etc/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):
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>:
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):
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
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:
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```
[Qubes Backup]: /doc/BackupRestore/
[TemplateVM]: /doc/Templates/

134
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]!
## Creating and Using a USB qube ##
**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].
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:
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.
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.
2. Create a new qube.
Give it an appropriate name and color label (recommended: `sys-usb`, red).
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.
Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
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.
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.
2. Create a new qube.
Give it an appropriate name and color label (recommended: `sys-usb`, red).
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.
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.
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.
**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.
4. Click `OK`.
Restart the qube.
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.)
4. Click `OK`.
Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
(This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
If the USB qube will not start, please have a look at the [faq].
## Enable a USB keyboard for login ##
**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.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices].
### Automatic setup ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates]) and execute in dom0:
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.
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.
### 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.
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:
sys-usb dom0 allow
```
sys-usb dom0 allow
```
(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:
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!*
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.
## Auto Enabling A USB Mouse ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices] before proceeding.
@ -111,20 +116,25 @@ 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:
/etc/qubes-rpc/policy/qubes.InputMouse
```
/etc/qubes-rpc/policy/qubes.InputMouse
```
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.
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
(Change `sys-usb` to your desired USB qube.)
```
sys-usb dom0 allow
```
(Change `sys-usb` to your desired USB qube.)
## How to hide all USB controllers from dom0 ##
@ -149,49 +159,47 @@ If dom0 cannot read your USB AEM device, AEM will hang.
The procedure to hide all USB controllers from dom0 is as follows:
* GRUB2
* GRUB2
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
* EFI
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.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. Reboot.
* EFI
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.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. Reboot.
## Removing a USB qube ##
**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
* GRUB2
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
* GRUB2
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.
[remove your USB-qube]: #removing-a-usb-qube
[security implications]: /doc/device-handling-security/#usb-security

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

@ -21,7 +21,7 @@ any GNU/Linux system with the following procedure.
**Note:** In the following example, the backup file is assumed to be both
encrypted and compressed.
1. Untar the main backup file.
1. Untar the main backup file.
~~~
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
@ -41,13 +41,13 @@ encrypted and compressed.
dom0-home/dom0user.000.hmac
~~~
2. Verify the integrity of the `private.img` file which houses your data.
2. Verify the integrity of the `private.img` file which houses your data.
~~~
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
~~~
@ -59,14 +59,14 @@ encrypted and compressed.
complete list of supported message digest algorithms can be found with
`openssl list-message-digest-algorithms`.
3. Decrypt the `private.img` file.
3. Decrypt the `private.img` file.
~~~
[user@restore vm1]$ openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in private.img.000 -out private.img.dec.000
~~~
**Note:** For multi-part files, a loop can be used:
~~~
find -name 'private.img.*' | sort -V | while read f; do
openssl enc -d -pass pass:your_passphrase -aes-256-cbc -in $f -out
@ -79,7 +79,7 @@ encrypted and compressed.
list of supported cipher algorithms can be found with `openssl
list-cipher-algorithms`.
4. Decompress the decrypted `private.img` file.
4. Decompress the decrypted `private.img` file.
~~~
[user@restore vm1]$ zforce private.img.dec.*
@ -89,7 +89,7 @@ encrypted and compressed.
**Note:** If your backup was compressed with a program other than `gzip`, you
must substitute the correct compression program.
5. Untar the decrypted and decompressed `private.img` file.
5. Untar the decrypted and decompressed `private.img` file.
~~~
[user@restore vm1]$ tar -M -xvf private.img.dec.000
@ -98,7 +98,7 @@ encrypted and compressed.
**Note:** For multi-part files, a script is required:
1. Create a `new-volume-script`:
1. Create a `new-volume-script`:
~~~
#!/bin/sh
@ -107,11 +107,11 @@ encrypted and compressed.
echo $name.$suffix >&$TAR_FD
~~~
2. `chmod +x new-volume-script`.
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
2. `chmod +x new-volume-script`.
3. `tar --new-volume-script=./new-volume-script -xvf private.img.dec.000`.
(The `--new-volume-script` option enables multi-volume untaring.)
6. Mount the private.img file and access your data.
6. Mount the private.img file and access your data.
~~~
[user@restore vm1]$ sudo mkdir /mnt/img
@ -123,6 +123,4 @@ encrypted and compressed.
**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
while this web page is inaccessible. You may obtain a plaintext version of
this file in Git repository housing all the documentation at:
https://github.com/QubesOS/qubes-doc.git
this file in Git repository housing all the documentation on [Github](https://github.com/QubesOS/qubes-doc.git)

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

@ -44,7 +44,7 @@ any GNU/Linux system with the following procedure.
[user@restore ~]$ openssl dgst -sha512 -hmac "your_passphrase" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
[user@restore ~]$ cat backup-header.hmac
[user@restore ~]$ cat backup-header.hmac
(stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
**Note:** The hash values should match. If they do not match, then the
@ -69,7 +69,7 @@ any GNU/Linux system with the following procedure.
encrypted=True
compressed=True
compression-filter=gzip
**Note:** If you see `version=2` here, go to [Emergency Backup Recovery -
format version 2](/doc/backup-emergency-restore-v2/) instead.
@ -78,7 +78,7 @@ any GNU/Linux system with the following procedure.
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "your_passphrase" private.img.000
HMAC-SHA512(private.img.000)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
[user@restore vm1]$ cat private.img.000.hmac
[user@restore vm1]$ cat private.img.000.hmac
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
**Note:** The hash values should match. If they do not match, then the
@ -137,4 +137,3 @@ any GNU/Linux system with the following procedure.
repository:
https://github.com/QubesOS/qubes-doc.git

5
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
any GNU/Linux system with the following procedure.
Required `scrypt` Utility
-------------------------
@ -53,7 +52,7 @@ any GNU/Linux system.
4. Verify the signature on the `scrypt` RPM.
[user@restore ~]$ rpm -K scrypt-*.rpm
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
The message `digests signatures OK` means that both the digest (i.e., the
@ -71,7 +70,6 @@ any GNU/Linux system.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
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
[Emergency Backup Recovery without Qubes (v2)]: /doc/backup-emergency-restore-v2/
[Emergency Backup Recovery without Qubes (v3)]: /doc/backup-emergency-restore-v3/

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

@ -25,7 +25,7 @@ Backing up changes to dom0
--------------------------
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up.
Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup.
Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup.
Here is an example of how to back up Qubes config files and RPC policies:
$ mkdir -p ~/backup/etc/qubes/
@ -48,7 +48,7 @@ Creating a backup
You may choose whether to compress backups by checking or unchecking the **Compress the backup** box.
Normally this should be left on unless you have a specific reason otherwise.
Once you have selected all desired VMs, click **Next**.
3. Select the destination for the backup:
@ -56,7 +56,7 @@ Creating a backup
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
For example, if you wish to send your backup to the `~/backups` folder in the target VM, you would simply browse to it using the convenient directory selection dialog (`...`) at the right.
This destination directory must already exist.
If it does not exist, you must create it manually prior to backing up.
@ -68,7 +68,7 @@ Creating a backup
**Note:** The supplied passphrase is used for **both** encryption/decryption and integrity verification.
At this point, you may also choose whether to save your settings by checking or unchecking the **Save settings as default backup profile** box.
**Warning: Saving the settings will result in your backup passphrase being saved in plaintext in dom0, so consider your threat model before checking this box.**
4. You will now see the summary of VMs to be backed up.
@ -83,7 +83,6 @@ Creating a backup
This step is optional but strongly recommended.
A backup is useless if you can't restore your data from it, and you can't be sure that your backup is good until you try to restore.
Restoring from a backup
-----------------------
@ -95,31 +94,31 @@ This brings up the **Qubes Restore VMs** window.
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
For example, if you had chosen the `~/backups` directory of a VM as your destination in step 3, you would now select the same VM and again browse to (using `...`) the `backups` folder.
Once you've located the backup file, double-click it or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.
However, it does not currently detect if it is missing data as long as it is a correctly structured, non-corrupted backup file.
See [issue #3498](https://github.com/QubesOS/qubes-issues/issues/3498) for more details.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
4. If your backup is encrypted, you must check the **Encrypted backup** box.
If a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
**Note:** The passphrase which was supplied when the backup was created was used for **both** encryption/decryption and integrity verification.
If the backup was not encrypted, the supplied passphrase is used only for integrity verification.
All backups made from a Qubes R4.0 system will be encrypted.
5. You will now see the summary of VMs to be restored.
5. You will now see the summary of VMs to be restored.
If there are any issues preventing the restore, they will be listed here and the **Next** button grayed out.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
6. When you are ready, click **Next**.
Qubes will proceed to restore from your backup.
Once the progress bar has completed, you may click **Finish**.
**Note:** When restoring from a dom0 backup, a new directory will be created in the current dom0 home directory, and the contents from the backup will be placed inside this new directory.
@ -128,20 +127,18 @@ 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).
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.
No special Qubes-specific tools are required to access data backed up by Qubes.
In the event a Qubes system is unavailable, you can access your data on any GNU/Linux system with the following procedure.
Refer to the following for emergency restore of a backup created on:
* [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
* [Qubes R3](/doc/backup-emergency-restore-v3/)
* [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
- [Qubes R4 or newer](/doc/backup-emergency-restore-v4/)
- [Qubes R3](/doc/backup-emergency-restore-v3/)
- [Qubes R2 or older](/doc/backup-emergency-restore-v2/)
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:
* If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
- If you plan to store the backup for a long time or on third-party servers, you should make sure to use a very long, high-entropy passphrase.
(Depending on the decryption passphrase you use for your system drive, this may necessitate selecting a stronger passphrase.
If your system drive decryption passphrase is already sufficiently strong, it may not.)
* An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
- An adversary who has access to your backups may try to substitute one backup for another.
For example, when you attempt to retrieve a recent backup, the adversary may instead give you a very old backup containing a compromised VM.
If you're concerned about this type of attack, you may wish to use a different passphrase for each backup, e.g., by appending a number or date to the passphrase.
* If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
- If you're forced to enter your system drive decryption passphrase in plain view of others (where it can be shoulder-surfed), then you may want to use a different passphrase for your backups (even if your system drive decryption passphrase is already maximally strong).
On the other hand, if you're careful to avoid shoulder-surfing and/or have a passphrase that's difficult to detect via shoulder-surfing, then this may not be a problem for you.
Notes
-----
* For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
* If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).
- For the technical details of the backup system, please refer to [this thread](https://groups.google.com/d/topic/qubes-devel/TQr_QcXIVww/discussion).
- If working with symlinks, note the issues described in [this thread](https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion).

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

@ -9,21 +9,20 @@ redirect_from:
- /wiki/StickMounting/
---
# Block (Storage) Devices #
# Block (Storage) Devices
*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".
## 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].
In addition to smaller flash memory sticks, this includes things like USB external hard drives.)
Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
Attaching USB drives is integrated into the Devices Widget: ![device manager icon]
Attaching USB drives is integrated into the Devices Widget: ![device manager icon]
Simply insert your USB drive and click on the widget.
You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example.
Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB].
@ -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.
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 a block device isn't automatically mounted after attaching, open a terminal in the VM and execute:
cd ~
mkdir mnt
sudo mount /dev/xvdi2 mnt
```
cd ~
mkdir mnt
sudo mount /dev/xvdi2 mnt
```
where `xvdi2` needs to be replaced with the partition you want to mount.
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].
## 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`.
@ -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.
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:
qvm-block
1. In a dom0 console (running as a normal user), list all available block devices:
```
qvm-block
```
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 string after the colon is the ID of the device used within the qube, like so:
sourceVM:sdb Cruzer () 4GiB
sourceVM:sdb1 Disk () 2GiB
```
sourceVM:sdb Cruzer () 4GiB
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:
```
qvm-block attach work sys-usb:sdb
```
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
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`.
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 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 ~
mkdir mnt
sudo mount /dev/xvdi mnt
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 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:
4. When you finish using the block device, click the eject button or right-click and select **Unmount**.
```
cd ~
mkdir mnt
sudo mount /dev/xvdi mnt
```
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:
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].
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].)
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.
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:
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`).
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`).
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`).
You can get it from the `qvm-block` listing:
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`).
You can get it from the `qvm-block` listing:
[user@dom0 ~]$ qvm-block
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
```shell_session
[user@dom0 ~]$ qvm-block
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
```
In above example, all `xl block-attach` parameters can be deduced from the output of `qvm-block`.
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
* `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.
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.
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.
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.
The newly created loop device should show up:
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
sourceVM:loop0 /path/to/file
```shell_session
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
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.
(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 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:
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`.
### read-only ###
### read-only
Attach device in read-only mode.
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:
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`:
qvm-block a work sys-usb:sda1 --ro
```
qvm-block a work sys-usb:sda1 --ro
```
The two commands are equivalent.
### devtype ###
### devtype
Usually, a block device is attached as disk.
In case you need to attach a block device as cdrom, this option allows that.
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`.
[device handling in qubes]: /doc/device-handling/
[mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class
[device manager icon]:/attachment/wiki/Devices/media-removable.png
@ -242,4 +263,3 @@ This option accepts `cdrom` and `disk`, default is `disk`.
[losetup]: https://linux.die.net/man/8/losetup
[USB]:/doc/usb-devices/
[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`:
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.
@ -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.)
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`):
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/
---
# Device Handling #
# Device Handling
This is an overview of device handling in Qubes OS.
For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages.
@ -107,13 +107,11 @@ DEVICE_CLASS however is required.
**SYNOPSIS**:
`qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]`
## Actions ##
## Actions
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.
`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:
- `--all` - equivalent to specifying every VM name after `list`.
- `--all` - equivalent to specifying every VM name after `list`.
No VM-name implies `--all`.
- `--exclude` - exclude VMs from `--all`.
- `--exclude` - exclude VMs from `--all`.
Requires `--all`.
**SYNOPSIS**
`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.
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:
- `--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.
- `--option`, `-o` - set additional options specific to DEVICE_CLASS.
- `--option`, `-o` - set additional options specific to DEVICE_CLASS.
**SYNOPSIS**
`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.
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**
`qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]`
[block]:/doc/block-devices/
[USB]:/doc/usb-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
[eject icon]: /attachment/wiki/Devices/media-eject.png
[i4692]: https://github.com/QubesOS/qubes-issues/issues/4692

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

@ -9,7 +9,7 @@ redirect_from:
- /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.
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.
## Security ##
## Security
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.
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.
### 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).
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).
R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one.
@ -50,21 +48,25 @@ 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:
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`.
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.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default 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:
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.
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.
NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM.
NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the DisposableVM Template on which it is based.
This is a change in behaviour from R3.2, where DisposableVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DisposableVM Template on which it is based.
@ -75,40 +77,43 @@ This means if you have changed anon-whonix's `default_dispvm` to use the system
A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DisposableVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DisposableVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu.
Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu.
Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu.
**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:
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:
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".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
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.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![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.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
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**.
Wait a few seconds until a web browser starts.
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)
## 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:
@ -118,11 +123,10 @@ 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.
## 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.
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.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
Starting an arbitrary program can be done from an AppVM by running
@ -132,11 +136,10 @@ 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`.
## 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 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.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
It is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
@ -147,8 +150,7 @@ $ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
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.)
### 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).
However, sometimes you want to open email links in DisposableVMs.
@ -164,10 +166,12 @@ This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, o
#### 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`
~~~
@anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
~~~
This line means:
This line means:
- FROM: Any VM
- TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
@ -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].
## Customizing DisposableVMs
## Customizing DisposableVMs ##
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.
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.
Full instructions can be found [here](/doc/disposablevm-customization/).
[DisposableVM Template]: /doc/glossary/#disposablevm-template
[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.

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

@ -18,24 +18,24 @@ In Qubes OS, you run all your programs in lightweight [virtual machines (VMs)] c
Not every app runs in its own qube.
(That would be a big waste of resources!)
Instead, each qube represents a [security domain] (e.g., "work," "personal," and "banking").
By default, all qubes are based on a single, common [template], although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
This is important, as it means that if a qube is ever compromised, the template on which it's based (and any other qubes based on that template) will still be safe.
By default, all qubes are based on a single, common [template], although you can create more templates if you wish.
When you create a new qube, you don't copy the whole system needed for this qube to work (which would include copying all the programs).
Instead, each qube *shares* the system with its respective template.
A qube has read-only access to the system of the template on which it's based, so a qube cannot modify a template in any way.
This is important, as it means that if a qube is ever compromised, the template on which it's based (and any other qubes based on that template) will still be safe.
So, creating a large number of qubes is cheap: each one needs only as much disk space as is necessary to store its private files (e.g., the "home" folder).
If you've installed Qubes OS using the default options, a few qubes have already been created for you:
- work
- personal
- untrusted
- vault
- work
- personal
- untrusted
- vault
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.
This is designed to allow you to quickly and easily identify the trust level of a given window at a glance.
Most Qubes OS users associate red with what's untrusted and dangerous (like a red light -- stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle.
Most Qubes OS users associate red with what's untrusted and dangerous (like a red light -- stop! danger!), green with what's safe and trusted, and yellow and orange with things in the middle.
This color scheme also extends to include blue and black, which are usually interpreted as indicating progressively more trusted domains than green, with black being ultimately trusted.
However, it's totally up to you how you'd like to interpret these colors.
Qubes OS doesn't assume anything about these colors.
@ -57,57 +57,58 @@ Dom0 shouldn't be used for anything else.
In particular, [you should never run user applications in dom0][dom0-precautions].
(That's what your qubes are for!)
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:
- Go to the Application Launcher and click **Terminal Emulator**.
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
- Go to the Application Launcher and click **Terminal Emulator**.
- Press `Alt+F3`, type `xfce terminal` and press Enter twice.
- Right-click on the desktop and select **Open Terminal Here**.
Various command-line tools are described as part of this guide, and the whole reference can be found [here][tools].
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 **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 **Updates Widget** will inform you when template updates are available.
- 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 **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.
![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.
Starting apps
-------------
Apps can be started either by using the shortcuts in the Application Launcher menu or by using the command line (i.e., a terminal running in dom0).
You can start apps directly from the Application Launcher or the Application Finder (`Alt+F3`).
Each qube has its own menu directory under the scheme `Domain: <name>`.
Each qube has its own menu directory under the scheme `Domain: <name>`.
After navigating into one of these directories, simply click on the application you'd like to start:
![menu1.png](/attachment/wiki/GettingStarted/r4.0-menu1.png)
![menu2.png](/attachment/wiki/GettingStarted/r4.0-menu2.png)
By default, each qube's menu contains only a few shortcuts.
If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab.
By default, each qube's menu contains only a few shortcuts.
If you'd like to add more, enter the qube's **Qube Settings** and add them on the Applications tab.
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.:
$ qvm-run untrusted firefox
This command will start the qube if it is not already running.
```shell_session
$ qvm-run untrusted firefox
```
This command will start the qube if it is not already running.
Adding, removing, and listing qubes
-----------------------------------
@ -117,26 +118,24 @@ 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:
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
- `qvm-create`
- `qvm-remove`
- `qvm-ls`
How many qubes do I need?
-------------------------
That's a great question, but there's no one-size-fits-all answer.
It depends on the structure of your digital life, and this is at least a little different for everyone.
That's a great question, but there's no one-size-fits-all answer.
It depends on the structure of your digital life, and this is at least a little different for everyone.
If you plan on using your system for work, then it also depends on what kind of job you do.
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
It's a good idea to start out with the three qubes created automatically by the installer: work, personal, and untrusted.
If and when you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it.
You'll also be able to easily [copy][copy-files] any files you need to the newly created qube.
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.
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.
(A full list is available in the [Common Tasks] section of the documentation.)
* [Copying and Pasting Text Between Domains][copy-paste]
* [Copying and Moving Files Between Domains][copy-files]
* [Copying from (and to) dom0]
* [Fullscreen Mode]
* [DisposableVMs]
* [Device Handling] (block, USB, and PCI devices)
- [Copying and Pasting Text Between Domains][copy-paste]
- [Copying and Moving Files Between Domains][copy-files]
- [Copying from (and to) dom0]
- [Fullscreen Mode]
- [DisposableVMs]
- [Device Handling] (block, USB, and PCI devices)
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`.
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`.

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

@ -9,7 +9,7 @@ redirect_from:
- /wiki/AssigningDevices/
---
# PCI Devices #
# PCI Devices
*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.
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.
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.
@ -33,57 +32,60 @@ Limits imposed by the PC and VT-d architectures may require all functions belong
This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations].
In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time.
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.
## Attaching Devices Using the GUI ##
## Attaching Devices Using the GUI
The qube settings for a VM offers the "Devices"-tab.
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"!
- 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!)
- 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`.
- 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.
3. Select a device you want to attach to the qube and click the single arrow right! (`>`)
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.
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!
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! (`>`)
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.
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!
## `qvm-pci` Usage ##
## `qvm-pci` Usage
The `qvm-pci` tool allows PCI attachment and detachment.
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:
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`.
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.
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.
(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.
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.
This may leak usage data even without malicious intent!
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.
This increases attack surface and possibility of [side channel attacks].
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.
@ -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:
* Reboot the physical machine. (Best practice)
- Reboot the physical machine. (Best practice)
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.
Replace `<BDF>` with your full device, for example `0000:00:1c.2`:
- 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`:
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
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!
```
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
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!
[device handling in qubes]: /doc/device-handling/
[security considerations]: /doc/device-handling-security/#pci-security
@ -145,4 +149,3 @@ or
[domain manager icon]: /attachment/wiki/Devices/qubes-logo-icon.png
[qvm-device]: /doc/device-handling/#general-qubes-device-widget-behavior-and-handling
[side channel attacks]: https://en.wikipedia.org/wiki/Side-channel_attack

53
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:
$ sudo qubes-dom0-update
```
$ sudo qubes-dom0-update
```
## How to install a specific package
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).
However, this is only for advanced users who really understand what they are doing.
@ -58,7 +62,7 @@ You can also pass commands to `dnf` using `--action=...`.
**WARNING:** Downgrading a package can expose your system to security vulnerabilities.
1. Download an older version of the package:
1. Download an older version of the package:
~~~
sudo qubes-dom0-update package-version
@ -66,7 +70,7 @@ You can also pass commands to `dnf` using `--action=...`.
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Downgrade the package:
2. Downgrade the package:
~~~
sudo dnf downgrade package-version
@ -76,7 +80,7 @@ You can also pass commands to `dnf` using `--action=...`.
You can re-install in a similar fashion to downgrading.
1. Download the package:
1. Download the package:
~~~
sudo qubes-dom0-update package
@ -84,7 +88,7 @@ You can re-install in a similar fashion to downgrading.
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Re-install the package:
2. Re-install the package:
~~~
sudo dnf reinstall package
@ -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:
sudo dnf remove anti-evil-maid
```
sudo dnf remove anti-evil-maid
```
## 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
* `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
* `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
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.
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:
- `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
@ -160,11 +168,13 @@ from the update command), you may need to manually rebuild the EFI or grub confi
your system uses.
*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
~~~
*Grub2*
~~~
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.
*EFI*
~~~
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.
For example,
~~~
default=4.19.67-1.pvops.qubes.x86_64
~~~
*Grub2*
~~~
sudo nano /etc/default/grub
[update the following two lines, add if needed]
@ -201,12 +215,13 @@ GRUB_SAVEDEFAULT=true
[save and exit nano]
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Then, reboot.
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").
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/).
@ -215,8 +230,9 @@ See the UpdateVM setting.
Choose your desired Whonix-Gateway ProxyVM from the list.
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
[Updating Qubes OS]: /doc/updating-qubes-os/
@ -225,4 +241,3 @@ For example: sys-whonix.
[troubleshooting newer hardware]: /doc/newer-hardware-troubleshooting/
[Managing VM kernel]: /doc/managing-vm-kernel/
[installing contributed packages]: /doc/installing-contributed-packages/

68
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.
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
To permanently install new software in a TemplateVM:
1. Start the TemplateVM.
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
1. Start the TemplateVM.
2. Start either a terminal (e.g. `gnome-terminal`) or a dedicated software management application, such as `gpk-application`.
3. Install software as normally instructed inside that operating system (e.g. `sudo dnf install <PACKAGE_NAME>` on Fedora, `sudo apt install <PACKAGE_NAME>` on Debian).
4. Shut down the TemplateVM.
5. Restart all [TemplateBasedVMs] based on the TemplateVM so the changes can take effect.
6. (Optional) In the relevant [TemplateBasedVMs]' **Qube Settings**, go to the **Applications** tab, select the new application(s) from the list, and press OK.
These new shortcuts will appear in the Applications Menu.
(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)
## Updating software in TemplateVMs
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**.
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
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):
* `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-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) repository; mostly experimental debugging packages
- `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-*-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.
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`.
### Debian
Debian also has three Qubes VM testing repositories (where `*` denotes the Release):
* `*-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
* `*-unstable` -- packages that are not intended to land in the stable repository; mostly experimental debugging packages
- `*-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
- `*-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`.
## Contributed package repository
Please see [installing contributed packages].
## StandaloneVMs
When you create a [StandaloneVM] from a TemplateVM, the StandaloneVM is a complete clone of the TemplateVM, including the entire filesystem.
@ -92,15 +86,13 @@ Therefore, it will not be updated when the TemplateVM is updated.
Rather, it must be updated individually.
The process for installing and updating software in StandaloneVMs is the same as described above for TemplateVMs.
## Advanced
The following sections cover advanced topics pertaining to installing and updating software in domUs.
### 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):
~~~
sudo dnf config-manager --set-enabled rpmfusion-free
@ -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 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
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.
However, it is a bit more complex.
#### Root revert
**Important:** This command will roll back any changes made *during the last time the TemplateVM was run, but **not** before.*
@ -145,25 +135,24 @@ Just make sure to **back up** all of your data and changes first!
2. In a dom0 terminal:
```
qvm-volume revert <template>:root
```
#### Reinstall the template
Please see [How to Reinstall a TemplateVM].
#### Full revert
This is like the simple revert, except:
- 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.
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.
With the default `revisions_to_keep=1` for the root volume, you must **not** have started the template since the compromising action.
- 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.
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.
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
@ -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.
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 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.
The defaults listed above are applied if the service is not explicitly listed in the services tab.
#### Technical details
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.
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):
```
```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
@tag:whonix-updatevm @default allow,target=sys-whonix
@tag:whonix-updatevm @anyvm deny
@ -250,8 +237,8 @@ Last metadata expiration check: 0:57:08 ago on Thu Nov 14 09:26:47 2019.
Notifying dom0 about installed applications
Installed:
snapd-2.42.1-1.fc30.x86_64 qubes-snapd-helper-1.0.1-1.fc30.noarch
[...]
snapd-2.42.1-1.fc30.x86_64 qubes-snapd-helper-1.0.1-1.fc30.noarch
[...]
Complete!
```
@ -275,6 +262,7 @@ Shutdown the TemplateVM:
```shell_session
[user@snap-demo-AppVM ~]$ snap install <package>
```
When the install is complete you can close the terminal window.
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.
### 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.
@ -303,7 +290,7 @@ yelp.desktop
3. Create the autostart directory:
```shell_session
```
[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.
[domUs]: /doc/glossary/#domu
[TemplateVMs]: /doc/templates/
[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/
[installing contributed packages]: /doc/installing-contributed-packages/
[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:
- [Dom0]
- [TemplateVMs]
- [StandaloneVMs] (if you have any)
- [Dom0]
- [TemplateVMs]
- [StandaloneVMs] (if you have any)
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."
@ -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]).
The one exception is dom0, which [doesn't have to be upgraded][dom0-eol].
[supported version of Qubes OS]: /doc/supported-versions/#qubes-os
[Upgrade Guides]: /doc/upgrade/
[security]: /security/

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

@ -6,7 +6,7 @@ redirect_from:
- /doc/usb/
---
# USB Devices #
# USB Devices
*This page is part of [device handling in qubes].*
@ -20,20 +20,18 @@ Whenever possible, attach a [block device] instead.
Examples of valid cases for USB-passthrough:
- [microcontroller programming]
- [external audio devices]
- [optical drives] for recording
- [microcontroller programming]
- [external audio devices]
- [optical drives] for recording
(If you are thinking to use a two-factor-authentication device, [there is an app for that][qubes u2f proxy].
But it has some [issues][4661].)
## 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.
USB-devices have a USB-icon to their right: ![usb icon]
@ -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.
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.
Listing available USB devices:
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_HP_X1200_USB_Optical_Mouse
```shell_session
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
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:
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera work
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```shell_session
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
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.
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.
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
sys-usb:2-5 058f:3822 058f_USB_2.0_Camera
sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse
```shell_session
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
sys-usb:2-4 04ca:300d 04ca_300d
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 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.
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`
- 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!
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.
In situations like these, you can try to pass through the entire USB controller to a qube as PCI device.
@ -122,26 +120,33 @@ 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):
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:
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)
The device is connected to USB bus \#3.
The device is connected to USB bus \#3.
Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM.
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:
../../../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.
@ -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`
[device handling in qubes]: /doc/device-handling/
[block device]: /doc/block-devices/
[security considerations]: /doc/device-handling-security/#usb-security

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

@ -26,20 +26,26 @@ inherits the pool default revisions_to_keep.
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:
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,
revisions_to_keep should probably be set to the minimum value of 1 to minimize
the possibility of the pool being accidentally filled up by snapshots. For a
smaller volume for which you would like to have the future option of reverting,
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 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
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:
qvm-volume revert vmname:private <revision>
```
qvm-volume revert vmname:private <revision>
```

50
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.
## Installer Defaults
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 /
~~~
## Typical Partition Schemes
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]
~~~
## Encryption Defaults
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:
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
- AES-128 [[1]][cryptsetup-faq][[2]][dm-crypt][[3]][tomb-238]
- SHA-256
- `/dev/urandom`
- probably an `iter-time` of one second
If, instead, you'd like to use AES-256, SHA-512, `/dev/random`, and a longer `iter-time`, for example, you can configure encryption manually by following the instructions below.
## Example: Custom LUKS Configuration
Boot into the Qubes installer, then press `ctrl`+`alt`+`F2` to get a virtual console.
1. (Optional) Wipe the disk:
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
```
# dd if=/dev/zero of=/dev/sda bs=1M status=progress && sync
```
2. Create partitions:
# fdisk /dev/sda
```
# fdisk /dev/sda
```
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:
# 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:
# cryptsetup open /dev/sda2 luks
```
# cryptsetup open /dev/sda2 luks
```
6. Create LVM volumes:
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root
```
# pvcreate /dev/mapper/luks
# vgcreate qubes_dom0 /dev/mapper/luks
# lvcreate -n swap -L 10G qubes_dom0
# lvcreate -T -l +100%FREE qubes_dom0/pool00
# lvcreate -V1G -T qubes_dom0/pool00 -n root
# lvextend -L <size_of_pool00> /dev/qubes_dom0/root
```
8. Proceed with the installer. You can do that either by pressing `ctrl`+`alt`+`F6`, or by rebooting and restarting the installation.
At the disk selection screen, select:
[x] I will configure partitioning.
[ ] Encrypt my data.
```
[x] I will configure partitioning.
[ ] Encrypt my data.
```
9. Decrypt your partition. After decrypting you may assign mount points:
Open the Unknown list and select `qubes_dom0-root`. Check the reformat box to the right and choose `ext4` as a filesystem. Enter `/` into the Mount Point field at the top.
@ -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`.
When you are finished, the Unknown list should go away, and all three mount points should be assigned. Proceed normally with the installation from there.
[cryptsetup-faq]: https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions
[dm-crypt]: https://wiki.archlinux.org/index.php/dm-crypt/Device_encryption
[tomb-238]: https://github.com/dyne/Tomb/issues/238

11
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
helpful in streamlining the process.
* We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew].
* We are happy to provide rsync or HTTP master.
* Our preferred frequency is **once every 24 hours**, but anything up to once
every 6-8 hours is fine.
* For technical accommodations, please contact [Wojtek] or [Marek].
* For website updates and fixes, please contact [Andrew].
[mirror-list]: /downloads/#mirrors
[Wojtek]: /team/#wojtek-porczyk

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

@ -41,44 +41,42 @@ From a Qubes-specific security perspective, each has certain pros and cons.
Pros:
* Works via USB, including with a [USB qube].
* Non-fixed capacity.
(Easy to find one on which the ISO can fit.)
* Works via USB, including with a [USB qube].
* Non-fixed capacity.
(Easy to find one on which the ISO can fit.)
Cons:
* Rewritable.
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware.
(Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
Installing from a compromised drive could compromise even a brand new Qubes installation.)
* Rewritable.
(If the drive is mounted to a compromised machine, the ISO could be maliciously altered after it has been written to the drive.)
* Untrustworthy firmware.
(Firmware can be malicious even if the drive is new.
Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive][BadUSB].
Installing from a compromised drive could compromise even a brand new Qubes installation.)
### Optical discs
Pros:
* 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.
You then have the option of verifying the signature on multiple different machines.)
* 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.
You then have the option of verifying the signature on multiple different machines.)
Cons:
* Fixed capacity.
(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.
(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:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
3. Use a SATA optical drive attached to dom0.
* Fixed capacity.
(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.
(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:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
3. Use a SATA optical drive attached to dom0.
(Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)
(Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)
Considering the pros and cons of each, perhaps a USB drive with non-rewritable (or at least cryptographically-signed) firmware and a physical write-protect switch might be the best option.
[AEM]: /doc/anti-evil-maid/
[verify]: /security/verifying-signatures/
[classic problem]: https://www.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf

65
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`:
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
```
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
```
Change `Qubes-RX-x86_64.iso` to the filename of the version you're installing, and change `/dev/sdY` to the correct target device e.g., `/dev/sdc`).
Make sure to write to the entire device (e.g., `/dev/sdc`) rather than just a single partition (e.g., `/dev/sdc1`).
@ -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.
You can choose one of three options:
* Install Qubes OS
* Test this media and install Qubes OS
* Troubleshooting
* Install Qubes OS
* Test this media and install Qubes OS
* Troubleshooting
Select the option to test this media and install Qubes OS.
@ -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.
Two options are available:
* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix] qubes.
* **Debian:** Select this option if you would like to use [Debian] qubes in addition to the default Fedora qubes.
* **Whonix:** Select this option if you would like to use [Whonix] qubes.
Whonix allows you to use [Tor] securely within Qubes.
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.
</div>
Your installation destination can be an internal or external storage drive, such as an SSD, HDD, or USB drive.
The installation destination must have a least 32 GiB of free space available.
@ -314,24 +315,24 @@ These are designed to give you a more ready-to-use environment from the get-go.
Let's briefly go over the options:
* **Create default system qubes:**
These are the core components of the system, required for things like internet access.
* **Create default application qubes:**
These are how you compartmentalize your digital life.
There's nothing special about the ones the installer creates.
They're just suggestions that apply to most people.
If you decide you don't want them, you can always delete them later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:**
If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:**
You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:**
This is for very advanced users only.
If you select this option, you'll have to set everything up manually afterward.
* **Create default system qubes:**
These are the core components of the system, required for things like internet access.
* **Create default application qubes:**
These are how you compartmentalize your digital life.
There's nothing special about the ones the installer creates.
They're just suggestions that apply to most people.
If you decide you don't want them, you can always delete them later, and you can always create your own.
* **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:**
If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:**
You should select this option if you rely on a USB device for network access, such as a USB modem or a USB Wi-Fi adapter.
* **Do not configure anything:**
This is for very advanced users only.
If you select this option, you'll have to set everything up manually afterward.
When you're satisfied with you choices, press **Done**.
This configuration process may take a while, depending on the speed and compatibility of your system.
@ -381,18 +382,17 @@ Consider giving back to the Qubes community and helping other users by [generati
## Getting help
* 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.
(Since the documentation is a community effort, we'd also greatly appreciate your help in [improving] it!)
* 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.
(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.
[QSB #46]: /news/2019/01/23/qsb-46/
[system requirements]: /doc/system-requirements/
[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
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
[Get Started]: /getting-started/

16
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.
## Qubes OS
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.1 | TBA | TBA | [In development][4.1] |
### 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.
@ -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.
Therefore, point releases are not displayed as separate rows on any of the tables on this page.
## Dom0
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.1 | Fedora 32 |
### Note on dom0 and EOL
Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen, device backends (in the dom0 kernel and in other VMs, such as the NetVM), and Qubes tools (gui-daemon, qrexec-daemon, etc.).
These components are [security-critical], and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
## TemplateVMs
The following table shows select [TemplateVM] versions that are currently supported.
@ -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.
### Note on Whonix support
[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.
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.
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 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.
* 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.
* 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.
We aim to announce both types of events one month in advance in order to remind users to upgrade.
[Version Scheme]: /doc/version-scheme/
[Downloads]: /downloads/
[download mirrors]: /downloads/#mirrors
@ -106,4 +99,3 @@ We aim to announce both types of events one month in advance in order to remind
[Whonix]: /doc/whonix/
[Whonix Project]: https://www.whonix.org/
[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
--------
How to test upcoming Qubes OS releases:
* Use [qubes-builder] to build the latest release.
* Test the latest release candidate (RC), if any is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
* Use [qubes-builder] to build the latest release.
* Test the latest release candidate (RC), if any is currently available.
* (No support) Experiment with devel alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
See [Version Scheme] for details about release versions and schedules.
See [Release Checklist] for details about the RC process.
Updates
-------
How to test updates:
* Enable [dom0 testing repositories].
* Enable [TemplateVM testing repositories].
* Enable [dom0 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.
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
------------------
If you're testing new releases or updates, we would be grateful for your feedback.
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.
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/
[qubes-builder]: /doc/qubes-builder/
[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
[report a bug]: /doc/reporting-bugs/
[Providing Feedback]: #providing-feedback

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