Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-11 23:39:38 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'translation-prepare' of https://github.com/marmarek/qubes-doc into marmarek-translation-prepare

Browse Source
This commit is contained in:
Andrew David Wong 2021-03-26 20:46:10 -07:00
commit d328b1b1c9
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
219 changed files with 4770 additions and 4966 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,23 +1,23 @@
--- ---
lang: en
layout: doc layout: doc
title: Development Workflow
permalink: /doc/development-workflow/ permalink: /doc/development-workflow/
redirect_from: redirect_from:
- /en/doc/development-workflow/ - /en/doc/development-workflow/
- /doc/DevelopmentWorkflow/ - /doc/DevelopmentWorkflow/
- /wiki/DevelopmentWorkflow/ - /wiki/DevelopmentWorkflow/
ref: 66
title: Development Workflow
--- ---
Development Workflow # Development Workflow
====================
A workflow for developing Qubes OS+ A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
assumes you're using qubes-builder to build Qubes. assumes you're using qubes-builder to build Qubes.
Repositories and committing Code # Repositories and committing Code
--------------------------------
Qubes is split into a bunch of git repos. This are all contained in the Qubes is split into a bunch of git repos. This are all contained in the
`qubes-src` directory under qubes-builder. Subdirectories there are separate `qubes-src` directory under qubes-builder. Subdirectories there are separate
@ -149,21 +149,20 @@ RPMS will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
### Useful [QubesBuilder](/doc/qubes-builder/) commands ### 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. 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 mostly useful just before building ISO. **Note:** this will not show version
for components containing changes since last version tag 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. 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) 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 verify tags and show the changes. This do not merge the changes - there are
left for review as FETCH\_HEAD ref. You can merge them using `git merge left for review as FETCH\_HEAD ref. You can merge them using `git merge
FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them. FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
Copying Code to dom0 ## Copying Code to dom0
--------------------
When developing it is convenient to be able to rapidly test changes. Assuming When developing it is convenient to be able to rapidly test changes. Assuming
you're developing Qubes on Qubes, you should be working in a special VM for you're developing Qubes on Qubes, you should be working in a special VM for
@ -309,7 +308,6 @@ to `testbuilder` VM. Otherwise it creates remote pointing at github account of
the same name. In any case it points at repository matching current directory the same name. In any case it points at repository matching current directory
name. name.
## Sending packages to different VM ## Sending packages to different VM
Other useful script(s) can be used to setup local package repository hosted in Other useful script(s) can be used to setup local package repository hosted in
@ -421,10 +419,10 @@ Remember to also import gpg public key using `rpm --import`.
Steps are mostly the same as in the case of yum repo. The only details that differ: Steps are mostly the same as in the case of yum repo. The only details that differ:
- use [linux-deb] instead of [linux-yum] as a base - both in source and target VM - use [linux-deb] instead of [linux-yum] as a base - both in source and target VM
- use different `update_repo.sh` script in source VM (below) - use different `update_repo.sh` script in source VM (below)
- use `local.UpdateApt` qrexec service in target VM (code below) - use `local.UpdateApt` qrexec service in target VM (code below)
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below) - in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
`update_repo.sh` script: `update_repo.sh` script:

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

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes Builder Details
permalink: /doc/qubes-builder-details/ permalink: /doc/qubes-builder-details/
redirect_from: redirect_from:
- /en/doc/qubes-builder-details/ - /en/doc/qubes-builder-details/
- /doc/QubesBuilderDetails/ - /doc/QubesBuilderDetails/
- /wiki/QubesBuilderDetails/ - /wiki/QubesBuilderDetails/
ref: 65
title: Qubes Builder Details
--- ---
[QubesBuilder](/doc/qubes-builder/) "API" [QubesBuilder](/doc/qubes-builder/) "API"
@ -18,28 +20,28 @@ Components Makefile.builder file
Variables for Linux build: 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. - `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. - `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. Most components uses *archlinux* directory for this purpose, so its good to keep this style.
Variables for Windows build: Variables for Windows build:
- `WIN_COMPILER` Choose which compiler should be used for this component, thus which build scripts. Currently two options available: - `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*. - `WDK` - Windows Driver Kit (default). Command used to build: *build -cZg*.
- `mingw` - MinGW (Windows gcc port). Command used to build: *make all* - `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_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_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: - `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_FILENAME` Path to key file (pfx format)
- `CERT_PASSWORD` Key password - `CERT_PASSWORD` Key password
- `CERT_PUBLIC_FILENAME` Certificate path in the case of self-signed cert - `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 - `CERT_CROSS_CERT_FILENAME` Certificate path in the case of correct autheticode cert
- `SIGNTOOL` Path to signtool - `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_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_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_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_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 builder.conf settings
--------------------- ---------------------

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

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

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

@ -1,6 +1,6 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes ISO Building
permalink: /doc/qubes-iso-building/ permalink: /doc/qubes-iso-building/
redirect_from: redirect_from:
- /doc/qubes-r3-building/ - /doc/qubes-r3-building/
@ -8,6 +8,8 @@ redirect_from:
- /en/doc/qubes-iso-building/ - /en/doc/qubes-iso-building/
- /doc/QubesR3Building/ - /doc/QubesR3Building/
- /wiki/QubesR3Building/ - /wiki/QubesR3Building/
ref: 63
title: Qubes ISO Building
--- ---
Building Qubes OS ISO Building Qubes OS ISO
@ -42,7 +44,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 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 gpg --edit-key 36879494
fpr fpr
# Verify fingerprint! See Note below! # Verify fingerprint! See Note below!
@ -68,7 +70,6 @@ git tag -v `git describe`
Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build. Assuming the verification went fine, we're good to go with all the rest without ever thinking more about verifying digital signatures on all the rest of the components, apart from an additional step if doing a non-scripted build.
The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources). The builder will do that for us for each component, every time we build, even for all auxiliary files (e.g. Xen or Linux kernel sources).
Build using setup script Build using setup script
----------------- -----------------
@ -128,7 +129,6 @@ make iso
Enjoy your new ISO! Enjoy your new ISO!
Build using manual steps Build using manual steps
----------------- -----------------

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

@ -1,17 +1,16 @@
--- ---
lang: en
layout: doc layout: doc
title: Code Signing
permalink: /doc/code-signing/ permalink: /doc/code-signing/
ref: 51
title: Code Signing
--- ---
Code Signing # Code Signing
============
All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key. All contributions to the Qubes OS [source code] must be cryptographically signed by the author's PGP key.
## Generating a Key
Generating a Key
----------------
(Note: If you already have a PGP key, you may skip this step.) (Note: If you already have a PGP key, you may skip this step.)
@ -56,7 +55,7 @@ Real name: Bilbo Baggins
E-mail address: bilbo@shire.org E-mail address: bilbo@shire.org
Comment: Comment:
You selected this USER-ID: You selected this USER-ID:
"Bilbo Baggins <bilbo@shire.org>" "Bilbo Baggins <bilbo@shire.org>"
@ -78,8 +77,7 @@ uid Bilbo Baggins <bilbo@shire.org>
sub 4096R/69B0EA85 2013-03-13 sub 4096R/69B0EA85 2013-03-13
~~~ ~~~
Upload the Key ## Upload the Key
--------------
For others to find the public key, please upload it to a server. For others to find the public key, please upload it to a server.
@ -88,8 +86,7 @@ $ gpg --send-keys --keyserver pool.sks-keyservers.net 69B0EA85
gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net gpg: sending key 488BA441 to hkp server pool.sks-keyservers.net
``` ```
Using PGP with Git ## Using PGP with Git
------------------
If you're submitting a patch via GitHub (or a similar Git server), please sign If you're submitting a patch via GitHub (or a similar Git server), please sign
your Git commits. your Git commits.
@ -112,7 +109,7 @@ your Git commits.
commit -S commit -S
~~~ ~~~
3. (Optional) Create signed tags. 3. (Optional) Create signed tags.
Signed commits are totally sufficient to contribute to Qubes OS. 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, 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. you can create a signed tag for the commit and push it before the check.
@ -141,8 +138,7 @@ your Git commits.
vtag = !git tag -v `git describe` vtag = !git tag -v `git describe`
~~~ ~~~
GitHub Signature Verification (optional) ## GitHub Signature Verification (optional)
----------------------------------------
GitHub shows a green `Verified` label indicating that the GPG signature could be GitHub shows a green `Verified` label indicating that the GPG signature could be
verified using any of the contributor’s GPG keys uploaded to GitHub. You can verified using any of the contributor’s GPG keys uploaded to GitHub. You can
@ -150,16 +146,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 key][GitHub New GPG key] under the [SSH GPG keys page][GitHub SSH GPG keys
page]. page].
Code Signature Checks ## Code Signature Checks
---------------------
The [signature-checker] checks if code contributions are signed. The [signature-checker] checks if code contributions are signed.
Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed: Although GitHub adds a little green `Verified` button next to the commit, the [signature-checker] uses this algorithm to check if a commit is correctly signed:
1. Is the commit signed? 1. Is the commit signed?
If the commit is not signed, you can see the message If the commit is not signed, you can see the message
> policy/qubesos/code-signing — No signature found > 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. 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) > policy/qubesos/code-signing — Unable to verify (no valid key found)
@ -169,23 +164,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: In this case, you have several options to sign the commit:
1. Amend the commit and replace it with a signed commit. 1. Amend the commit and replace it with a signed commit.
You can use this command to create a new signed commit: You can use this command to create a new signed commit:
``` ```
git commit --amend -S git commit --amend -S
``` ```
This also rewrites the commit so you need to push it forcefully: This also rewrites the commit so you need to push it forcefully:
``` ```
git push -f git push -f
``` ```
2. Create a signed tag for the unsigned commit.
2. Create a signed tag for the unsigned commit.
If the commit is back in history and you do not want to change it, If the commit is back in history and you do not want to change it,
you can create a signed tag for this commit and push the signature. you can create a signed tag for this commit and push the signature.
You can use the alias from above: You can use the alias from above:
``` ```
git checkout <commit> git checkout <commit>
git spush git spush
``` ```
Now, the signature checker needs to re-check the signature. Now, the signature checker needs to re-check the signature.
Please comment on the pull request that you would like to have the signatures checked again. Please comment on the pull request that you would like to have the signatures checked again.
@ -198,15 +199,12 @@ but is not able to verify it using the any key available.
This might be that you forgot to upload the key to a key server. This might be that you forgot to upload the key to a key server.
Please upload it. Please upload it.
## Using PGP with Email
Using PGP with Email If you're submitting a patch by emailing the [developer mailing list], simply sign your email with your PGP key.
-------------------- 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. Enigmail is a security addon for the Mozilla Thunderbird email client that allows you to easily digitally encrypt and sign your emails.
[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/ [guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
[source code]: /doc/source-code/ [source code]: /doc/source-code/
[developer mailing list]: /support/#qubes-devel [developer mailing list]: /support/#qubes-devel
@ -214,4 +212,3 @@ Enigmail is a security addon for the Mozilla Thunderbird email client that allow
[signature-checker]: https://github.com/marmarek/signature-checker [signature-checker]: https://github.com/marmarek/signature-checker
[GitHub New GPG key]: https://github.com/settings/gpg/new [GitHub New GPG key]: https://github.com/settings/gpg/new
[GitHub SSH GPG keys page]: https://github.com/settings/keys [GitHub SSH GPG keys page]: https://github.com/settings/keys

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

@ -1,12 +1,14 @@
--- ---
lang: en
layout: doc layout: doc
title: Coding Style
permalink: /doc/coding-style/ permalink: /doc/coding-style/
redirect_from: redirect_from:
- /en/doc/coding-style/ - /en/doc/coding-style/
- /doc/CodingStyle/ - /doc/CodingStyle/
- /wiki/CodingStyle/ - /wiki/CodingStyle/
- /trac/wiki/CodingStyle/ - /trac/wiki/CodingStyle/
ref: 53
title: Coding Style
--- ---
Coding Guidelines for Qubes Developers Coding Guidelines for Qubes Developers
@ -17,10 +19,10 @@ Rationale
Maintaining proper coding style is very important for any large software project, such as Qubes. Here's why: 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 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 (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 allows others to easily review the code and catch various bugs,
- It provides for an aesthetically pleasing experience when one reads the code... - 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. 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 +31,25 @@ And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes
General typographic conventions 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***: - **Naming conventions for any OS *other than Windows***:
- `ClassName` - `ClassName`
- `some_variable`, `some_function`, `some_argument` - `some_variable`, `some_function`, `some_argument`
- **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following: - **Naming convention *for Windows OS*** -- exceptionally to preserve Windows conventions please use the following:
- `ClassName`, `FunctionName` - `ClassName`, `FunctionName`
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables - `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 (...) { for (...) {
@ -61,33 +63,33 @@ General typographic conventions
File naming 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:** **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 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-*` - 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) - 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/` - Helper, non-executable files in `/usr/share/qubes/`
- Various config files in `/etc/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/` - 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/` - 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` - 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/` - Logs: either log to the system-wide messages, or to `/var/log/qubes/`
**File naming in Windows systems:** **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) - 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` - 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 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! - 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. - 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. - 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. - 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** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
~~~ ~~~
// Return window id // Return window id
@ -97,7 +99,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 #if 0
@ -117,42 +119,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. > 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 Source Code management (Git) guidelines
--------------------------------------- ---------------------------------------
- Use git to maintain all code for Qubes project. - Use git to maintain all code for Qubes project.
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](https://git-scm.com/book). Read it. - Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
- Qubes code is divided into many git repositories. There are several reasons for that: - Qubes code is divided into many git repositories. There are several reasons for that:
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts. - This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
- 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. - 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. - 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). - 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 Commit message guidelines
------------------------- -------------------------
Please attempt to follow these conventions when writing your Git commit messages: Please attempt to follow these conventions when writing your Git commit messages:
* Separate the subject line from the body with a blank line. - Separate the subject line from the body with a blank line.
* Limit the subject line to approximately 50 characters. - Limit the subject line to approximately 50 characters.
* Capitalize the subject line. - Capitalize the subject line.
* Do not end the subject line with a period. - Do not end the subject line with a period.
* Use the imperative mood in the subject line. - Use the imperative mood in the subject line.
* Wrap the body at 72 characters. - Wrap the body at 72 characters.
* Use the body to explain *what* and *why* rather than *how*. - Use the body to explain *what* and *why* rather than *how*.
For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list. For details, examples, and the rationale behind each of these conventions, please see [this blog post](https://chris.beams.io/posts/git-commit/), which is the source of this list.
Security coding guidelines Security coding guidelines
-------------------------- --------------------------
- As a general rule: **untrusted input** is our \#1 enemy! - 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. - 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.: - 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); read_struct(untrusted_conf);
@ -165,22 +167,22 @@ Security coding guidelines
height = untrusted_conf.height; 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 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 C and C++ specific guidelines
----------------------------- -----------------------------
- Do not place code in `*.h` files. - Do not place code in `*.h` files.
- Use `const` whenever possible, e.g. in function arguments passed via pointers. - 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. - 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. - Think about classes hierarchy, before starting to implement specific methods.
Bash-specific guidelines 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.

4
developer/code/license.md
View File

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: License
permalink: /doc/license/ permalink: /doc/license/
redirect_from: redirect_from:
- /en/doc/license/ - /en/doc/license/
- /doc/QubesLicensing/ - /doc/QubesLicensing/
- /wiki/QubesLicensing/ - /wiki/QubesLicensing/
ref: 52
title: License
--- ---
Qubes OS License Qubes OS License

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

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Source Code
permalink: /doc/source-code/ permalink: /doc/source-code/
redirect_from: redirect_from:
- /en/doc/source-code/ - /en/doc/source-code/
- /doc/SourceCode/ - /doc/SourceCode/
- /wiki/SourceCode/ - /wiki/SourceCode/
ref: 54
title: Source Code
--- ---
Qubes Source Code Repositories Qubes Source Code Repositories
@ -14,11 +16,11 @@ Qubes Source Code Repositories
All the Qubes code is kept in Git repositories. We have divided the project into All the Qubes code is kept in Git repositories. We have divided the project into
several components, each of which has its own separate repository, for example: several components, each of which has its own separate repository, for example:
* `core-admin.git` -- The core Qubes infrastructure, responsible for VM * `core-admin.git` -- The core Qubes infrastructure, responsible for VM
management, VM templates, fs sharing, etc. management, VM templates, fs sharing, etc.
* `gui-daemon.git` -- GUI virtualization, Dom0 side. * `gui-daemon.git` -- GUI virtualization, Dom0 side.
* `gui-agent-linux.git` -- GUI virtualization, Linux VM side. * `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
* `linux-template-builder.git` -- Scripts and other files used to create Qubes * `linux-template-builder.git` -- Scripts and other files used to create Qubes
template images. template images.
All of our repositories are available under the [QubesOS GitHub account]. All of our repositories are available under the [QubesOS GitHub account].
@ -35,9 +37,9 @@ e.g.:
git clone https://github.com/QubesOS/qubes-core-admin.git core-admin 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 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: If you really do want to clone **all** of the repositories, you can use these commands:
~~~ ~~~
@ -53,21 +55,20 @@ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-su
(Alternatively, you can pull instead of just fetching.) (Alternatively, you can pull instead of just fetching.)
How to Send Patches How to Send Patches
------------------- -------------------
If you want to [contribute code] to the project, there are two ways. Whichever 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. 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 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 process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list] in order to notify people who a message to the [qubes-devel mailing list] in order to notify people who
do not receive GitHub notifications. 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 1. Make all the changes in your working directory, i.e. edit files, move them
around (you can use 'git mv' for this), etc. around (you can use 'git mv' for this), etc.

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

@ -1,20 +1,20 @@
--- ---
lang: en
layout: doc layout: doc
title: Automated Tests
permalink: /doc/automated-tests/ permalink: /doc/automated-tests/
redirect_from: redirect_from:
- /en/doc/automated-tests/ - /en/doc/automated-tests/
- /doc/AutomatedTests/ - /doc/AutomatedTests/
ref: 45
title: Automated Tests
--- ---
Automated Tests # Automated Tests
===============
Unit and Integration Tests ## Unit and Integration Tests
--------------------------
Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS. Starting with Qubes R3 we use [python unittest][unittest] to perform automatic tests of Qubes OS.
Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests). Despite the name, we use it for both [unit tests](https://en.wikipedia.org/wiki/Unit_tests) and [integration tests](https://en.wikipedia.org/wiki/Integration_tests).
The main purpose is, of course, to deliver much more stable releases. 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. The integration tests must be run in dom0, but some unit tests can run inside a VM as well.
@ -46,6 +46,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a
You can use `python3 -m qubes.tests.run -h` to get usage information: You can use `python3 -m qubes.tests.run -h` to get usage information:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -h [user@dom0 ~]$ python3 -m qubes.tests.run -h
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
[--do-not-clean] [--do-clean] [--loglevel LEVEL] [--do-not-clean] [--do-clean] [--loglevel LEVEL]
@ -83,9 +84,11 @@ You can use `python3 -m qubes.tests.run -h` to get usage information:
When running only specific tests, write their names like in log, in format: When running only specific tests, write their names like in log, in format:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.". MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
Example: basic/TC_00_Basic/test_000_create Example: basic/TC_00_Basic/test_000_create
```
For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list: For instance, to run only the tests for the fedora-21 template, you can use the `-l` option, then filter the list:
```
[user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking network/VmNetworking_fedora-21/test_000_simple_networking
network/VmNetworking_fedora-21/test_010_simple_proxyvm network/VmNetworking_fedora-21/test_010_simple_proxyvm
@ -108,6 +111,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app vm_qrexec_gui/TC_20_DispVM_fedora-21/test_020_gui_app
vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file vm_qrexec_gui/TC_20_DispVM_fedora-21/test_030_edit_file
[user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21` [user@dom0 ~]$ sudo -E python3 -m qubes.tests.run -v `python3 -m qubes.tests.run -l | grep fedora-21`
```
Example test run: Example test run:
@ -115,11 +119,12 @@ Example test run:
Tests are also compatible with nose2 test runner, so you can use this instead: Tests are also compatible with nose2 test runner, so you can use this instead:
```bash
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
```
This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA]. This may be especially useful together with various nose2 plugins to store tests results (for example `nose2.plugins.junitxml`), to ease presenting results. This is what we use on [OpenQA].
### Unit testing inside a VM ### Unit testing inside a VM
Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped. Many unit tests will also work inside a VM. However all of the tests requiring a dedicated VM to be run (mostly the integration tests) will be skipped.
@ -132,6 +137,7 @@ its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec)
The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/). The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
```{.bash} ```{.bash}
cd ~ cd ~
sudo dnf install python3-pip lvm2 python35 python3-virtualenv sudo dnf install python3-pip lvm2 python35 python3-virtualenv
@ -158,16 +164,17 @@ the current stable branch.
Test runs can be altered using environment variables: Test runs can be altered using environment variables:
- `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format - `DEFAULT_LVM_POOL` - LVM thin pool to use for tests, in `VolumeGroup/ThinPool` format
- `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card) - `QUBES_TEST_PCIDEV` - PCI device to be used in PCI passthrough tests (for example sound card)
- `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested - `QUBES_TEST_TEMPLATES` - space separated list of templates to run tests on; if not set, all installed templates are tested
- `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol) - `QUBES_TEST_LOAD_ALL` - load all tests (including tests for all templates) when relevant test modules are imported; this needs to be set for test runners not supporting [load_tests protocol](https://docs.python.org/3/library/unittest.html#load-tests-protocol)
### Adding a new test to core-admin ### Adding a new test to core-admin
After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py) After adding a new unit test to [core-admin/qubes/tests](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests) you'll have to include it in [core-admin/qubes/tests/\_\_init\_\_.py](https://github.com/QubesOS/qubes-core-admin/tree/master/qubes/tests/__init__.py)
#### Editing `__init__.py` #### Editing `__init__.py`
You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`. You'll also need to add your test at the bottom of the `__init__.py` file, in the method `def load_tests`, in the for loop with `modname`.
Again, given the hypothetical `example.py` test: Again, given the hypothetical `example.py` test:
@ -213,7 +220,7 @@ class SomeTestCase(unittest.TestCase):
# first test that actually use event loop will try to dereference (already # first test that actually use event loop will try to dereference (already
# destroyed) objects, resulting in SEGV # destroyed) objects, resulting in SEGV
self.loop = quamash.QEventLoop(self.qtapp) self.loop = quamash.QEventLoop(self.qtapp)
def tearDown(self): def tearDown(self):
[...] [...]
# process any pending events before destroying the object # process any pending events before destroying the object
@ -237,11 +244,10 @@ class SomeTestCase(unittest.TestCase):
gc.collect() gc.collect()
~~~ ~~~
## Installation Tests with openQA
Installation Tests with openQA **URL:** <https://openqa.qubes-os.org/>
------------------------------
**URL:** <https://openqa.qubes-os.org/>
**Tests:** <https://github.com/marmarek/openqa-tests-qubesos> **Tests:** <https://github.com/marmarek/openqa-tests-qubesos>
Manually testing the installation of Qubes OS is a time-consuming process. Manually testing the installation of Qubes OS is a time-consuming process.
@ -258,4 +264,3 @@ Thanks to an anonymous donor, our openQA system is hosted in a datacenter on har
[unittest]: https://docs.python.org/3/library/unittest.html [unittest]: https://docs.python.org/3/library/unittest.html
[OpenQA]: http://open.qa/ [OpenQA]: http://open.qa/

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

@ -1,13 +1,15 @@
--- ---
lang: en
layout: doc layout: doc
title: Mount LVM image
permalink: /doc/mount-lvm-image/ permalink: /doc/mount-lvm-image/
ref: 46
title: Mount LVM image
--- ---
# How to 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. 1: make the image available for qubesdb.
From dom0 terminal: From dom0 terminal:
@ -25,7 +27,8 @@ From dom0 terminal:
3: Attach the device to your newly created disp VM 3: Attach the device to your newly created disp VM
From the GUI, or from the command line: From the GUI, or from the command line:
```bash ```bash
[user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev
``` ```
@ -37,15 +40,19 @@ From the GUI, or from the command line:
``` ```
5: Umount and kill the VM 5: Umount and kill the VM
```
```bash
[user@dispXXXX]$ umount /mnt/ [user@dispXXXX]$ umount /mnt/
``` ```
6: Remove the image from qubesdb 6: Remove the image from qubesdb
```
```bash
[user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
``` ```
# References # References
https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625 Please consult this issue's [comment].
[comment]: https://github.com/QubesOS/qubes-issues/issues/4687#issuecomment-451626625

22
developer/debugging/profiling.md
View File

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

5
developer/debugging/safe-remote-ttys.md
View File

@ -1,10 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Safe Remote Dom0 Terminals
permalink: /doc/safe-remote-ttys/ permalink: /doc/safe-remote-ttys/
redirect_from: redirect_from:
- /en/doc/safe-remote-ttys/ - /en/doc/safe-remote-ttys/
- /doc/safe-remote-ttys/ ref: 49
title: Safe Remote Dom0 Terminals
--- ---
Safe Remote Dom0 Terminals Safe Remote Dom0 Terminals

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

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

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

@ -1,53 +1,53 @@
--- ---
lang: en
layout: doc layout: doc
title: VM Configuration Interface
permalink: /doc/vm-interface/ permalink: /doc/vm-interface/
redirect_from: redirect_from:
- /en/doc/vm-interface/ - /en/doc/vm-interface/
- /doc/VMInterface/ - /doc/VMInterface/
- /doc/SystemDoc/VMInterface/ - /doc/SystemDoc/VMInterface/
- /wiki/SystemDoc/VMInterface/ - /wiki/SystemDoc/VMInterface/
ref: 47
title: VM Configuration Interface
--- ---
VM Configuration Interface # VM Configuration Interface
==========================
Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes: Qubes VM have some settings set by dom0 based on VM settings. There are multiple configuration channels, which includes:
- QubesDB - QubesDB
- XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`) - XenStore (in Qubes 2, data the same as in QubesDB, keys without leading `/`)
- Qubes RPC (called at VM startup, or when configuration changed) - Qubes RPC (called at VM startup, or when configuration changed)
- GUI protocol - GUI protocol
QubesDB ## QubesDB
--------------------
### Keys exposed by dom0 to VM ### ### Keys exposed by dom0 to VM
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM` - `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False` - `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `/qubes-vm-persistence` - what data do persist between VM restarts: - `/qubes-vm-persistence` - what data do persist between VM restarts:
- `full` - all disks - `full` - all disks
- `rw-only` - only `/rw` disk - `rw-only` - only `/rw` disk
- `none` - none - `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw` - `/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). - `/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). - `/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-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-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-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip - IP address for this VM (only when VM has netvm set) - `/qubes-ip - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is) - `/qubes-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-primary-dns` - primary DNS address (only when VM has netvm set)
- `/qubes-secondary-dns` - secondary 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-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-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-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-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 - `/qubes-netvm-secondary-dns` - same as `qubes-secondary-dns` in connected VMs (only when VM serves as network backend - ProxyVM and NetVM); traffic sent to this IP on port 53 should be redirected to secondary DNS server
- `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself - `/guivm-windows-prefix` - title prefix for any window not originating from another qube. This means windows of applications running in GuiVM itself
#### Firewall rules in 3.x #### #### Firewall rules in 3.x
QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in QubesDB is also used to configure firewall in ProxyVMs. Rules are stored in
separate key for each target VM. Entries: separate key for each target VM. Entries:
@ -63,7 +63,7 @@ VM after applying rules may signal some error, writing a message to
`/qubes-iptables-error` key. This does not exclude any other way of `/qubes-iptables-error` key. This does not exclude any other way of
communicating problems - like a popup. communicating problems - like a popup.
#### Firewall rules in 4.x #### #### Firewall rules in 4.x
QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as QubesDB is also used to configure firewall in ProxyVMs. Each rule is stored as
a separate entry, grouped on target VM: a separate entry, grouped on target VM:
@ -85,19 +85,19 @@ Each rule is a single QubesDB entry, consisting of pairs `key=value` separated
by space. QubesDB enforces limit on a single entry length - 3072 bytes. by space. QubesDB enforces limit on a single entry length - 3072 bytes.
Possible options for a single rule: Possible options for a single rule:
- `action`, values: `accept`, `drop`; this is present in every rule - `action`, values: `accept`, `drop`; this is present in every rule
- `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24` - `dst4`, value: destination IPv4 address with a mask; for example: `192.168.0.0/24`
- `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3` - `dst6`, value: destination IPv6 address with a mask; for example: `2000::/3`
- `dsthost`, value: DNS hostname of destination host - `dsthost`, value: DNS hostname of destination host
- `proto`, values: `tcp`, `udp`, `icmp` - `proto`, values: `tcp`, `udp`, `icmp`
- `specialtarget`, value: One of predefined target, currently defined values: - `specialtarget`, value: One of predefined target, currently defined values:
- `dns` - such option should match DNS traffic to default DNS server (but - `dns` - such option should match DNS traffic to default DNS server (but
not any DNS server), on both TCP and UDP not any DNS server), on both TCP and UDP
- `dstports`, value: destination ports range separated with `-`, valid only - `dstports`, value: destination ports range separated with `-`, valid only
together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80` together with `proto=tcp` or `proto=udp`; for example `1-1024`, `80-80`
- `icmptype`, value: numeric (decimal) icmp message type, for example `8` for - `icmptype`, value: numeric (decimal) icmp message type, for example `8` for
echo request, valid only together with `proto=icmp` echo request, valid only together with `proto=icmp`
- `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering - `dpi`, value: Deep Packet Inspection protocol (like: HTTP, SSL, SMB, SSH, SMTP) or the default 'NO' as no DPI, only packet filtering
Options must appear in the rule in the order listed above. Duplicated options Options must appear in the rule in the order listed above. Duplicated options
are forbidden. are forbidden.
@ -117,48 +117,46 @@ Example valid rules:
- `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP - `action=drop proto=tcp specialtarget=dns` - drop DNS queries sent using TCP
- `action=drop` - `action=drop`
### Keys set by VM for passing info to dom0 ### ### Keys set by VM for passing info to dom0
- `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman; - `memory/meminfo` (**xenstore**) - used memory (updated by qubes-meminfo-writer), input information for qmemman;
- Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux. - Qubes 3.x format: 6 lines (EOL encoded as `\n`), each in format "FIELD: VALUE kB"; fields: `MemTotal`, `MemFree`, `Buffers`, `Cached`, `SwapTotal`, `SwapFree`; meaning the same as in `/proc/meminfo` in Linux.
- Qubes 4.0+ format: used memory size in the VM, in kbytes - 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: - `/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) - `desc` - device description (ASCII text)
- `size` - device size in bytes - `size` - device size in bytes
- `mode` - default connection mode; `r` for read-only, `w` for read-write - `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: - `/qubes-usb-devices` - list of USB devices exposed by this VM, each device (subdirectory) should contain:
- `desc` - device description (ASCII text) - `desc` - device description (ASCII text)
- `usb-ver` - USB version (1, 2 or 3) - `usb-ver` - USB version (1, 2 or 3)
Qubes RPC ## Qubes RPC
---------
Services called by dom0 to provide some VM configuration: Services called by dom0 to provide some VM configuration:
- `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.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.WaitForSession` - called to wait for full VM startup
- `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here - `qubes.GetAppmenus` - receive appmenus from given VM (template); TODO: describe format here
- `qubes.GetImageRGBA` - receive image/application icon. Protocol: - `qubes.GetImageRGBA` - receive image/application icon. Protocol:
1. Caller sends name of requested icon. This can be one of: 1. Caller sends name of requested icon. This can be one of:
* `xdgicon:NAME` - search for NAME in standard icons theme * `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:-` * `-` - get icon data from stdin (the caller), can be prefixed with format name, for example `png:-`
* file name * file name
2. The service responds with image dimensions: width and height as 2. The service responds with image dimensions: width and height as
decimal numbers, separated with space and with EOL marker at the and; then decimal numbers, separated with space and with EOL marker at the and; then
image data in RGBA format (32 bits per pixel) 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 triggered manually from dom0 by calling `qvm-sync-clock`). The service
receives one line at stdin - time in format of `date -u -Iseconds`, for receives one line at stdin - time in format of `date -u -Iseconds`, for
example `2015-07-31T16:10:43+0000`. 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` GUI mode. The service receives a single word on stdin - either `FULLSCREEN`
or `SEAMLESS` 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`, Name of disk image is passed on standard input (`root`, `private`, `volatile`,
or other). This is used starting with Qubes 4.0. or other). This is used starting with Qubes 4.0.
Other Qrexec services installed by default: Other Qrexec services installed by default:
- `qubes.Backup` - store Qubes backup. The service receives location chosen by - `qubes.Backup` - store Qubes backup. The service receives location chosen by
@ -193,19 +191,19 @@ Other Qrexec services installed by default:
can send icon for the same window multiple times to replace previous one (for can send icon for the same window multiple times to replace previous one (for
example for animated icons) example for animated icons)
- `qubes.VMShell` - call any command in the VM; the command(s) is passed one per line - `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 - `qubes.VMExec` - call any command in the VM, without using shell, the command
needs to be passed as argument and encoded as follows: needs to be passed as argument and encoded as follows:
- the executable name and arguments are separated by `+` - the executable name and arguments are separated by `+`
- everything except alphanumeric characters, `.` and `_` needs to be - everything except alphanumeric characters, `.` and `_` needs to be
escaped escaped
- bytes are escaped as `-HH` (where `HH` is hex code, capital letters only) - bytes are escaped as `-HH` (where `HH` is hex code, capital letters only)
- `-` itself can be escaped as `--` - `-` itself can be escaped as `--`
- example: to run `ls -a /home/user`, use - example: to run `ls -a /home/user`, use
`qubes.VMExec+ls+--a+-2Fhome-2Fuser` `qubes.VMExec+ls+--a+-2Fhome-2Fuser`
- `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM - `qubes.VMExecGUI` - a variant of `qubes.VMExec` that waits for full VM
startup first startup first
Services called in GuiVM: Services called in GuiVM:
- `policy.Ask`, `policy.Notify` - confirmation prompt and notifications for - `policy.Ask`, `policy.Notify` - confirmation prompt and notifications for
@ -224,7 +222,6 @@ abstraction. This will change in the future. Those tools are:
Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that. Additionally, automatic tests extensively run various commands directly in VMs. We do not plan to change that.
GUI protocol ## GUI protocol
------------
GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call. GUI initialization includes passing the whole screen dimensions from dom0 to VM. This will most likely be overwritten by qubes.SetMonitorLayout Qubes RPC call.

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

@ -1,15 +1,16 @@
--- ---
lang: en
layout: doc layout: doc
title: Windows Debugging
permalink: /doc/windows-debugging/ permalink: /doc/windows-debugging/
redirect_from: redirect_from:
- /en/doc/windows-debugging/ - /en/doc/windows-debugging/
- /doc/WindowsDebugging/ - /doc/WindowsDebugging/
- /wiki/WindowsDebugging/ - /wiki/WindowsDebugging/
ref: 50
title: Windows Debugging
--- ---
Debugging Windows HVMs # Debugging Windows HVMs
======================
Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs. Debugging Windows code can be tricky in a virtualized environment. The guide below assumes Xen hypervisor and Windows 7 VMs.
@ -17,22 +18,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. 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**. - 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. - 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` - 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 connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below: - To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
```bash
#!/bin/sh #!/bin/sh
id1=$(xl domid "$1-dm") id1=$(xl domid "$1-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
echo $tty1 echo $tty1
```
Pass it a running VM name and it will output the corresponding pty name. Pass it a running VM name and it will output the corresponding pty name.
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that: - To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
```bash
#!/bin/sh #!/bin/sh
id1=$(xl domid "$1-dm") id1=$(xl domid "$1-dm")
@ -40,14 +44,15 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty) tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty) tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
socat $tty1,raw $tty2,raw socat $tty1,raw $tty2,raw
```
...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0. ...but there is a catch. Xen seems to process the traffic that goes through serial ports and changes all **0x0a** bytes into **0x0d, 0x0a** pairs (newline conversion). I didn't find a way to turn that off (setting ptys to raw mode didn't change anything) and it's not mentioned anywhere on the Internet, so maybe it's something on my system. If the above script works for you then you don't need anything more in dom0.
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port. - On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
- On the *host* system, install [WinDbg](https://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port. - On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- Reboot the *target* VM. - Reboot the *target* VM.
- Run the above shell script in dom0. - Run the above shell script in dom0.
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that: - If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
~~~ ~~~
Opened \\.\com1 Opened \\.\com1
@ -55,7 +60,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 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. Kernel Debugger connection established.
Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols 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. ... Retry sending the same data packet for 64 times.
The transport connection between host kernel debugger and target Windows seems lost. 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. please try resync with target, recycle the host debugger, or reboot the target Windows.
@ -73,6 +78,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works: ...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
```c
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <fcntl.h> #include <fcntl.h>
@ -85,11 +91,11 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
{ {
static int count = 0; static int count = 0;
static unsigned char buf[17] = {0}; static unsigned char buf[17] = {0};
// relay to ouptput port // relay to ouptput port
write(fd2, &c, 1); write(fd2, &c, 1);
fprintf(stderr, "%c", mark); fprintf(stderr, "%c", mark);
/* dump all data going over the line /* dump all data going over the line
if (count == 0) if (count == 0)
fprintf(stderr, "%c", mark); fprintf(stderr, "%c", mark);
@ -112,13 +118,13 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
unsigned char c = 0; unsigned char c = 0;
struct termios tio; struct termios tio;
ssize_t size; ssize_t size;
if (argc < 3) if (argc < 3)
{ {
fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]); fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
return EINVAL; return EINVAL;
} }
fd1 = open(argv[1], O_RDONLY | O_NOCTTY); fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
if (fd1 <= 0) if (fd1 <= 0)
{ {
@ -182,6 +188,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
close(fd2); close(fd2);
return 0; return 0;
} }
```
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like: > This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
> >
@ -202,7 +209,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 > 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. > Kernel Debugger connection established.
> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols > 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 > Windows 7 Kernel Version 7601 MP (1 procs) Free x64
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532 > Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
> Machine Name: > Machine Name:
@ -214,7 +221,7 @@ Things get complicated if you need to perform kernel debugging or troubleshoot p
There are two main issues to be adopted to get all things to work in the R4.0. There are two main issues to be adopted to get all things to work in the R4.0.
## Add a virtual serial port ## ## Add a virtual serial port
Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console. Qemu in the stub domain with virtual serial port added in a recommended way (```<serial type="pty"/>```) fails to start (Could not open '/dev/hvc1': No such device). It seems like a lack of multiple xen consoles support/configuration. The only way that I have found is to attach serial port explicitly to the available console.
@ -228,15 +235,17 @@ $ gunzip stubdom-linux-rootfs.gz
$ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs $ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
$ rm stubdom-linux-rootfs $ rm stubdom-linux-rootfs
``` ```
2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line. 2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
3. Apply changes: 3. Apply changes:
```shell_session ```shell_session
$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs $ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot $ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
``` ```
## Connect two consoles ## ## Connect two consoles
Run the following script: Run the following script:

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

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

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

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

198
developer/general/gsoc.md
View File

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

7
developer/general/join.md
View File

@ -1,7 +1,9 @@
--- ---
lang: en
layout: sidebar layout: sidebar
title: Join
permalink: /join/ permalink: /join/
ref: 26
title: Join
--- ---
Joining the Qubes OS Team Joining the Qubes OS Team
@ -9,5 +11,4 @@ Joining the Qubes OS Team
The Qubes OS Project does not currently have any open positions. The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available. This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/). In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

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

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

95
developer/general/style-guide.md
View File

@ -1,96 +1,7 @@
--- ---
lang: en
layout: doc layout: doc
title: Style-guide
permalink: /doc/style-guide/ permalink: /doc/style-guide/
ref: 27
title: Style-guide
--- ---
Style Guide
===========
## Fonts
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a user's desktop environment of choice.
<div class="styleguide">
{% for font in site.data.styleguide.fonts %}
<div class="row">
<div class="col-lg-6 col-md-6 focus">
<div class="font {{font.class}}">Custom Qubes Font</div>
</div>
<div class="col-lg-6 col-md-6">
<strong>Family:</strong> {{font.family}}<br>
</div>
</div>
{% endfor %}
</div>
---
## Colors
The following **grayscale** colors are currently used on the Qubes website and documentation, and they will eventually match colors within the OS itself.
<div class="styleguide">
{% for color in site.data.styleguide.colors %}
{% if color.type == "grayscale" %}
<div class="swatch more-bottom more-right">
<div class="color add-bottom bg-{{color.class}}"></div>
<strong class="add-bottom">{{color.name}}</strong>
<code>#{{color.hex | downcase}}</code>
</div>
{% endif %}
{% endfor %}
</div>
The following **colors** are currently being used on the Qubes website and documentation, and they will eventually match the colors within the OS itself!
<div class="styleguide">
{% for color in site.data.styleguide.colors %}
{% if color.type == "colors" %}
<div class="swatch more-bottom more-right">
<div class="color add-bottom bg-{{color.class}}"></div>
<strong class="add-bottom">{{color.name}}</strong>
<code>#{{color.hex | downcase}}</code>
</div>
{% endif %}
{% endfor %}
</div>
---
## Icons
Currently, all the icons on the Qubes-OS.org website are generated using [FontAwesome](https://fontawesome.com/).
*As more custom work is done to generate icons for the operating system itself, they will be added here!*
---
## Logos
The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website.
The artwork is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
The code is licensed under GNU GPLv2.
GPLv2 and the source code can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
<div class="styleguide">
{% for logo in site.data.styleguide.logos %}
{% for version in logo.versions %}
<div class="row more-bottom">
<div class="col-lg-4 col-md-4">
<div class="focus">
<img class="logo" src="{{version.path}}{{logo.image}}">
</div>
</div>
<div class="col-lg-8 col-md-8">
<p>
<strong>Image:</strong> {{logo.image}}<br>
<strong>Size:</strong> {{version.size}}<br>
<strong>Format:</strong> {{version.format}}<br>
<strong>Download:</strong> <a href="{{version.path}}{{logo.image}}" target="_blank">this image</a>
</p>
</div>
</div>
{% endfor %}
{% endfor %}
</div>

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

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

56
developer/releases/1.0/release-notes.md
View File

@ -1,56 +0,0 @@
---
layout: doc
title: Qubes R1.0 Release Notes
permalink: /doc/releases/1.0/release-notes/
redirect_from:
- /en/doc/releases/1.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
------------
- 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.
- 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
~~~
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.
Downloads
---------
See [Qubes Downloads](/doc/QubesDownloads/).
Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/).
Upgrading
---------
### From Qubes 1.0-rc1
If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). The easiest way for doing this is to click on the Update Button in the Qubes Manger -- one click when you selected Dom0, and one click for each of your template VM (by default there is just one template).
### From Qubes 1.0 Beta 3
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
~~~

52
developer/releases/1_0/release-notes.md Normal file
View File

@ -0,0 +1,52 @@
---
lang: en
layout: doc
permalink: /doc/releases/1.0/release-notes/
redirect_from:
- /en/doc/releases/1.0/release-notes/
ref: 18
title: 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
- 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.
- 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
~~~
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.
## Downloads
See [Qubes Downloads](/doc/QubesDownloads/).
## Installation instructions
See [Installation Guide](/doc/installation-guide/).
## Upgrading
### From Qubes 1.0-rc1
If you're already running Qubes 1.0-rc1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). The easiest way for doing this is to click on the Update Button in the Qubes Manger -- one click when you selected Dom0, and one click for each of your template VM (by default there is just one template).
### From Qubes 1.0 Beta 3
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
~~~

34
developer/releases/2.0/release-notes.md → developer/releases/2_0/release-notes.md
View File

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

23
developer/releases/3.0/release-notes.md → developer/releases/3_0/release-notes.md
View File

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

4
developer/releases/3.0/schedule.md → developer/releases/3_0/schedule.md
View File

@ -1,9 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes R3.0 Release Schedule
permalink: /doc/releases/3.0/schedule/ permalink: /doc/releases/3.0/schedule/
redirect_from: redirect_from:
- /en/doc/releases/3.0/schedule/ - /en/doc/releases/3.0/schedule/
ref: 20
title: Qubes R3.0 Release Schedule
--- ---
Qubes R3.0 Release Schedule Qubes R3.0 Release Schedule

22
developer/releases/3.1/release-notes.md → developer/releases/3_1/release-notes.md
View File

@ -1,14 +1,14 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes R3.1 release notes
permalink: /doc/releases/3.1/release-notes/ permalink: /doc/releases/3.1/release-notes/
ref: 16
title: Qubes R3.1 release notes
--- ---
Qubes R3.1 release notes # Qubes R3.1 release notes
========================
New features since 3.0 ## New features since 3.0
----------------------
* Management Stack based of Salt Stack in dom0 - [documentation][salt-doc] * Management Stack based of Salt Stack in dom0 - [documentation][salt-doc]
* Out of the box Whonix setup * Out of the box Whonix setup
@ -23,8 +23,7 @@ New features since 3.0
You can get detailed description in [completed github issues][github-release-notes] You can get detailed description in [completed github issues][github-release-notes]
Known issues ## Known issues
------------
* Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more) * Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more)
@ -38,18 +37,15 @@ Known issues
It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems. It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
Downloads ## Downloads
---------
See [Qubes Downloads](/downloads/). See [Qubes Downloads](/downloads/).
Installation instructions ## Installation instructions
-------------------------
See [Installation Guide](/doc/installation-guide/). See [Installation Guide](/doc/installation-guide/).
Upgrading ## Upgrading
---------
### From R3.0 ### From R3.0

6
developer/releases/3.1/schedule.md → developer/releases/3_1/schedule.md
View File

@ -1,9 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes R3.1 Release Schedule
permalink: /doc/releases/3.1/schedule/ permalink: /doc/releases/3.1/schedule/
redirect_from: redirect_from:
- /en/doc/releases/3.1/schedule/ - /en/doc/releases/3.1/schedule/
ref: 17
title: Qubes R3.1 Release Schedule
--- ---
Qubes R3.1 Release Schedule Qubes R3.1 Release Schedule
@ -18,4 +20,4 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
| 12 Jan 2016 | 3.1-rc2 release | | 12 Jan 2016 | 3.1-rc2 release |
| 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 | | 26 Jan 2016 | decide whether 3.1-rc2 is the final 3.1 |
| 9 Feb 2016 | current-testing freeze before 3.1-rc3 | | 9 Feb 2016 | current-testing freeze before 3.1-rc3 |
| <strike>16 Feb 2016</strike><br/>23 Feb 2016 | 3.1-rc3 release | | ~~16 Feb 2016~~ <br/> 23 Feb 2016 | 3.1-rc3 release |

22
developer/releases/3.2/release-notes.md → developer/releases/3_2/release-notes.md
View File

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

10
developer/releases/3.2/schedule.md → developer/releases/3_2/schedule.md
View File

@ -1,9 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes R3.2 Release Schedule
permalink: /doc/releases/3.2/schedule/ permalink: /doc/releases/3.2/schedule/
redirect_from: redirect_from:
- /en/doc/releases/3.2/schedule/ - /en/doc/releases/3.2/schedule/
ref: 22
title: Qubes R3.2 Release Schedule
--- ---
Qubes R3.2 Release Schedule Qubes R3.2 Release Schedule
@ -15,9 +17,9 @@ This schedule is based on [Version Scheme](/doc/version-scheme/#release-schedule
| -----------:| --------------------------------------- | | -----------:| --------------------------------------- |
| 18 Jun 2016 | 3.2-rc1 release | | 18 Jun 2016 | 3.2-rc1 release |
| 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 | | 2 Jul 2016 | decide whether 3.2-rc1 is the final 3.2 |
| <strike>16 Jul 2016</strike><br/>20 Jul 2016 | current-testing freeze before 3.2-rc2 | | ~~16 Jul 2016~~ <br/> 20 Jul 2016 | current-testing freeze before 3.2-rc2 |
| <strike>23 Jul 2016</strike><br/>27 Jul 2016 | 3.2-rc2 release | | ~~23 Jul 2016~~ <br/> 27 Jul 2016 | 3.2-rc2 release |
| <strike> 5 Aug 2016</strike><br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 | | ~~5 Aug 2016~~ <br/> 9 Aug 2016 | decide whether 3.2-rc2 is the final 3.2 |
| 24 Aug 2016 | current-testing freeze before 3.2-rc3 | | 24 Aug 2016 | current-testing freeze before 3.2-rc3 |
| 31 Aug 2016 | 3.2-rc3 release | | 31 Aug 2016 | 3.2-rc3 release |
| 29 Sep 2016 | 3.2 release | | 29 Sep 2016 | 3.2 release |

21
developer/releases/4.0/release-notes.md → developer/releases/4_0/release-notes.md
View File

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

14
developer/releases/4.0/schedule.md → developer/releases/4_0/schedule.md
View File

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

17
developer/releases/notes.md
View File

@ -1,16 +1,17 @@
--- ---
lang: en
layout: doc layout: doc
title: Release Notes
permalink: /doc/releases/notes/ permalink: /doc/releases/notes/
ref: 13
title: Release Notes
--- ---
Release Notes Release Notes
============= =============
* [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/) * [Qubes R1.0 release notes](/doc/releases/1.0/release-notes/)
* [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/) * [Qubes R2.0 release notes](/doc/releases/2.0/release-notes/)
* [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/) * [Qubes R3.0 release notes](/doc/releases/3.0/release-notes/)
* [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/) * [Qubes R3.1 release notes](/doc/releases/3.1/release-notes/)
* [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/) * [Qubes R3.2 release notes](/doc/releases/3.2/release-notes/)
* [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/) * [Qubes R4.0 release notes](/doc/releases/4.0/release-notes/)

13
developer/releases/schedules.md
View File

@ -1,14 +1,15 @@
--- ---
lang: en
layout: doc layout: doc
title: Release Schedules
permalink: /doc/releases/schedules/ permalink: /doc/releases/schedules/
ref: 15
title: Release Schedules
--- ---
Release Schedules Release Schedules
================= =================
* [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/) * [Qubes R3.0 release schedule](/doc/releases/3.0/schedule/)
* [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/) * [Qubes R3.1 release schedule](/doc/releases/3.1/schedule/)
* [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/) * [Qubes R3.2 release schedule](/doc/releases/3.2/schedule/)
* [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/) * [Qubes R4.0 release schedule](/doc/releases/4.0/schedule/)

7
developer/releases/todo.md
View File

@ -1,9 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Release Checklist
permalink: /doc/releases/todo/ permalink: /doc/releases/todo/
redirect_from: redirect_from:
- /en/doc/releases/todo/ - /en/doc/releases/todo/
ref: 14
title: Release Checklist
--- ---
Release Checklist Release Checklist
@ -13,6 +15,7 @@ Release Checklist
On -rc1 On -rc1
------- -------
* write schedule * write schedule
* create package repositories (linux-yum, linux-deb) * create package repositories (linux-yum, linux-deb)
* update repository definition (core-agent-linux, installer-qubes-os/qubes-release) * update repository definition (core-agent-linux, installer-qubes-os/qubes-release)
@ -24,6 +27,7 @@ On -rc1
On subsequent -rc On subsequent -rc
----------------- -----------------
* push packages to `current` * push packages to `current`
* update release notes * update release notes
* build ISO and push to mirrors * build ISO and push to mirrors
@ -31,6 +35,7 @@ On subsequent -rc
On final release On final release
---------------- ----------------
* push packages to `current` * push packages to `current`
* finish release notes * finish release notes
* update InstallationInstructions * update InstallationInstructions

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

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

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

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Dom0 Secure Updates
permalink: /doc/dom0-secure-updates/ permalink: /doc/dom0-secure-updates/
redirect_from: redirect_from:
- /en/doc/dom0-secure-updates/ - /en/doc/dom0-secure-updates/
- /doc/Dom0SecureUpdates/ - /doc/Dom0SecureUpdates/
- /wiki/Dom0SecureUpdates/ - /wiki/Dom0SecureUpdates/
ref: 43
title: Dom0 Secure Updates
--- ---
Qubes Dom0 secure update procedure Qubes Dom0 secure update procedure
@ -18,9 +20,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: However, we anticipate some other situations when updating Dom0 software might be required:
- Updating drivers/libs for new hardware support - Updating drivers/libs for new hardware support
- Correcting non-security related bugs (e.g. new buttons for qubes manager) - Correcting non-security related bugs (e.g. new buttons for qubes manager)
- Adding new features (e.g. GUI backup tool) - Adding new features (e.g. GUI backup tool)
Problems with traditional network-based update mechanisms Problems with traditional network-based update mechanisms
--------------------------------------------------------- ---------------------------------------------------------

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

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: DVMimpl
permalink: /doc/dvm-impl/ permalink: /doc/dvm-impl/
redirect_from: redirect_from:
- /en/doc/dvm-impl/ - /en/doc/dvm-impl/
- /doc/DVMimpl/ - /doc/DVMimpl/
- /wiki/DVMimpl/ - /wiki/DVMimpl/
ref: 34
title: DVMimpl
--- ---
DisposableVM implementation in Qubes DisposableVM implementation in Qubes
@ -20,19 +22,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: 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` 1. APPVM is started by `qvm-start`
2. xenstore key `/local/domain/appvm_domain_id/qubes_save_request` is created 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 3. if prerun script was specified, copy it to `qubes_save_script` xenstore key
4. wait for the `qubes_used_mem` key to appear 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 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. 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 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 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. 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 7. APPVM private image is detached
8. the domain is saved via `xl save` 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 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). 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 +43,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: 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 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` 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. 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. 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`) 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. 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. The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.

12
developer/services/qfilecopy.md
View File

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Qfilecopy
permalink: /doc/qfilecopy/ permalink: /doc/qfilecopy/
redirect_from: redirect_from:
- /en/doc/qfilecopy/ - /en/doc/qfilecopy/
- /doc/Qfilecopy/ - /doc/Qfilecopy/
- /wiki/Qfilecopy/ - /wiki/Qfilecopy/
ref: 35
title: Qfilecopy
--- ---
InterVM file copy design InterVM file copy design
@ -13,15 +15,15 @@ InterVM file copy design
There are two cases when we need a mechanism to copy files between VMs: 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 - "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. - 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. 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: This has the following disadvantages:
- performance - dom0 has to prepare and attach/detach block devices, which is slow because of hotplug scripts involvement. - 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. - 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. 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.

39
developer/services/qfileexchgd.md
View File

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Qfileexchgd
permalink: /doc/qfileexchgd/ permalink: /doc/qfileexchgd/
redirect_from: redirect_from:
- /en/doc/qfileexchgd/ - /en/doc/qfileexchgd/
- /doc/Qfileexchgd/ - /doc/Qfileexchgd/
- /wiki/Qfileexchgd/ - /wiki/Qfileexchgd/
ref: 40
title: Qfileexchgd
--- ---
**This mechanism is obsolete as of Qubes Beta 1!** **This mechanism is obsolete as of Qubes Beta 1!**
@ -21,37 +23,36 @@ Overview
*qfilexchgd* is a dom0 daemon responsible for managing exchange of block devices ("virtual pendrives") between VMs. It is used for *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 files between AppVMs
- copying a single file between an AppVM and a DisposableVM - 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 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: *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 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 a change in `/local/domain/domid/device/qpen` key - VMs write to this key to request service from *qfilexchgd*
Copying files between AppVMs 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. 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. 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. 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. 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 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. 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. 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) 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, 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` 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 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. 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.
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.

53
developer/services/qmemman.md
View File

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Qmemman
permalink: /doc/qmemman/ permalink: /doc/qmemman/
redirect_from: redirect_from:
- /en/doc/qmemman/ - /en/doc/qmemman/
- /doc/Qmemman/ - /doc/Qmemman/
- /wiki/Qmemman/ - /wiki/Qmemman/
ref: 41
title: Qmemman
--- ---
qmemman, Qubes memory manager qmemman, Qubes memory manager
@ -18,8 +20,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: 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 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 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). 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 +29,24 @@ Similarly, when there is need for Xen free memory (for instance, in order to cre
To sum up, *qmemman* pros and cons. Pros: To sum up, *qmemman* pros and cons. Pros:
- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand - 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 - works well in practice, with less than 1% CPU consumption in the idle case
- simple, concise implementation - simple, concise implementation
Cons: Cons:
- the algorithm to calculate the memory requirement for a domain is necessarily simple, and may not closely reflect reality - 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 - *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 - it takes more time to obtain free Xen memory, as all participating domains need to instructed to yield memory
Interface Interface
--------- ---------
*qmemman* listens for the following events: *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 - 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. - 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. - 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 Algorithms basics
----------------- -----------------
@ -53,28 +55,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: 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 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 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` 3. if TOTAL\_MEMORY \> TOTAL\_PREFMEM, then redistribute TOTAL\_MEMORY across all domains proportionally to their `prefmem`
4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then 4. if TOTAL\_MEMORY \< TOTAL\_PREFMEM, then
1. for all domains whose `prefmem` is less than actual memory, shrink them to their `prefmem` 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` 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: 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) - 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 - 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. 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: 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` 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. 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 3. shrink donors, proportionally to their `prefmem`, so that X MB should become free
4. wait BALOON\_DELAY (0.1s) 4. wait BALOON\_DELAY (0.1s)
5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error). 5. if some domain have not given back any memory, remove it from the donors list, and go to step 2, unless we already did MAX\_TRIES (20) iterations (then return error).
Notes Notes
----- -----

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

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

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

@ -1,7 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: "Qrexec: Socket-based services"
permalink: /doc/qrexec-socket-services/ permalink: /doc/qrexec-socket-services/
ref: 42
title: 'Qrexec: Socket-based services'
--- ---
# Qrexec: Socket-based services # Qrexec: Socket-based services
@ -20,11 +22,15 @@ If the file is a Unix socket, qrexec will try to connect to it.
Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`. Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after `QUBESRPC`.
When running in a VM, this is: When running in a VM, this is:
```
<service_name> <source>\0 <service_name> <source>\0
```
When running in dom0, it is: When running in dom0, it is:
```
<service_name> <source> <target_type> <target>\0 <service_name> <source> <target_type> <target>\0
```
(The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`). (The target type can be `name`, in which case target is a domain name, or `keyword`, in which the target is a keyword like `@dispvm`).

5
developer/services/qrexec.md
View File

@ -1,16 +1,17 @@
--- ---
lang: en
layout: doc layout: doc
title: "Qrexec: secure communication across domains"
permalink: /doc/qrexec/ permalink: /doc/qrexec/
redirect_from: redirect_from:
- /en/doc/qrexec3/ - /en/doc/qrexec3/
- /doc/Qrexec3/ - /doc/Qrexec3/
- /doc/qrexec3/ - /doc/qrexec3/
- /wiki/Qrexec3/ - /wiki/Qrexec3/
- /doc/qrexec/
- /en/doc/qrexec/ - /en/doc/qrexec/
- /doc/Qrexec/ - /doc/Qrexec/
- /wiki/Qrexec/ - /wiki/Qrexec/
ref: 37
title: 'Qrexec: secure communication across domains'
--- ---
# Qrexec: secure communication across domains # Qrexec: secure communication across domains

80
developer/services/qrexec2.md
View File

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

65
developer/system/architecture.md
View File

@ -1,12 +1,14 @@
--- ---
lang: en
layout: doc layout: doc
title: Architecture
permalink: /doc/architecture/ permalink: /doc/architecture/
redirect_from: redirect_from:
- /doc/qubes-architecture/ - /doc/qubes-architecture/
- /en/doc/qubes-architecture/ - /en/doc/qubes-architecture/
- /doc/QubesArchitecture/ - /doc/QubesArchitecture/
- /wiki/QubesArchitecture/ - /wiki/QubesArchitecture/
ref: 56
title: Architecture
--- ---
Qubes Architecture Overview Qubes Architecture Overview
@ -18,25 +20,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. Qubes lets the user define many security domains, which are implemented as lightweight Virtual Machines (VMs), or “AppVMs.” For example, the user can have “personal,” “work,” “shopping,” “bank,” and “random” AppVMs and can use the applications within those VMs just as if they were executing on the local machine. At the same time, however, these applications are well isolated from each other. Qubes also supports secure copy-and-paste and file sharing between the AppVMs, of course.
Key Architecture features Key Architecture features
------------------------- -------------------------
- Based on a secure bare-metal hypervisor (Xen) - Based on a secure bare-metal hypervisor (Xen)
- Networking code sand-boxed in an unprivileged VM (using IOMMU/VT-d) - 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) - USB stacks and drivers sand-boxed in an unprivileged VM (currently experimental feature)
- No networking code in the privileged domain (dom0) - No networking code in the privileged domain (dom0)
- All user applications run in “AppVMs,” lightweight VMs based on Linux - All user applications run in “AppVMs,” lightweight VMs based on Linux
- Centralized updates of all AppVMs based on the same template - Centralized updates of all AppVMs based on the same template
- Qubes GUI virtualization presents applications as if they were running locally - Qubes GUI virtualization presents applications as if they were running locally
- Qubes GUI provides isolation between apps sharing the same desktop - Qubes GUI provides isolation between apps sharing the same desktop
- Secure system boot based (optional) - 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. (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. Please note that this document is for historical interest only.
For the latest information, please see the rest of the [System Documentation](/doc/#system).) For the latest information, please see the rest of the [System Documentation](/doc/#system).)
Qubes Core Stack Qubes Core Stack
---------------- ----------------
@ -45,26 +45,26 @@ the glue that connects all the other components together, and which allows users
and admins to interact with and configure the system. The other components of and admins to interact with and configure the system. The other components of
the Qubes system include: the Qubes system include:
- VM-located core agents (implementing e.g. qrexec endpoints used by various - VM-located core agents (implementing e.g. qrexec endpoints used by various
Qubes services) Qubes services)
- VM-customizations (making the VMs lightweight and working well with seamless - VM-customizations (making the VMs lightweight and working well with seamless
GUI virtualization) GUI virtualization)
- Qubes GUI virtualization (the protocol, VM-located agents, and daemons - Qubes GUI virtualization (the protocol, VM-located agents, and daemons
located in the GUI domain which, for now, happens to be the same as dom0), located in the GUI domain which, for now, happens to be the same as dom0),
- GUI domain customizations (Desktop Environment customizations, decoration - GUI domain customizations (Desktop Environment customizations, decoration
coloring plugin, etc) coloring plugin, etc)
- The AdminVM distribution (various customizations, special services, such as - The AdminVM distribution (various customizations, special services, such as
for receiving and verifying updates, in the future: custom distro) for receiving and verifying updates, in the future: custom distro)
- The Xen hypervisor (with a bunch of customization patches, occasional - The Xen hypervisor (with a bunch of customization patches, occasional
hardening) or - in the future - some other virtualising or containerizing hardening) or - in the future - some other virtualising or containerizing
software or technology software or technology
- Multiple "Qubes Apps" (various services built on top of Qubes qrexec - Multiple "Qubes Apps" (various services built on top of Qubes qrexec
infrastructure, such as: trusted PDF and Image converters, Split GPG, safe infrastructure, such as: trusted PDF and Image converters, Split GPG, safe
USB proxies for HID devices, USB proxy for offering USB devices (exposed via USB proxies for HID devices, USB proxy for offering USB devices (exposed via
qvm-usb), Yubikey support, USB Armory support, etc) qvm-usb), Yubikey support, USB Armory support, etc)
- Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used - Various ready-to-use templates (e.g. Debian-, Whonix-based), which are used
to create actual VMs, i.e. provide the root filesystem to the VMs to create actual VMs, i.e. provide the root filesystem to the VMs
- Salt Stack integration - Salt Stack integration
And all these components are "glued together" by the Qubes Core Stack. And all these components are "glued together" by the Qubes Core Stack.
@ -73,4 +73,3 @@ And all these components are "glued together" by the Qubes Core Stack.
This diagram illustrates the location of all these components in the overall This diagram illustrates the location of all these components in the overall
system architecture. Unlike the other Qubes architecture diagram above, this one system architecture. Unlike the other Qubes architecture diagram above, this one
takes an AppVM-centric approach. takes an AppVM-centric approach.

29
developer/system/audio.md
View File

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

230
developer/system/gui.md
View File

@ -1,12 +1,14 @@
--- ---
lang: en
layout: doc layout: doc
title: GUI
permalink: /doc/gui/ permalink: /doc/gui/
redirect_from: redirect_from:
- /en/doc/gui/ - /en/doc/gui/
- /en/doc/gui-docs/ - /en/doc/gui-docs/
- /doc/GUIdocs/ - /doc/GUIdocs/
- /wiki/GUIdocs/ - /wiki/GUIdocs/
ref: 61
title: GUI
--- ---
Qubes GUI protocol Qubes GUI protocol
@ -17,23 +19,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: 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 - *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) - *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: The main responsibilities of *qubes_gui* are:
- call XCompositeRedirectSubwindows on the root window, so that each window has its own composition buffer - 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 - 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 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 - receive information about window size/position change, apply them to the local window
The main responsibilities of *qubes_guid* are: 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* - 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 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 - 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 - 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. 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. 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 +43,30 @@ AppVM has no way to get information on keystrokes fed to other AppVMs (e.g. XTES
Window content updates implementation Window content updates implementation
------------------------------------- -------------------------------------
Typical remote desktop applications, like *vnc*, pass information on all changed window content in-band (say, over tcp). 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. 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* 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 - 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 - 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. 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. There is no supported way (e.g. Xorg extension) to do this zero-copy style.
The following method is used in Qubes: 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. - 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 - *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* - 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. - 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. Therefore, rogue AppVM cannot gain anything by passing crafted mnfs in the `MFNDUMP` message.
To sum up, this solution has the following benefits: To sum up, this solution has the following benefits:
- window updates at DRAM speed - window updates at DRAM speed
- no changes to Xorg code - no changes to Xorg code
- minimal size of the supporting code - minimal size of the supporting code
![gui.png](/attachment/wiki/GUIdocs/gui.png) ![gui.png](/attachment/wiki/GUIdocs/gui.png)
@ -78,14 +80,14 @@ In Qubes, a custom window decorator is used that paints a colourful frame (the c
Clipboard sharing implementation 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: Therefore, the following mechanism is used:
- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0. - 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. - 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. - 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. This action is fully controlled by the user, it cannot be triggered/forced by any AppVM.
*qubes_gui* and *qubes_guid* code notes *qubes_gui* and *qubes_guid* code notes
@ -93,20 +95,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: 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 local X server
- messages from the vchan connecting to the remote party - 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. 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. 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. Include these files when reporting a bug.
AppVM -> dom0 messages 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. 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). 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 +117,8 @@ Window manager hints and flags are described in the [Extended Window Manager Hin
Each message starts with the following header: Each message starts with the following header:
~~~ ```c
struct msghdr { struct msghdr {
uint32_t type; uint32_t type;
uint32_t window; uint32_t window;
/* This field is intended for use by gui_agents to skip unknown /* This field is intended for use by gui_agents to skip unknown
@ -126,7 +128,7 @@ struct msghdr {
* whatever it wants! */ * whatever it wants! */
uint32_t untrusted_len; uint32_t untrusted_len;
}; };
~~~ ```
This header is followed by message-specific data: This header is followed by message-specific data:
@ -164,9 +166,9 @@ struct msg_create {
<tr> <tr>
<td>MSG_MAP</td> <td>MSG_MAP</td>
<td><pre> <td><pre>
struct msg_map_info { struct msg_map_info {
uint32_t transient_for; uint32_t transient_for;
uint32_t override_redirect; uint32_t override_redirect;
}; };
</pre></td> </pre></td>
<td>Map a window with given parameters</td> <td>Map a window with given parameters</td>
@ -179,12 +181,12 @@ struct msg_map_info {
<tr> <tr>
<td>MSG_CONFIGURE</td> <td>MSG_CONFIGURE</td>
<td><pre> <td><pre>
struct msg_configure { struct msg_configure {
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t width; uint32_t width;
uint32_t height; uint32_t height;
uint32_t override_redirect; uint32_t override_redirect;
}; };
</pre></td> </pre></td>
<td>Change window position/size/type</td> <td>Change window position/size/type</td>
@ -192,15 +194,15 @@ struct msg_configure {
<tr> <tr>
<td>MSG_MFNDUMP</td> <td>MSG_MFNDUMP</td>
<td><pre> <td><pre>
struct shm_cmd { struct shm_cmd {
uint32_t shmid; uint32_t shmid;
uint32_t width; uint32_t width;
uint32_t height; uint32_t height;
uint32_t bpp; uint32_t bpp;
uint32_t off; uint32_t off;
uint32_t num_mfn; uint32_t num_mfn;
uint32_t domid; uint32_t domid;
uint32_t mfns[0]; uint32_t mfns[0];
}; };
</pre></td> </pre></td>
<td>Retrieve the array of mfns that constitute the composition buffer of a remote window. <td>Retrieve the array of mfns that constitute the composition buffer of a remote window.
@ -211,8 +213,8 @@ struct shm_cmd {
<tr> <tr>
<td>MSG_SHMIMAGE</td> <td>MSG_SHMIMAGE</td>
<td><pre> <td><pre>
struct msg_shmimage { struct msg_shmimage {
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t width; uint32_t width;
uint32_t height; uint32_t height;
@ -223,8 +225,8 @@ struct msg_shmimage {
<tr> <tr>
<td>MSG_WMNAME</td> <td>MSG_WMNAME</td>
<td><pre> <td><pre>
struct msg_wmname { struct msg_wmname {
char data[128]; char data[128];
}; };
</pre></td> </pre></td>
<td>Set the window name; only printable characters are allowed</td> <td>Set the window name; only printable characters are allowed</td>
@ -237,16 +239,16 @@ struct msg_wmname {
<tr> <tr>
<td>MSG_WINDOW_HINTS</td> <td>MSG_WINDOW_HINTS</td>
<td><pre> <td><pre>
struct msg_window_hints { struct msg_window_hints {
uint32_t flags; uint32_t flags;
uint32_t min_width; uint32_t min_width;
uint32_t min_height; uint32_t min_height;
uint32_t max_width; uint32_t max_width;
uint32_t max_height; uint32_t max_height;
uint32_t width_inc; uint32_t width_inc;
uint32_t height_inc; uint32_t height_inc;
uint32_t base_width; uint32_t base_width;
uint32_t base_height; uint32_t base_height;
}; };
</pre> </td> </pre> </td>
<td>Size hints for window manager</td> <td>Size hints for window manager</td>
@ -254,7 +256,7 @@ struct msg_window_hints {
<tr> <tr>
<td>MSG_WINDOW_FLAGS</td> <td>MSG_WINDOW_FLAGS</td>
<td><pre> <td><pre>
struct msg_window_flags { struct msg_window_flags {
uint32_t flags_set; uint32_t flags_set;
uint32_t flags_unset; uint32_t flags_unset;
}; };
@ -279,12 +281,12 @@ Proper handling of the below messages is NOT security-critical.
Each message starts with the following header Each message starts with the following header
~~~ ```c
struct msghdr { struct msghdr {
uint32_t type; uint32_t type;
uint32_t window; uint32_t window;
}; };
~~~ ```
The header is followed by message-specific data: The header is followed by message-specific data:
@ -297,12 +299,12 @@ The header is followed by message-specific data:
<tr> <tr>
<td>MSG_KEYPRESS</td> <td>MSG_KEYPRESS</td>
<td><pre> <td><pre>
struct msg_keypress { struct msg_keypress {
uint32_t type; uint32_t type;
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t state; uint32_t state;
uint32_t keycode; uint32_t keycode;
}; };
</pre> </td> </pre> </td>
<td>Tell *qubes_drv* driver to generate a keypress</td> <td>Tell *qubes_drv* driver to generate a keypress</td>
@ -310,12 +312,12 @@ struct msg_keypress {
<tr> <tr>
<td>MSG_BUTTON</td> <td>MSG_BUTTON</td>
<td><pre> <td><pre>
struct msg_button { struct msg_button {
uint32_t type; uint32_t type;
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t state; uint32_t state;
uint32_t button; uint32_t button;
}; };
</pre> </td> </pre> </td>
<td>Tell *qubes_drv* driver to generate mouseclick</td> <td>Tell *qubes_drv* driver to generate mouseclick</td>
@ -323,11 +325,11 @@ struct msg_button {
<tr> <tr>
<td>MSG_MOTION</td> <td>MSG_MOTION</td>
<td><pre> <td><pre>
struct msg_motion { struct msg_motion {
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t state; uint32_t state;
uint32_t is_hint; uint32_t is_hint;
}; };
</pre> </td> </pre> </td>
<td>Tell *qubes_drv* driver to generate motion event</td> <td>Tell *qubes_drv* driver to generate motion event</td>
@ -335,12 +337,12 @@ struct msg_motion {
<tr> <tr>
<td>MSG_CONFIGURE</td> <td>MSG_CONFIGURE</td>
<td><pre> <td><pre>
struct msg_configure { struct msg_configure {
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t width; uint32_t width;
uint32_t height; uint32_t height;
uint32_t override_redirect; uint32_t override_redirect;
}; };
</pre> </td> </pre> </td>
<td>Change window position/size/type</td> <td>Change window position/size/type</td>
@ -348,9 +350,9 @@ struct msg_configure {
<tr> <tr>
<td>MSG_MAP</td> <td>MSG_MAP</td>
<td><pre> <td><pre>
struct msg_map_info { struct msg_map_info {
uint32_t transient_for; uint32_t transient_for;
uint32_t override_redirect; uint32_t override_redirect;
}; };
</pre> </td> </pre> </td>
<td>Map a window with given parameters</td> <td>Map a window with given parameters</td>
@ -363,14 +365,14 @@ struct msg_map_info {
<tr> <tr>
<td>MSG_CROSSING</td> <td>MSG_CROSSING</td>
<td><pre> <td><pre>
struct msg_crossing { struct msg_crossing {
uint32_t type; uint32_t type;
uint32_t x; uint32_t x;
uint32_t y; uint32_t y;
uint32_t state; uint32_t state;
uint32_t mode; uint32_t mode;
uint32_t detail; uint32_t detail;
uint32_t focus; uint32_t focus;
}; };
</pre> </td> </pre> </td>
<td>Notify window about enter/leave event</td> <td>Notify window about enter/leave event</td>
@ -378,10 +380,10 @@ struct msg_crossing {
<tr> <tr>
<td>MSG_FOCUS</td> <td>MSG_FOCUS</td>
<td><pre> <td><pre>
struct msg_focus { struct msg_focus {
uint32_t type; uint32_t type;
uint32_t mode; uint32_t mode;
uint32_t detail; uint32_t detail;
}; };
</pre> </td> </pre> </td>
<td>Raise a window, XSetInputFocus</td> <td>Raise a window, XSetInputFocus</td>
@ -409,8 +411,8 @@ struct msg_focus {
<tr> <tr>
<td>MSG_WINDOW_FLAGS</td> <td>MSG_WINDOW_FLAGS</td>
<td><pre> <td><pre>
struct msg_window_flags { struct msg_window_flags {
uint32_t flags_set; uint32_t flags_set;
uint32_t flags_unset; uint32_t flags_unset;
}; };
</pre> </td> </pre> </td>

23
developer/system/networking.md
View File

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

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

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

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

@ -1,7 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Storage Pools
permalink: /doc/storage-pools/ permalink: /doc/storage-pools/
ref: 57
title: Storage Pools
--- ---
Storage Pools in Qubes Storage Pools in Qubes
@ -32,7 +34,6 @@ When installed, the system has, as you can see from the contents of
default pool is special in R3.2. It will add `dir_path=/var/lib/qubes` default pool is special in R3.2. It will add `dir_path=/var/lib/qubes`
configuration value from `defaults[pool_config]`, if not overwritten. configuration value from `defaults[pool_config]`, if not overwritten.
Currently the only supported driver out of the box is `xen`. The benefit of Currently the only supported driver out of the box is `xen`. The benefit of
pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2 pools (besides that you can write your own storage driver e.g. for Btrfs) in R3.2
is that you can store your domains in multiple places. is that you can store your domains in multiple places.
@ -50,4 +51,4 @@ argument to `qvm-create` to have the VM images stored in pool `foo`. See also
`qvm-create --help`. `qvm-create --help`.
While the current API is not as clean and beautiful as the R4 API, it allows 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.

5
developer/system/system-doc.md
View File

@ -1,6 +1,6 @@
--- ---
lang: en
layout: doc layout: doc
title: System Documentation
permalink: /doc/system-doc/ permalink: /doc/system-doc/
redirect_from: redirect_from:
- /en/doc/system-doc/ - /en/doc/system-doc/
@ -8,5 +8,6 @@ redirect_from:
- /wiki/SystemDoc/ - /wiki/SystemDoc/
redirect_to: redirect_to:
- /doc/#developer-documentation - /doc/#developer-documentation
ref: 62
title: System Documentation
--- ---

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

@ -1,66 +1,63 @@
--- ---
lang: en
layout: doc layout: doc
title: Template Implementation
permalink: /doc/template-implementation/ permalink: /doc/template-implementation/
redirect_from: redirect_from:
- /en/doc/template-implementation/ - /en/doc/template-implementation/
- /doc/TemplateImplementation/ - /doc/TemplateImplementation/
- /wiki/TemplateImplementation/ - /wiki/TemplateImplementation/
ref: 58
title: Template Implementation
--- ---
Overview of VM block devices # Overview of VM block devices
============================
Every VM has 4 block devices connected: Every VM has 4 block devices connected:
- **xvda** – base root device (/) – details described below - **xvda** – base root device (/) – details described below
- **xvdb** – private.img – place where VM always can write. - **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) - **xvdc** – volatile.img, discarded at each VM restart – here is placed swap and temporal "/" modifications (see below)
- **xvdd** – modules.img – kernel modules and firmware - **xvdd** – modules.img – kernel modules and firmware
private.img (xvdb) ## private.img (xvdb)
------------------
This is mounted as /rw and here is placed all VM private data. This includes: This is mounted as /rw and here is placed all VM private data. This includes:
- */home* – which is bind mounted to /rw/home - */home* – which is bind mounted to /rw/home
- */usr/local* – which is symlink to /rw/usrlocal - */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local) - 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. **Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM are copied to the child TemplateBasedVM's `/home`. From that point onward, the child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any subsequent changes to the parent TemplateVM's `/home` will no longer affect the child TemplateBasedVM's `/home`. Once a TemplateBasedVM has been created, any changes in its `/home`, `/usr/local`, or `/rw/config` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the TemplateBasedVM. No changes in any other directories in TemplateBasedVMs persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent TemplateVM.
modules.img (xvdd) ## modules.img (xvdd)
------------------
As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files: As the kernel is chosen in dom0, there must be some way to provide matching kernel modules to VM. Qubes kernel directory consists of 3 files:
- *vmlinuz* – actual kernel - *vmlinuz* – actual kernel
- *initramfs* – initial ramdisk containing script to setup snapshot devices (see below) and mount /lib/modules - *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) - *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. Normally kernel "package" is common for many VMs (can be set using qvm-prefs). One of them can be set as default (qvm-set-default-kernel) to simplify kernel updates (by default all VMs use the default kernel). All installed kernels are placed in /var/lib/qubes/vm-kernels as separate subdirs. In this case, modules.img is attached to the VM as R/O device.
There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom". There is a special case when the VM can have a custom kernel – when it is updateable (StandaloneVM or TemplateVM) and the kernel is set to "none" (by qvm-prefs). In this case the VM uses the kernel from the "kernels" VM subdir and modules.img is attached as R/W device. FIXME: "none" should be renamed to "custom".
Qubes TemplateVM implementation # Qubes TemplateVM implementation
===============================
TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs: TemplateVM has a shared root.img across all AppVMs that are based on it. This mechanism has some advantages over a simple common device connected to multiple VMs:
- root.img can be modified while there are AppVMs running – without corrupting the filesystem - 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 - 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. 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) ![TemplateSharing2.png](/attachment/wiki/TemplateImplementation/TemplateSharing2.png)
Snapshot device in Dom0 ## Snapshot device in Dom0
-----------------------
This device consists of: This device consists of:
- root.img – real template filesystem - root.img – real template filesystem
- root-cow.img – differences between the device as seen by AppVM and the current root.img - 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. 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 +79,29 @@ This is done using snapshot-merge device-mapper target (available from 2.6.34 ke
Steps performed by **qvm-revert-template-changes**: Steps performed by **qvm-revert-template-changes**:
1. Ensure that no other VMs uses this template. 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*). 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). 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. 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*. 5. Replace *snapshot-merge* d-m target back to *snapshot*.
6. Cleanup snapshot device (if nobody uses it at the moment). 6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file). 7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
Snapshot device in AppVM ## Snapshot device in AppVM
------------------------
Root device is exposed to AppVM in read-only mode. AppVM can write only in: Root device is exposed to AppVM in read-only mode. AppVM can write only in:
- private.img – persistent storage (mounted in /rw) used for /home, /usr/local – in future versions, its use may be extended - 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 – temporary storage, which is discarded after an AppVM restart
volatile.img is divided into two partitions: volatile.img is divided into two partitions:
1. changes to root device 1. changes to root device
2. swap partition 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. Inside of an AppVM, the root device is wrapped by the snapshot in the first partition of volatile.img. Therefore, the AppVM can write anything to its filesystem – however, such changes will be discarded after a restart.
StandaloneVM ## StandaloneVM
------------
Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*. Standalone VM enables user to modify root filesystem persistently. It can be created using *--standalone* switch to *qvm-create*.

289
doc.md
View File

@ -1,6 +1,6 @@
--- ---
layout: doc lang: en
title: Documentation layout: doc-index
permalink: /doc/ permalink: /doc/
redirect_from: redirect_from:
- /en/doc/ - /en/doc/
@ -12,287 +12,6 @@ redirect_from:
- /en/help/ - /en/help/
- /en/community/ - /en/community/
- /community/ - /community/
ref: 12
title: Documentation
--- ---
# Qubes OS Documentation
Welcome to the Qubes OS documentation!
## Introduction
* [What is Qubes OS?](/intro/)
* [Video Tours](/video-tours/)
* [Screenshots](/screenshots/)
* [User FAQ](/faq/#users)
* [Reporting Bugs and Other Issues](/doc/reporting-bugs/)
* [Help, Support, Mailing Lists, and Forum](/support/)
* [How to Contribute](/doc/contributing/)
## Project Security
* [Security Center](/security/)
* [Security FAQ](/faq/#general--security)
* [Security Pack](/security/pack/)
* [Security Bulletins](/security/bulletins/)
* [Canaries](/security/canaries/)
* [Xen Security Advisory (XSA) Tracker](/security/xsa/)
* [Verifying Signatures](/security/verifying-signatures/)
* [Qubes PGP Keys](https://keys.qubes-os.org/keys/)
## User Documentation
Core documentation for Qubes users.
### Choosing Your Hardware
* [System Requirements](/doc/system-requirements/)
* [Certified Hardware](/doc/certified-hardware/)
* [Hardware Compatibility List (HCL)](/hcl/)
* [Hardware Testing](/doc/hardware-testing/)
### Downloading, Installing, and Upgrading Qubes
* [Downloads](/downloads/)
* [Installation Guide](/doc/installation-guide/)
* [Upgrade Guides](/doc/upgrade/)
* [Supported Versions](/doc/supported-versions/)
* [Version Scheme](/doc/version-scheme/)
* [Testing New Releases and Updates](/doc/testing/)
### Common Tasks
* [Getting Started](/getting-started/)
* [Copying and Pasting Text Between Domains](/doc/copy-paste/)
* [Copying and Moving Files Between Domains](/doc/copying-files/)
* [Copying from (and to) Dom0](/doc/copy-from-dom0/)
* [Updating Qubes OS](/doc/updating-qubes-os/)
* [Installing and Updating Software in Dom0](/doc/software-update-dom0/)
* [Installing and Updating Software in DomUs](/doc/software-update-domu/)
* [Backup, Restoration, and Migration](/doc/backup-restore/)
* [Volume Backup and Revert](/doc/volume-backup-revert/)
* [DisposableVMs](/doc/disposablevm/)
* [Block (or Storage) Devices](/doc/block-devices/)
* [USB Devices](/doc/usb-devices)
* [PCI Devices](/doc/pci-devices/)
* [Device Handling](/doc/device-handling/)
* [Optical Discs](/doc/optical-discs/)
* [Fullscreen Mode](/doc/full-screen-mode/)
### Managing Operating Systems within Qubes
* [TemplateVMs](/doc/templates/)
* [Fedora](/doc/templates/fedora/)
* [Debian](/doc/templates/debian/)
* [Minimal TemplateVMs](/doc/templates/minimal/)
* [Windows](/doc/windows/)
* [StandaloneVMs and HVMs](/doc/standalone-and-hvm/)
### Security in Qubes
* [Qubes Firewall](/doc/firewall/)
* [Understanding and Preventing Data Leaks](/doc/data-leaks/)
* [Passwordless Root Access in VMs](/doc/vm-sudo/)
* [Device Handling Security](/doc/device-handling-security/)
* [Anti Evil Maid](/doc/anti-evil-maid/)
* [Split GPG](/doc/split-gpg/)
* [U2F Proxy](/doc/u2f-proxy/)
* [YubiKey](/doc/yubi-key/)
### Advanced Configuration
* [Configuration Files](/doc/config-files/)
* [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
* [RPC Policies](/doc/rpc-policy/)
* [USB Qubes](/doc/usb-qubes/)
* [Managing VM Kernels](/doc/managing-vm-kernel/)
* [Salt Management Stack](/doc/salt/)
* [DisposableVM Customization](/doc/disposablevm-customization/)
* [Making Any File Persistent Using `bind-dirs`](/doc/bind-dirs/)
* [GUI Configuration](/doc/gui-configuration/)
* [Resizing Disk Images](/doc/resize-disk-image/)
* [Mounting and Decrypting Qubes Partitions from Outside Qubes](/doc/mount-from-other-os/)
* [KDE](/doc/kde/)
* [i3 Window Manager](/doc/i3/)
* [awesome Window Manager](/doc/awesome/)
### Troubleshooting
* [Installation Troubleshooting](/doc/installation-troubleshooting)
* [UEFI Troubleshooting](/doc/uefi-troubleshooting/)
* [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/)
* [Application Shortcut Troubleshooting](/doc/managing-appvm-shortcuts/)
* [VM Troubleshooting](/doc/vm-troubleshooting/)
* [HVM Troubleshooting](/doc/hvm-troubleshooting/)
* [Disk Troubleshooting](/doc/disk-troubleshooting/)
* [PCI Troubleshooting](/doc/pci-troubleshooting/)
* [USB Troubleshooting](/doc/usb-troubleshooting/)
* [GUI Troubleshooting](/doc/gui-troubleshooting/)
* [Media Troubleshooting](/doc/media-troubleshooting/)
* [Firewall Troubleshooting](/doc/firewall/#firewall-troubleshooting)
* [Hardware Troubleshooting](/doc/hardware-troubleshooting/)
* [VPN Troubleshooting](/doc/vpn-troubleshooting/)
* [Update Troubleshooting](/doc/update-troubleshooting/)
### Reference Pages
* [Command-line Tools](/doc/tools/)
* [Glossary](/doc/glossary/)
* [Qubes Service Framework](/doc/qubes-service/)
* [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/)
* [Deprecated Documentation](https://github.com/QubesOS/qubesos.github.io#deprecated-documentation)
## Developer Documentation
Core documentation for Qubes developers and advanced users.
### General
* [Developer FAQ](/faq/#developers)
* [Package Contributions](/doc/package-contributions/)
* [Documentation Guidelines](/doc/doc-guidelines/)
* [Community-Developed Feature Tracker](/qubes-issues/)
* [Google Summer of Code](/gsoc/)
* [Google Season of Docs](/gsod/)
* [Books for Developers](/doc/devel-books/)
* [Style Guide](/doc/style-guide/)
* [Usability & UX](/doc/usability-ux/)
### Code
* [Source Code](/doc/source-code/)
* [Software License](/doc/license/)
* [Coding Guidelines](/doc/coding-style/)
* [Code Signing](/doc/code-signing/)
### System
* [Qubes OS Architecture Overview](/doc/architecture/)
* [Security-critical Code in Qubes OS](/doc/security-critical-code/)
* [Qubes Core Admin](https://dev.qubes-os.org/projects/core-admin/en/latest/)
* [Qubes Core Admin Client](https://dev.qubes-os.org/projects/core-admin-client/en/latest/)
* [Qubes Admin API](/news/2017/06/27/qubes-admin-api/)
* [Qubes Core Stack](/news/2017/10/03/core3/)
* [Qubes GUI virtualization protocol](/doc/gui/)
* [Networking in Qubes](/doc/networking/)
* [Implementation of template sharing and updating](/doc/template-implementation/)
* [Storage Pools](/doc/storage-pools/)
* [Audio virtualization](/doc/audio-virtualization/)
### Services
* [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
* [Dynamic memory management in Qubes](/doc/qmemman/)
* [Implementation of DisposableVMs](/doc/dvm-impl/)
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
* [Qrexec: secure communication across domains](/doc/qrexec/)
* [Qrexec: Qubes RPC internals](/doc/qrexec-internals/)
* [Qrexec: Socket-based services](/doc/qrexec-socket-services/)
### Debugging
* [Profiling python code](/doc/profiling/)
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
* [Automated tests](/doc/automated-tests/)
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
* [Debugging Windows VMs](/doc/windows-debugging/)
* [Safe Remote Dom0 Terminals](/doc/safe-remote-ttys/)
* [Mount LVM Image](/doc/mount-lvm-image/)
### Building
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
* [Development Workflow](/doc/development-workflow/)
* [Building Qubes OS ISO](/doc/qubes-iso-building/)
* [Qubes Template Configuration Files](https://github.com/QubesOS/qubes-template-configs)
### Releases
* [Release notes](/doc/releases/notes/)
* [Release schedules](/doc/releases/schedules/)
* [Release checklist](/doc/releases/todo/)
## External Documentation
Unofficial, third-party documentation from the Qubes community and others.
For more, please see [Qubes Community Documentation](https://github.com/Qubes-Community/Contents/tree/master/docs).
### Operating System Guides
* [Template: Ubuntu](https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md)
* [Template: Whonix](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md)
* [Template: CentOS](https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md)
* [Template: Gentoo](https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md)
* [Pentesting](https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting.md)
* [Pentesting: BlackArch](https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md)
* [Pentesting: Kali](https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md)
* [Pentesting: PTF](https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md)
* [Tips for Using Linux in an HVM](https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md)
* [Creating a NetBSD VM](https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md)
### Security Guides
* [Security Guidelines](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md)
* [Using Multi-factor Authentication with Qubes](https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md)
* [How to Set Up a Split Bitcoin Wallet in Qubes](https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md)
* [Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
* [Split SSH](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/split-ssh.md)
* [Using OnlyKey with Qubes OS](https://docs.crp.to/qubes.html)
### Privacy Guides
* [Whonix for Privacy & Anonymity](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md)
* [Running Tails in Qubes](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md)
* [Anonymizing your MAC Address](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/anonymizing-your-mac-address.md)
* [Signal](https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md)
* [Reducing the fingerprint of the text-based web browser w3m](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/w3m.md)
### Configuration Guides
* [Qubes Tips and Tricks](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/tips-and-tricks.md)
* [How to set up a ProxyVM as a VPN Gateway](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md)
* [Multibooting](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md)
* [Changing your Time Zone](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md)
* [Installing ZFS in Qubes](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zfs.md)
* [Mutt Guide](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md)
* [Postfix Guide](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/postfix.md)
* [Fetchmail Guide](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/fetchmail.md)
* [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
* [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
* [Adding Bridge Support to the NetVM (EXPERIMENTAL)](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md)
* [Enabling TRIM for SSD disks](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/disk-trim.md)
* [Configuring a Network Printer](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md)
* [Using External Audio Devices](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md)
* [Rxvt Guide](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/rxvt.md)
* [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com)
* [How to Make a Multimedia TemplateVM](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md)
* [How to install an Nvidia driver in dom0](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md)
### Customization Guides
* [Customizing Fedora minimal templates](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md)
* [Customizing Windows 7 templates](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md)
* [Language Localization](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md)
* [Dark Theme in Dom0 and DomU](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md)
* [Safely Removing TemplateVM Packages (Example: Thunderbird)](https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md)
### Troubleshooting
* [Nvidia Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md)
* [Lenovo ThinkPad Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/thinkpad-troubleshooting.md)
* [Apple MacBook Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md)
* [Sony Vaio Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/sony-vaio-tinkering.md)
* [Intel Integrated Graphics Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md)
* [Multiboot Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md#troubleshooting)
* [Application Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md)
* [Tails Troubleshooting](https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/tails-troubleshooting.md)
### Building Guides
* [Building a TemplateVM based on a new OS (ArchLinux example)](https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md)
* [Building the Archlinux Template](https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md)
* [Building the Whonix Templates](https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-whonix-template.md)
* [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion)

7
external/building-guides/building-archlinux-template.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Building Archlinux Template
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md
redirect_from: redirect_from:
- /doc/building-archlinux-template/ - /doc/building-archlinux-template/
- /en/doc/building-archlinux-template/ - /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/ - /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/ - /wiki/BuildingArchlinuxTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md
ref: 116
title: Building Archlinux Template
--- ---

6
external/building-guides/building-non-fedora-template.md vendored
View File

@ -1,11 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Building Non-Fedora Template
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md
redirect_from: redirect_from:
- /doc/building-non-fedora-template/ - /doc/building-non-fedora-template/
- /en/doc/building-non-fedora-template/ - /en/doc/building-non-fedora-template/
- /doc/BuildingNonFedoraTemplate/ - /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/ - /wiki/BuildingNonFedoraTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md
ref: 117
title: Building Non-Fedora Template
--- ---

7
external/building-guides/building-whonix-template.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: Building Whonix Templates
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-whonix-template.md
redirect_from: redirect_from:
- /doc/building-whonix-template/ - /doc/building-whonix-template/
- /en/doc/building-whonix-template/ - /en/doc/building-whonix-template/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-whonix-template.md
ref: 115
title: Building Whonix Templates
--- ---

7
external/configuration-guides/change-time-zone.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Changing your Time Zone
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md
redirect_from: redirect_from:
- /doc/change-time-zone/ - /doc/change-time-zone/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md
ref: 109
title: Changing your Time Zone
--- ---

7
external/configuration-guides/disk-trim.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Disk TRIM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/disk-trim.md
redirect_from: redirect_from:
- /doc/disk-trim/ - /doc/disk-trim/
- /en/doc/disk-trim/ - /en/doc/disk-trim/
- /doc/DiskTRIM/ - /doc/DiskTRIM/
- /wiki/DiskTRIM/ - /wiki/DiskTRIM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/disk-trim.md
ref: 104
title: Disk TRIM
--- ---

7
external/configuration-guides/external-audio.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: External Audio
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md
redirect_from: redirect_from:
- /doc/external-audio/ - /doc/external-audio/
- /en/doc/external-audio/ - /en/doc/external-audio/
- /doc/ExternalAudio/ - /doc/ExternalAudio/
- /wiki/ExternalAudio/ - /wiki/ExternalAudio/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md
ref: 100
title: External Audio
--- ---

7
external/configuration-guides/fetchmail.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Fetchmail
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/fetchmail.md
redirect_from: redirect_from:
- /doc/fetchmail/ - /doc/fetchmail/
- /en/doc/fetchmail/ - /en/doc/fetchmail/
- /doc/Fetchmail/ - /doc/Fetchmail/
- /wiki/Fetchmail/ - /wiki/Fetchmail/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/fetchmail.md
ref: 114
title: Fetchmail
--- ---

7
external/configuration-guides/install-nvidia-driver.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: How to Install an Nvidia Driver
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md
redirect_from: redirect_from:
- /doc/install-nvidia-driver/ - /doc/install-nvidia-driver/
- /en/doc/install-nvidia-driver/ - /en/doc/install-nvidia-driver/
- /doc/InstallNvidiaDriver/ - /doc/InstallNvidiaDriver/
- /wiki/InstallNvidiaDriver/ - /wiki/InstallNvidiaDriver/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md
ref: 96
title: How to Install an Nvidia Driver
--- ---

7
external/configuration-guides/multiboot.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Multibooting
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
redirect_from: redirect_from:
- https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md - https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
ref: 112
title: Multibooting
--- ---

7
external/configuration-guides/multimedia.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: How to Make a Multimedia TemplateVM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md
redirect_from: redirect_from:
- /doc/multimedia/ - /doc/multimedia/
- /en/doc/multimedia/ - /en/doc/multimedia/
- /doc/Multimedia/ - /doc/Multimedia/
- /wiki/Multimedia/ - /wiki/Multimedia/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md
ref: 105
title: How to Make a Multimedia TemplateVM
--- ---

7
external/configuration-guides/mutt.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Mutt
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md
redirect_from: redirect_from:
- /doc/mutt/ - /doc/mutt/
- /en/doc/mutt/ - /en/doc/mutt/
- /doc/Mutt/ - /doc/Mutt/
- /wiki/Mutt/ - /wiki/Mutt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md
ref: 106
title: Mutt
--- ---

7
external/configuration-guides/network-bridge-support.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Network Bridge Support
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md
redirect_from: redirect_from:
- /doc/network-bridge-support/ - /doc/network-bridge-support/
- /en/doc/network-bridge-support/ - /en/doc/network-bridge-support/
- /doc/NetworkBridgeSupport/ - /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/ - /wiki/NetworkBridgeSupport/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md
ref: 113
title: Network Bridge Support
--- ---

7
external/configuration-guides/network-printer.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Network Printer
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md
redirect_from: redirect_from:
- /doc/network-printer/ - /doc/network-printer/
- /en/doc/network-printer/ - /en/doc/network-printer/
- /doc/NetworkPrinter/ - /doc/NetworkPrinter/
- /wiki/NetworkPrinter/ - /wiki/NetworkPrinter/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md
ref: 108
title: Network Printer
--- ---

142
external/configuration-guides/postfix.md vendored
View File

@ -1,146 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Postfix
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/postfix.md
redirect_from: redirect_from:
- /doc/postfix/ - /doc/postfix/
- /en/doc/postfix/ - /en/doc/postfix/
- /doc/Postfix/ - /doc/Postfix/
- /wiki/Postfix/ - /wiki/Postfix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/postfix.md
ref: 107
title: Postfix
--- ---
Postfix
=======
Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](/doc/mutt/)+Postfix+[Fetchmail](/doc/fetchmail/) stack.
Installation
------------
`dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain`
Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables.
You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something
Configuration
-------------
In TemplateVM open `/etc/aliases` and add line:
~~~
root: user
~~~
and run `newaliases`.
This is the only thing to do in TemplateVM, as MTA configuration is AppVM specific, so we will keep it in `/usr/local` (ie. `/rw/usrlocal`) in each AppVM.
Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` and `/etc/postfix/postfix-files` there.
### Makefile
Postfix keeps its lookup tables in bdb hash databases. They need to be compiled from source files. Postfix admins like to keep track of them by means of `/usr/local/etc/postfix/Makefile`:
~~~
all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf))
newaliases
clean:
$(RM) *.db
.PHONY: all clean
%.db: %
/usr/sbin/postmap hash:$<
~~~
### Postfix main configuration
`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it):
~~~
mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain
mynetworks_style = host
inet_protocols = ipv4
smtp_generic_maps = hash:/etc/postfix/generic
local_header_rewrite_clients =
smtp_sender_dependent_authentication = yes
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/saslpass
smtp_sasl_security_options =
smtp_tls_security_level = encrypt
smtp_sasl_mechanism_filter = plain, login
smtpd_relay_restrictions = permit_mynetworks,permit_sasl_authenticated,defer_unauth_destination
smtpd_sender_restrictions = check_sender_access hash:/etc/postfix/sender_access
home_mailbox = .maildir/
setgid_group = postdrop
mail_owner = postfix
html_directory = no
manpage_directory = /usr/share/man
queue_directory = /var/spool/postfix
readme_directory = no
mailbox_command = /usr/bin/procmail
sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
alias_maps = hash:/etc/aliases
~~~
### Lookup tables
`/usr/local/etc/postfix/generic` (put there your primary address):
~~~
@localhost your.mail@example.com
~~~
`/usr/local/etc/postfix/sender_relay`. This is an important file. Put all your SMTP servers there. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
~~~
`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on your provider if you need to put whole email as username or just the part before `@`.
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
[smtp.mail.com]:smtp your.other@mail.com:supers3cret
~~~
`/usr/local/etc/postfix/sender_access`. I use it to nullroute known spam domains. If you do not need it, comment respective line in `main.cf`.
~~~
spamdomain1.com DISCARD
spamdomain2.com DISCARD
~~~
Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four above mentioned lookup tables (`generic.db`, `sender_relay.db`, `saslpass.db` and `sender_access`).
### procmail
Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`:
~~~
MAILDIR = "${HOME}/.maildir"
ORGMAIL = "${MAILDIR}/"
DEFAULT = "${MAILDIR}/"
:0
* ^List-Id:.*qubes-users\.googlegroups\.com
list/qubes-users/
:0
* ^List-Id:.*qubes-devel\.googlegroups\.com
list/qubes-devel/
~~~
Run
---

7
external/configuration-guides/rxvt.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Rxvt
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/rxvt.md
redirect_from: redirect_from:
- /doc/rxvt/ - /doc/rxvt/
- /en/doc/rxvt/ - /en/doc/rxvt/
- /doc/Rxvt/ - /doc/Rxvt/
- /wiki/Rxvt/ - /wiki/Rxvt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/rxvt.md
ref: 103
title: Rxvt
--- ---

7
external/configuration-guides/tips-and-tricks.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Tips and Tricks
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/tips-and-tricks.md
redirect_from: redirect_from:
- /doc/tips-and-tricks/ - /doc/tips-and-tricks/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/tips-and-tricks.md
ref: 110
title: Tips and Tricks
--- ---

7
external/configuration-guides/vpn.md vendored
View File

@ -1,12 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: VPN
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md
redirect_from: redirect_from:
- /doc/vpn/ - /doc/vpn/
- /doc/privacy/vpn/ - /doc/privacy/vpn/
- /en/doc/vpn/ - /en/doc/vpn/
- /doc/VPN/ - /doc/VPN/
- /wiki/VPN/ - /wiki/VPN/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md
ref: 102
title: VPN
--- ---

7
external/configuration-guides/w3m.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Reducing the fingerprint of the text-based web browser w3m
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/w3m.md
redirect_from: redirect_from:
- /doc/w3m/ - /doc/w3m/
- /en/doc/mutt/ - /en/doc/mutt/
- /doc/W3m/ - /doc/W3m/
- /wiki/W3m/ - /wiki/W3m/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/w3m.md
ref: 101
title: Reducing the fingerprint of the text-based web browser w3m
--- ---

7
external/configuration-guides/zfs.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: ZFS
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zfs.md
redirect_from: redirect_from:
- /doc/zfs/ - /doc/zfs/
- /en/doc/zfs/ - /en/doc/zfs/
- /doc/ZFS/ - /doc/ZFS/
- /wiki/ZFS/ - /wiki/ZFS/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zfs.md
ref: 111
title: ZFS
--- ---

7
external/customization-guides/dark-theme.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Dark Theme in Dom0 and DomU
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md
redirect_from: redirect_from:
- /doc/dark-theme/ - /doc/dark-theme/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md
ref: 74
title: Dark Theme in Dom0 and DomU
--- ---

9
external/customization-guides/fedora-minimal-template-customization.md vendored
View File

@ -1,9 +1,8 @@
--- ---
lang: en
layout: doc layout: doc
title: Fedora Minimal Template Customization
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md
redirect_from:
- /doc/fedora-minimal-template-customization/
redirect_from: /en/doc/fedora-minimal-template-customization/ redirect_from: /en/doc/fedora-minimal-template-customization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/fedora-minimal-template-customization.md
ref: 76
title: Fedora Minimal Template Customization
--- ---

7
external/customization-guides/language-localization.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Language Localization
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md
redirect_from: redirect_from:
- /doc/language-localization/ - /doc/language-localization/
- /en/doc/language-localization/ - /en/doc/language-localization/
- /doc/LanguageLocalization/ - /doc/LanguageLocalization/
- /wiki/LanguageLocalization/ - /wiki/LanguageLocalization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md
ref: 73
title: Language Localization
--- ---

7
external/customization-guides/removing-templatevm-packages.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Removing TemplateVM Packages
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md
redirect_from: redirect_from:
- /doc/removing-templatevm-packages/ - /doc/removing-templatevm-packages/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md
ref: 75
title: Removing TemplateVM Packages
--- ---

8
external/customization-guides/windows-template-customization.md vendored
View File

@ -1,9 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Windows Template Customization
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md
redirect_from: redirect_from:
- /doc/windows-template-customization/ - /doc/windows-template-customization/
redirect_from: /en/doc/windows-template-customization/ redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md
ref: 72
title: Windows Template Customization
--- ---

7
external/os-guides/centos.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: CentOS Template
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md
redirect_from: redirect_from:
- /doc/templates/centos/ - /doc/templates/centos/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md
ref: 81
title: CentOS Template
--- ---

6
external/os-guides/gentoo.md vendored
View File

@ -1,7 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Gentoo Template
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md
redirect_from: redirect_from:
- /doc/templates/gentoo/ - /doc/templates/gentoo/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md
ref: 221
title: Gentoo Template
--- ---

7
external/os-guides/linux-hvm-tips.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Linux HVM Tips
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md
redirect_from: redirect_from:
- /doc/linux-hvm-tips/ - /doc/linux-hvm-tips/
- /en/doc/linux-hvm-tips/ - /en/doc/linux-hvm-tips/
- /doc/LinuxHVMTips/ - /doc/LinuxHVMTips/
- /wiki/LinuxHVMTips/ - /wiki/LinuxHVMTips/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md
ref: 82
title: Linux HVM Tips
--- ---

7
external/os-guides/netbsd.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: How to Create a NetBSD VM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md
redirect_from: redirect_from:
- /doc/netbsd/ - /doc/netbsd/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md
ref: 84
title: How to Create a NetBSD VM
--- ---

7
external/os-guides/pentesting.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Penetration Testing
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting.md
redirect_from: redirect_from:
- /doc/pentesting/ - /doc/pentesting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting.md
ref: 83
title: Penetration Testing
--- ---

7
external/os-guides/pentesting/blackarch.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: How to Create a BlackArch VM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md
redirect_from: redirect_from:
- /doc/pentesting/blackarch/ - /doc/pentesting/blackarch/
- /doc/blackarch/ - /doc/blackarch/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md
ref: 88
title: How to Create a BlackArch VM
--- ---

7
external/os-guides/pentesting/kali.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: How to create a Kali Linux VM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md
redirect_from: redirect_from:
- /doc/pentesting/kali/ - /doc/pentesting/kali/
- /doc/kali/ - /doc/kali/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md
ref: 87
title: How to create a Kali Linux VM
--- ---

7
external/os-guides/pentesting/ptf.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: How to create Penetration Testers Framework (PTF) VM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md
redirect_from: redirect_from:
- /doc/pentesting/ptf/ - /doc/pentesting/ptf/
- /doc/ptf/ - /doc/ptf/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md
ref: 89
title: How to create Penetration Testers Framework (PTF) VM
--- ---

7
external/os-guides/ubuntu.md vendored
View File

@ -1,12 +1,13 @@
--- ---
lang: en
layout: doc layout: doc
title: Ubuntu Template
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md
redirect_from: redirect_from:
- /doc/templates/ubuntu/ - /doc/templates/ubuntu/
- /doc/ubuntu/ - /doc/ubuntu/
- /en/doc/templates/ubuntu/ - /en/doc/templates/ubuntu/
- /doc/Templates/Ubuntu/ - /doc/Templates/Ubuntu/
- /wiki/Templates/Ubuntu/ - /wiki/Templates/Ubuntu/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md
ref: 80
title: Ubuntu Template
--- ---

7
external/os-guides/windows/windows-tools.md vendored
View File

@ -1,7 +1,6 @@
--- ---
lang: en
layout: doc layout: doc
title: Qubes Windows Tools
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md
redirect_from: redirect_from:
- /doc/windows-tools/ - /doc/windows-tools/
- /doc/windows-appvms/ - /doc/windows-appvms/
@ -13,5 +12,7 @@ redirect_from:
- /doc/WindowsTools3/ - /doc/WindowsTools3/
- /doc/WindowsTools/ - /doc/WindowsTools/
- /wiki/WindowsTools/ - /wiki/WindowsTools/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md
ref: 86
title: Qubes Windows Tools
--- ---

7
external/os-guides/windows/windows-vm.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Installing a Windows VM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md
redirect_from: redirect_from:
- /doc/windows-vm/ - /doc/windows-vm/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md
ref: 85
title: Installing a Windows VM
--- ---

7
external/privacy-guides/anonymizing-your-mac-address.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: Anonymizing your MAC Address
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/anonymizing-your-mac-address.md
redirect_from: redirect_from:
- /doc/anonymizing-your-mac-address/ - /doc/anonymizing-your-mac-address/
- /doc/randomizing-your-mac-address/ - /doc/randomizing-your-mac-address/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/anonymizing-your-mac-address.md
ref: 67
title: Anonymizing your MAC Address
--- ---

7
external/privacy-guides/signal.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Signal
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md
redirect_from: redirect_from:
- /doc/signal/ - /doc/signal/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md
ref: 70
title: Signal
--- ---

7
external/privacy-guides/tails.md vendored
View File

@ -1,9 +1,10 @@
--- ---
lang: en
layout: doc layout: doc
title: Running Tails in Qubes
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md
redirect_from: redirect_from:
- /doc/tails/ - /doc/tails/
- /doc/running-tails - /doc/running-tails
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md
ref: 71
title: Running Tails in Qubes
--- ---

7
external/privacy-guides/torvm.md vendored
View File

@ -1,7 +1,6 @@
--- ---
lang: en
layout: doc layout: doc
title: TorVM
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/torvm.md
redirect_from: redirect_from:
- /doc/torvm/ - /doc/torvm/
- /doc/privacy/torvm/ - /doc/privacy/torvm/
@ -9,5 +8,7 @@ redirect_from:
- /doc/TorVM/ - /doc/TorVM/
- /doc/UserDoc/TorVM/ - /doc/UserDoc/TorVM/
- /wiki/UserDoc/TorVM/ - /wiki/UserDoc/TorVM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/torvm.md
ref: 68
title: TorVM
--- ---

7
external/privacy-guides/whonix.md vendored
View File

@ -1,7 +1,6 @@
--- ---
lang: en
layout: doc layout: doc
title: Whonix for Privacy & Anonymity
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md
redirect_from: redirect_from:
- /doc/whonix/ - /doc/whonix/
- /doc/privacy/whonix/ - /doc/privacy/whonix/
@ -17,5 +16,7 @@ redirect_from:
- /doc/privacy/uninstall-whonix/ - /doc/privacy/uninstall-whonix/
- /doc/whonix/update/ - /doc/whonix/update/
- /doc/privacy/updating-whonix/ - /doc/privacy/updating-whonix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md
ref: 69
title: Whonix for Privacy & Anonymity
--- ---

7
external/security-guides/multifactor-authentication.md vendored
View File

@ -1,10 +1,11 @@
--- ---
lang: en
layout: doc layout: doc
title: Multifactor Authentication
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md
redirect_from: redirect_from:
- /doc/multifactor-authentication/ - /doc/multifactor-authentication/
- /en/doc/multifactor-authentication/ - /en/doc/multifactor-authentication/
- /doc/Multi-factorAuthentication/ - /doc/Multi-factorAuthentication/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md
ref: 78
title: Multifactor Authentication
--- ---

7
external/security-guides/security-guidelines.md vendored
View File

@ -1,11 +1,12 @@
--- ---
lang: en
layout: doc layout: doc
title: Security Guidelines
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md
redirect_from: redirect_from:
- /doc/security-guidelines/ - /doc/security-guidelines/
- /en/doc/security-guidelines/ - /en/doc/security-guidelines/
- /doc/SecurityGuidelines/ - /doc/SecurityGuidelines/
- /wiki/SecurityGuidelines/ - /wiki/SecurityGuidelines/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md
ref: 79
title: Security Guidelines
--- ---

7
external/security-guides/split-bitcoin.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Split Bitcoin
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md
redirect_from: redirect_from:
- /doc/split-bitcoin/ - /doc/split-bitcoin/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md
ref: 77
title: Split Bitcoin
--- ---

7
external/troubleshooting/application-troubleshooting.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Application Troubleshooting
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md
redirect_from: redirect_from:
- /doc/application-troubleshooting/ - /doc/application-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md
ref: 236
title: Application Troubleshooting
--- ---

7
external/troubleshooting/intel-igfx-troubleshooting.md vendored
View File

@ -1,8 +1,9 @@
--- ---
lang: en
layout: doc layout: doc
title: Intel Integrated Graphics Troubleshooting
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md
redirect_from: redirect_from:
- /doc/intel-igfx-troubleshooting/ - /doc/intel-igfx-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md
ref: 90
title: Intel Integrated Graphics Troubleshooting
--- ---

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