Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-06 05:34:27 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'main' into patch-20

Browse source
This commit is contained in:
Dr. Gerhard Weck 2025-07-24 17:41:35 +02:00 • committed by GitHub
commit ed1e54b7ed
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
184 changed files with 4744 additions and 2662 deletions
Download patch file Download diff file Expand all files Collapse all files

2
_dev/conf.py
View file

@ -186,7 +186,7 @@ htmlhelp_basename = 'QubesOSdev'
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
'python': ('https://docs.python.org/', None),
# 'core-admin': ('https://dev.qubes-os.org/projects/core-admin/en/latest/', None),
}

84
developer/building/development-workflow.md
View file

@ -12,42 +12,41 @@ title: Development workflow
A workflow for developing Qubes OS+
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
assumes you're using qubes-builder to build Qubes.
To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
assumes you're using qubes-builder v2 to build Qubes.
## Repositories and committing Code
Qubes is split into a bunch of git repos. These are all contained in the
`qubes-src` directory under qubes-builder. Subdirectories there are separate
components, stored in separate git repositories.
Qubes source code is split into many git repos. These are all contained in the
`artifacts/sources` directory under qubes-builder. Subdirectories there are
separate components, stored in separate git repositories.
The best way to write and contribute code is to create a git repo somewhere
(e.g., github) for the repo you are interested in editing (e.g.,
(e.g., GitHub) for the repo you are interested in editing (e.g.,
`qubes-manager`, `core-agent-linux`, etc). To integrate your repo with the rest
of Qubes, cd to the repo directory and add your repository as a remote in git
**Example:**
~~~
$ cd qubes-builder/qubes-src/qubes-manager
$ git remote add abel git@github.com:abeluck/qubes-manager.git
$ cd qubes-builder/artifacts/sources/qubes-manager
$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git
~~~
You can then proceed to easily develop in your own branches, pull in new
commits from the dev branches, merge them, and eventually push to your own repo
on github.
commits from the dev branches, merge them, and eventually push to your own repo.
When you are ready to submit your changes to Qubes to be merged, push your
changes, then create a signed git tag (using `git tag -s`). Finally, send a
letter to the Qubes listserv describing the changes and including the link to
your repository. You can also create pull request on github. Don't forget to
include your public PGP key you use to sign your tags.
letter to the Qubes listserv describing the changes, and including a link to
your repository. If you are using GitHub you can instead create a pull request.
Don't forget to include the public PGP key you use to sign your tags.
### Kernel-specific notes
#### Prepare fresh version of kernel sources, with Qubes-specific patches applied
In qubes-builder/qubes-src/linux-kernel:
In `qubes-builder/artifacts/sources/linux-kernel`:
~~~
make prep
@ -66,7 +65,7 @@ drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
#### Go to the kernel tree and update the version
In qubes-builder/qubes-src/linux-kernel:
In `qubes-builder/artifacts/sources/linux-kernel`:
~~~
cd kernel-3.4.18/linux-3.4.18
@ -74,14 +73,14 @@ cd kernel-3.4.18/linux-3.4.18
#### Changing the config
In kernel-3.4.18/linux-3.4.18:
In `kernel-3.4.18/linux-3.4.18`:
~~~
cp ../../config .config
make oldconfig
~~~
Now change the configuration. For example, in kernel-3.4.18/linux-3.4.18:
Now change the configuration. For example, in `kernel-3.4.18/linux-3.4.18`:
~~~
make menuconfig
@ -117,9 +116,7 @@ vi series.conf
#### Building RPMs
TODO: Is this step generic for all subsystems?
Now it is a good moment to make sure you have changed kernel release name in
Now is a good moment to make sure you have changed the kernel release name in
rel file. For example, if you change it to '1debug201211116c' the
resulting RPMs will be named
'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help
@ -131,34 +128,23 @@ your changes locally.
To actually build RPMs, in qubes-builder:
~~~
make linux-kernel
./qb -c linux-kernel package fetch prep build
~~~
RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
RPMs will appear in
`artifacts/repository/destination_name/package_name`
(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/`
~~~
-rw-rw-r-- 1 user user 42996126 Nov 17 04:08 kernel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 43001450 Nov 17 05:36 kernel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 8940138 Nov 17 04:08 kernel-devel-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 8937818 Nov 17 05:36 kernel-devel-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 54490741 Nov 17 04:08 kernel-qubes-vm-3.4.18-1debug20121116c.pvops.qubes.x86_64.rpm
-rw-rw-r-- 1 user user 54502117 Nov 17 05:37 kernel-qubes-vm-3.4.18-1debug20121117a.pvops.qubes.x86_64.rpm
~~~
### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands
### Useful [QubesBuilder](/doc/qubes-builder/) commands
1. `make check` - will check if all the code was committed into repository and
if all repository are tagged with signed tag.
2. `make show-vtags` - show version of each component (based on git tags) -
mostly useful just before building ISO. **Note:** this will not show version
for components containing changes since last version tag.
3. `make push` - push change from **all** repositories to git server. You must
set proper remotes (see above) for all repositories first.
4. `make prepare-merge` - fetch changes from remote repositories (can be
specified on commandline via GIT\_SUBDIR or GIT\_REMOTE vars), (optionally)
verify tags and show the changes. This do not merge the changes - there are
left for review as FETCH\_HEAD ref. You can merge them using `git merge
FETCH_HEAD` (in each repo directory). Or `make do-merge` to merge all of them.
1. `./qb package diff` - show uncommitted changes
2. ` ./qb repository check-release-status-for-component` and
`./qb repository check-release-status-for-template` - show version of each
component/template (based on git tags)
3. `./qb package sign` - sign built packages
4. `./qb package publish` and `./qb package upload` - publish signed packages
and upload published
repository
## Copying Code to dom0
@ -297,12 +283,12 @@ if [ "$1" = "tb" ]; then
exit $?
fi
git remote add $1 git@github.com:$1/qubes-`basename $PWD`
git remote add $1 git@GitHub.com:$1/qubes-`basename $PWD`
~~~
It should be executed from component top level directory. This script takes one
argument - remote name. If it is `tb`, then it creates qrexec-based git remote
to `testbuilder` VM. Otherwise it creates remote pointing at github account of
to `testbuilder` VM. Otherwise it creates remote pointing at GitHub account of
the same name. In any case it points at repository matching current directory
name.
@ -321,7 +307,7 @@ current and current-testing).
### RPM packages - yum repo
In source VM, grab [linux-yum](https://github.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
In source VM, grab [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) repository (below is assumed you've made it in
`~/repo-yum-upload` directory) and replace `update_repo.sh` script with:
~~~
@ -337,7 +323,7 @@ find -type f -name '*.rpm' -delete
qrexec-client-vm $VMNAME local.UpdateYum
~~~
In target VM, setup actual yum repository (also based on [linux-yum](https://github.com/QubesOS/qubes-linux-yum), this time
In target VM, setup actual yum repository (also based on [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum), this time
without modifications). You will also need to setup some gpg key for signing
packages (it is possible to force yum to install unsigned packages, but it
isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
@ -417,7 +403,7 @@ Remember to also import gpg public key using `rpm --import`.
Steps are mostly the same as in the case of yum repo. The only details that differ:
- use [linux-deb](https://github.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://github.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
- use [linux-deb](https://GitHub.com/QubesOS/qubes-linux-deb) instead of [linux-yum](https://GitHub.com/QubesOS/qubes-linux-yum) as a base - both in source and target VM
- use different `update_repo.sh` script in source VM (below)
- use `local.UpdateApt` qrexec service in target VM (code below)
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)

6
developer/building/qubes-builder-details.md
View file

@ -10,6 +10,12 @@ ref: 65
title: Qubes builder details
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> This information concerns the old Qubes builder (v1). It supports
only building Qubes 4.1 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.1 and later, and all related components.</div>
Components Makefile.builder file
--------------------------------

166
developer/building/qubes-builder-v2.md Normal file
View file

@ -0,0 +1,166 @@
---
lang: en
layout: doc
permalink: /doc/qubes-builder-v2/
redirect_from:
- /en/doc/qubes-builder-v2/
- /doc/QubesBuilder2/
- /wiki/QubesBuilder2/
ref: 311
title: Qubes builder v2
---
This is a brief introduction to using Qubes Builder v2 to work with Qubes OS
sources. It will walk you through installing and configuring Builder v2, and
using it to fetch and build Qubes OS packages.
For details and customization, use [Qubes OS v2 builder documentation](https://github.com/QubesOS/qubes-builderv2/).
# Overview
In the second generation of Qubes OS builder, container or disposable qube
isolation is used to perform every stage of the build and release process.
From fetching sources to building, everything is executed inside an isolated
*cage* (either a disposable or a container) using an *executor*. For every
command that needs to perform an action on sources, like cloning and
verifying Git repos, rendering a SPEC file, generating SRPM or Debian
source packages, a new cage is used. Only the signing, publishing, and
uploading stages are executed locally outside a cage.
# Setup
This is a simple setup using a docker executor. This is a good default choice;
if you don't know which executor to use, use docker.
1. First, decide what qube you are going to use when working with Qubes
Builder v2. It can be an AppVM or a Standalone qube, with some steps
different between the two.
2. Installing dependencies
- If you want to use an app qube for developing, install dependencies in the template.
If you are using a standalone, install them in the qube itself.
Dependencies are specified in `dependencies-*.
txt` files in the main builder directory, and you can install them easily
in the following ways:
1. for Fedora, use:
```shell
$ sudo dnf install $(cat dependencies-fedora.txt)
$ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
```
2. for Debian (note: some Debian packages require Debian version 13 or
later), use:
```shell
$ sudo apt install $(cat dependencies-debian.txt)
$ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
```
If you have installed dependencies in the template, close it, and
(re)start the development qube.
3. Clone the qubes-builder v2 repository into a location of your choice:
```shell
git clone https://github.com/QubesOS/qubes-builderv2
cd qubes-builderv2/
```
4. If you haven't previously used docker in the current qube, you need to set up
some permissions. In particular, the user has to be added to the `docker`
group:
```shell
$ sudo usermod -aG docker user
```
Next, **restart the qube**.
5. Finally, you need to generate a docker image:
```shell
$ tools/generate-container-image.sh docker
```
In an app qube, as `/var/lib/docker` is not persistent by default, you also
need to use [bind-dirs](/doc/bind-dirs/) to avoid repeating this step after reboot, adding
the following to the `/rw/config/qubes-bind-dirs.d/docker.conf` file in
this qube:
```
binds+=( '/var/lib/docker' )
```
# Configuration
To use Qubes OS Builder v2, you need to have a `builder.yml` configuration file.
You can use one of the sample files from the `example-configs/` directory; for a
more readable `builder.yml`, you can also include one of the files from that
directory in your `builder.yml`. An example `builder.yml` is:
```
# include configuration relevant for the current release
include:
- example-configs/qubes-os-r4.2.yml
# which repository to use to fetch sources
use-qubes-repo:
version: 4.2
testing: true
# each package built will have local build number appended to package release
# number. It makes it easier to update in testing environment
increment-devel-versions: true
# reduce output
debug: false
# this can be set to true if you do not want sources to be automatically
# fetched from git
skip-git-fetch: false
# executor configuration
executor:
type: docker
options:
image: "qubes-builder-fedora:latest"
```
# Using Builder v2
To fetch sources - in this example, for the `core-admin-client` package, you
can use the following command:
```shell
$ ./qb -c core-admin-client package fetch
```
This will fetch the sources for the listed package and place them in
`artifacts/sources` directory.
To build a package (from sources in the `artifacts/sources` directory), use:
```shell
$ ./qb -c core-admin-client package fetch prep build
```
or, if you want to build for a specific target (`host-fc37` is a `dom0`
using Fedora 37, `vm-fc40` would be a qube using Fedora 40 etc.), use:
```shell
$ ./qb -c core-admin-client -d host-fc37 package fetch prep build
```
If you want to fetch the entire Qubes OS source use the following:
```shell
$ ./qb package fetch
```
**caution**: some repositories might have additional requirements. You can
disable repositories that are not needed in the `example-configs/*.yml`
file you are using by commenting them out. In particular, `python-fido2`,
`lvm` and `windows`-related repositories have special requirements.

6
developer/building/qubes-builder.md
View file

@ -10,6 +10,12 @@ ref: 64
title: Qubes builder
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
only building Qubes 4.2 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.2 and later, and all related components.
</div>
**Note: See [ISO building instructions](/doc/qubes-iso-building/) for a streamlined overview on how to use the build system.**

6
developer/building/qubes-iso-building.md
View file

@ -12,6 +12,12 @@ ref: 63
title: Qubes ISO building
---
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-circle"></i>
<b>Note:</b> These instructions concern the older Qubes builder (v1). It supports
only building Qubes 4.2 or earlier.<br>The build process has been completely rewritten in <a href="https://github.com/QubesOS/qubes-builderv2/">qubes-builder v2</a>. This can be used for building Qubes R4.2 and later versions, and all related components.
</div>
Build Environment
-----------------

11
developer/code/code-signing.md
View file

@ -65,7 +65,9 @@ Currently, [these](https://github.com/marmarek/signature-checker/blob/master/che
In the example below, we will use `keyserver.ubuntu.com`.
Replace 6E2F4E7AF50A5827 with your key ID, which is the last 8 hex digits of the long number in the second line of the output above:
Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID**
which is the last 16 hex digits of the long number in the second line
of the output above:
```
pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
87975838063F97A968D503266E2F4E7AF50A5827
@ -76,11 +78,6 @@ $ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827
gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com
```
```
$ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827
gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com
```
## Using PGP with Git
If you're submitting a patch via GitHub (or a similar Git server), please sign
@ -147,9 +144,11 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s
1. Is the commit signed?
If the commit is not signed, you can see the message
> policy/qubesos/code-signing — No signature found
2. If the commit is signed, the key is downloaded from a GPG key server.
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)
### No Signature Found

1
developer/code/source-code.md
View file

@ -60,6 +60,7 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b
* **Preferred**: Use GitHub's [fork & pull requests](https://guides.github.com/activities/forking/).
Opening a pull request on GitHub greatly eases the code review and tracking
process. In addition, especially for bigger changes, it's a good idea to send
a message to the [qubes-devel mailing list](/support/#qubes-devel) in order to notify people who

4
developer/debugging/automated-tests.md
View file

@ -132,7 +132,7 @@ Whereas integration tests are mostly stored in the [qubes-core-admin](https://gi
To for example run the `qubes-core-admin` unit tests, you currently have to clone at least [qubes-core-admin](https://github.com/QubesOS/qubes-core-admin) and
its dependency [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec) repository in the branches that you want to test.
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-v2/).
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:
@ -267,11 +267,13 @@ It feeds off of the openQA test data to make graph plots. Here is an example:
![openqa-investigator-splitgpg-example.png](/attachment/doc/openqa-investigator-splitgpg-example.png)
Some outputs:
- plot by tests
- plot by errors
- markdown
Some filters:
- filter by error
- filter by test name

5
developer/debugging/test-bench.md
View file

@ -205,9 +205,10 @@ pushd ${HOME}/builder >/dev/null
# the following are needed only if you have sources outside builder
#rm -rf qubes-src/core-admin
#make COMPONENTS=core-admin get-sources
#qb -c core-admin package fetch
make core-admin
qb -c core-admin -d host-fc41 prep build
# update your dom0 fedora distribution as appropriate
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
qtb-runtests
```

5
developer/debugging/vm-interface.md
View file

@ -22,18 +22,19 @@ Qubes VM have some settings set by dom0 based on VM settings. There are multiple
### Keys exposed by dom0 to VM
- `/qubes-base-template` - base template
- `/qubes-vm-type` - VM type, the same as `type` field in `qvm-prefs`. One of `AppVM`, `ProxyVM`, `NetVM`, `TemplateVM`, `HVM`, `TemplateHVM`
- `/qubes-vm-updatable` - flag whether VM is updatable (whether changes in root.img will survive VM restart). One of `True`, `False`
- `/qubes-vm-persistence` - what data do persist between VM restarts:
- `full` - all disks
- `rw-only` - only `/rw` disk
- `none` - none
- `/qubes-timezone - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-timezone` - name of timezone based on dom0 timezone. For example `Europe/Warsaw`
- `/qubes-keyboard` (deprecated in R4.1) - keyboard layout based on dom0 layout. Its syntax is suitable for `xkbcomp` command (after expanding escape sequences like `\n` or `\t`). This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does). This entry is created as part of gui-daemon initialization (so not available when gui-daemon disabled, or not started yet).
- `/keyboard-layout` - keyboard layout based on GuiVM layout. Its syntax can be `layout+variant+options`, `layout+variant`, `layout++options` or simply `layout`. For example, `fr+oss`, `pl++compose:caps` or `fr`. This is meant only as some default value, VM can ignore this option and choose its own keyboard layout (this is what keyboard setting from Qubes Manager does).
- `/qubes-debug-mode` - flag whether VM has debug mode enabled (qvm-prefs setting). One of `1`, `0`
- `/qubes-service/SERVICE_NAME` - subtree for VM services controlled from dom0 (using the `qvm-service` command or Qubes Manager). One of `1`, `0`. Note that not every service will be listed here, if entry is missing, it means "use VM default". A list of currently supported services is in the `qvm-service` man page.
- `/qubes-netmask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-netm ask` - network mask (only when VM has netvm set); currently hardcoded "255.255.255.0"
- `/qubes-ip` - IP address for this VM (only when VM has netvm set)
- `/qubes-gateway` - default gateway IP (only when VM has netvm set); VM should add host route to this address directly via eth0 (or whatever default interface name is)
- `/qubes-primary-dns` - primary DNS address (only when VM has netvm set)

291
developer/debugging/windows-debugging.md
View file

@ -10,253 +10,80 @@ ref: 50
title: Windows debugging
---
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 Qubes 4.2 and Windows 7 or later VMs.
User-mode debugging is usually straightforward if it can be done on one machine. Just duplicate your normal debugging environment in the VM.
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 the debugger, your source code and private symbols. The *target* will run the code being debugged. We will use kernel debugging over network which is supported from Windows 7 onwards. The main caveat is that Windows kernel supports only specific network adapters for this, and the default one in Qubes won't work.
- First, you need to prepare separate copies of both *target* and *host* VM configuration files with some changes. Copy the files from **/var/lib/qubes/appvms/vmname/vmname.conf** to some convenient location, let's call them **host.conf** and **target.conf**.
- In both copied files add the following line at the end: `serial = 'pty'`. This will make Xen connect VM's serial ports to dom0's ptys.
- From now on you need to start both VMs like this: `qvm-start --custom-config=/your/edited/host.conf host`
- To connect both VM serial ports together you will either need [socat](http://www.dest-unreach.org/socat/) or a custom utility described later.
- To determine which dom0 pty corresponds to VM's serial port you need to read xenstore, example script below:
## Important note
```bash
#!/bin/sh
- Do not install Xen network PV drivers in the target VM. Network kernel debugging needs a specific type of NIC or it won't work, the network PV drivers interfere with that.
id1=$(xl domid "$1-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
echo $tty1
```
- If you have kernel debugging active when the Xen PV drivers are being installed, make sure to disable it before rebooting (`bcdedit /set debug off`). You can re-enable debugging after the reboot. The OS won't boot otherwise. I'm not sure what's the exact cause. I know that busparams for the debugging NIC change when PV drivers are installed (see later), but even changing that accordingly in the debug settings doesn't help -- so it's best to disable debug for this one reboot.
Pass it a running VM name and it will output the corresponding pty name.
## Modifying the NIC of the target VM
- To connect both ptys you can use [socat](http://www.dest-unreach.org/socat/) like that:
You will need to create a custom libvirt config for the target VM. See [the documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/libvirt.html) for overview of how libvirt templates work in Qubes. The following assumes the target VM is named `target-vm`.
```bash
#!/bin/sh
- Edit `/usr/share/qubes/templates/libvirt/xen.xml` to prepare our custom config to override just the NIC part of the global template:
- add `{% raw %}{% block network %}{% endraw %}` before `{% raw %}{% if vm.netvm %}{% endraw %}`
- add `{% raw %}{% endblock %}{% endraw %}` after the matching `{% raw %}{% endif %}{% endraw %}`
- Copy `/usr/share/qubes/templates/libvirt/devices/net.xml` to `/etc/qubes/templates/libvirt/xen/by-name/target-vm.xml`.
- Add `<model type='e1000'/>` to the `<interface>` section.
- Enclose everything within `{% raw %}{% block network %}{% endraw %}` + `{% raw %}{% endblock %}{% endraw %}`.
- Add `{% raw %}{% extends 'libvirt/xen.xml' %}{% endraw %}` at the start.
- The final `target-vm.xml` should look something like this:
id1=$(xl domid "$1-dm")
id2=$(xl domid "$2-dm")
tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
socat $tty1,raw $tty2,raw
```
~~~
{% raw %}
{% extends 'libvirt/xen.xml' %}
{% block network %}
<interface type='ethernet'>
<mac address="{{ vm.mac }}" />
<ip address="{{ vm.ip }}" />
<backenddomain name="{{ vm.netvm.name }}" />
<script path='vif-route-qubes' />
<model type='e1000' />
</interface>
{% endblock %}
{% endraw %}
~~~
...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.
- Start `target-vm` and verify in the device manager that a "Intel PRO/1000 MT" adapter is present.
- On the *target* system, run `bcdedit /set debug on` on the console to turn on kernel debugging. It defaults to the first serial port.
- On the *host* system, install [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx) and start the kernel debug (Ctrl-K), choose **com1** as the debug port.
- Reboot the *target* VM.
- Run the above shell script in dom0.
- If everything is fine you should see the proper kernel debugging output in WinDbg. However, if you see something like that:
## Host and target preparation
- On `host-vm` you will need WinDbg, which is a part of the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
- Copy the `Debuggers` directory from Windows SDK to `target-vm`.
- In both `host-vm` and `target-vm` switch the windows network to private (it tends to be public by default).
- Either turn off the windows firewall or enable all ICMP-in rules in both VMs.
- In `firewall-vm` edit `/rw/config/qubes-firewall-user-script` to connect both Windows VMs, add:
- `iptables -I FORWARD 2 -s <target-vm-ip> -d <host-vm-ip> -j ACCEPT`
- `iptables -I FORWARD 2 -s <host-vm-ip> -d <target-vm-ip> -j ACCEPT`
- run `/rw/config/qubes-firewall-user-script` so the changes take effect immediately
- Make sure both VMs can ping each other.
- In `target-vm`:
- start elevated `cmd` session
- `cd sdk\Debuggers\x64`
- `kdnet` should show that the NIC is supported, note the busparams:
~~~
Network debugging is supported on the following NICs:
busparams=0.6.0, Intel(R) PRO/1000 MT Network Connection, KDNET is running on this NIC.
~~~
- `bcdedit /debug on`
- `bcdedit /dbgsettings net hostip:<host-vm-ip> port:50000 key:1.1.1.1` (you can customize the key)
- `bcdedit /set "{dbgsettings}" busparams x.y.z` (use the busparams `kdnet` has shown earlier)
- In `host-vm` start WinDbg: `windbg -k net:port=50000,key=1.1.1.1`. It will listen for target's connection.
- Reboot `target-vm`, debugging should start:
~~~
Opened \\.\com1
Waiting to reconnect...
Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:35:43.262 2014 (UTC + 1:00)), ptr64 TRUE
Kernel Debugger connection established.
Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
Executable search path is:
... Retry sending the same data packet for 64 times.
The transport connection between host kernel debugger and target Windows seems lost.
please try resync with target, recycle the host debugger, or reboot the target Windows.
Unable to read KTHREAD address fffff8000281ccc0
**************************************************************************
Unable to read debugger data block header
**************************************************************************
Unable to read KTHREAD address fffff8000281ccc0
Unable to read PsLoadedModuleList
Unable to read KTHREAD address fffff8000281ccc0
**************************************************************************
Unable to read debugger data block header
**************************************************************************
Connected to target 10.137.0.19 on port 50000 on local IP 10.137.0.20.
You can get the target MAC address by running .kdtargetmac command.
Connected to Windows 10 19041 x64 target at (Thu Aug 3 14:05:48.069 2023 (UTC + 2:00)), ptr64 TRUE
~~~
...then you're most likely a victim of the CRLF issue mentioned above. To get around it I wrote a small utility that basically does what socat would do and additionally corrects those replaced bytes in the stream. It's not pretty but it works:
```c
#include <errno.h>
#include <stdio.h>
#include <fcntl.h>
#include <termios.h>
int fd1, fd2;
char mark = ' ';
void out(unsigned char c)
{
static int count = 0;
static unsigned char buf[17] = {0};
// relay to ouptput port
write(fd2, &c, 1);
fprintf(stderr, "%c", mark);
/* dump all data going over the line
if (count == 0)
fprintf(stderr, "%c", mark);
fprintf(stderr, "%02x ", c);
if (c >= 0x20 && c < 0x80)
buf[count] = c;
else
buf[count] = '.';
count++;
if (count == 0x10)
{
count = 0;
fprintf(stderr, " %s\n", buf);
}
*/
}
int main(int argc, char* argv[])
{
unsigned char c = 0;
struct termios tio;
ssize_t size;
if (argc < 3)
{
fprintf(stderr, "Usage: %s pty1 pty2 [mark character]\n", argv[0]);
return EINVAL;
}
fd1 = open(argv[1], O_RDONLY | O_NOCTTY);
if (fd1 <= 0)
{
perror("open fd1");
return errno;
}
fd2 = open(argv[2], O_WRONLY | O_NOCTTY);
if (fd2 <= 0)
{
perror("open fd2");
return errno;
}
/*
// This doesn't make any difference which supports the theory
// that it's Xen who corrupts the byte stream.
cfmakeraw(&tio);
if (tcsetattr(fd1, TCSANOW, &tio) < 0)
{
perror("tcsetattr 1");
return errno;
}
if (tcsetattr(fd2, TCSANOW, &tio) < 0)
{
perror("tcsetattr 2");
return errno;
}
*/
if (argc == 4)
mark = argv[3][0];
while (1)
{
size = read(fd1, &c, 1);
if (size <= 0)
break;
parse:
if (c == 0x0d)
{
size = read(fd1, &c, 1);
if (size <= 0)
{
out(0x0d);
break;
}
if (c == 0x0a)
{
out(0x0a);
}
else
{
out(0x0d);
goto parse;
}
}
else
out(c);
}
close(fd1);
close(fd2);
return 0;
}
```
> This utility is a unidirectional relay so you need to run two instances to get duplex communication, like:
>
> #!/bin/sh
>
> id1=$(xl domid "$1-dm")
> id2=$(xl domid "$2-dm")
> tty1=$(xenstore-read /local/domain/${id1}/device/console/3/tty)
> tty2=$(xenstore-read /local/domain/${id2}/device/console/3/tty)
> ./ptycrlf ${tty1} ${tty2} - &
> ./ptycrlf ${tty2} ${tty1} + &
> With this everything should be good:
>
> ~~~
> Opened \\.\com1
> Waiting to reconnect...
> Connected to Windows 7 7601 x64 target at (Wed Mar 19 20:56:31.371 2014 (UTC + 1:00)), ptr64 TRUE
> Kernel Debugger connection established.
> Symbol search path is: srv*c:\symbols*http://msdl.microsoft.com/download/symbols
> Executable search path is:
> Windows 7 Kernel Version 7601 MP (1 procs) Free x64
> Built by: 7601.18247.amd64fre.win7sp1_gdr.130828-1532
> Machine Name:
> Kernel base = 0xfffff800`0261a000 PsLoadedModuleList = 0xfffff800`0285d6d0
> System Uptime: not available
> ~~~
# Debugging HVMs in the Qubes 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
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.
1. Unpack stub domain in dom0:
```shell_session
$ mkdir stubroot
$ cp /usr/lib/xen/boot/stubdom-linux-rootfs stubroot/stubdom-linux-rootfs.gz
$ cd stubroot
$ gunzip stubdom-linux-rootfs.gz
$ cpio -i -d -H newc --no-absolute-filenames < stubdom-linux-rootfs
$ rm stubdom-linux-rootfs
```
2. Edit Init script to remove last loop and to add "-serial /dev/hvc0" to the qemu command line.
3. Apply changes:
```shell_session
$ find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../stubdom-linux-rootfs
$ sudo mv ../stubdom-linux-rootfs /usr/lib/xen/boot
```
## Connect two consoles
Run the following script:
```shell
debugname1=win7new
debugname2=win7dbg
id1=$(xl domid "$debugname1-dm")
id2=$(xl domid "$debugname2-dm")
tty1=$(xenstore-read /local/domain/${id1}/console/tty)
tty2=$(xenstore-read /local/domain/${id1}/console/tty)
socat $tty1,raw $tty2,raw
```
Happy debugging!

4
developer/general/devel-books.md
View file

@ -26,6 +26,6 @@ Below is a list of various books that might be useful in learning some basics ne
- _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
- Useful books about Python:
- _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
- _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
- _[Programming in Python 3](https://www.qtrac.eu/py3book.html)_, by Mark Summerfield
- _[Rapid GUI Programming with Python and Qt](https://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.)

2
developer/general/developing-gui-applications.md
View file

@ -59,7 +59,7 @@ If error should be thrown, you need to provide the error code and name, for exam
b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00'
```
For details of particular calls, you can use [Extending the mock Qubes object].
For details of particular calls, you can use [Extending the mock Qubes object](#extending-the-mock-qubes-object).
## Available mocks

2
developer/general/documentation-style-guide.md
View file

@ -262,7 +262,7 @@ Duplicating documentation is almost always a bad idea. There are many reasons fo
### Core vs. external documentation
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Community](https://github.com/Qubes-Community) project. External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Community](https://github.com/Qubes-Community) project instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Community](https://github.com/Qubes-Community) project should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Community links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents.
Core documentation resides in the [Qubes OS Project's official repositories](https://github.com/QubesOS/), mainly in [qubes-doc](https://github.com/QubesOS/qubes-doc). External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the [Qubes Forum](https://forum.qubes-os.org/docs). External documentation should not be submitted to [qubes-doc](https://github.com/QubesOS/qubes-doc). If you've written a piece of documentation that is not appropriate for [qubes-doc](https://github.com/QubesOS/qubes-doc), we encourage you to submit it to the [Qubes Forum](https://forum.qubes-os.org/docs) instead. However, *linking* to external documentation from [qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed, the maintainers of the [Qubes Forum](https://forum.qubes-os.org/) should regularly submit PRs against the documentation index (see [How to edit the documentation index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index)) to add and update Qubes Forum links in the ["External documentation"](/doc/#external-documentation) section of the documentation table of contents.
The main difference between **core** (or **official**) and **external** (or **community** or **unofficial**) documentation is whether it documents software that is officially written and maintained by the Qubes OS Project. The purpose of this distinction is to keep the core docs maintainable and high-quality by limiting them to the software output by the Qubes OS Project. In other words, we take responsibility for documenting all of the software we put out into the world, but it doesn't make sense for us to take on the responsibility of documenting or maintaining documentation for anything else. For example, Qubes OS may use a popular Linux distribution for an official [TemplateVM](/doc/templates/). However, it would not make sense for a comparatively small project like ours, with modest funding and a lean workforce, to attempt to document software belonging to a large, richly-funded project with an army of paid and volunteer contributors, especially when they probably already have documentation of their own. This is particularly true when it comes to Linux in general. Although many users who are new to Qubes are also new to Linux, it makes absolutely no sense for our comparatively tiny project to try to document Linux in general when there is already a plethora of documentation out there.

106
developer/general/gsoc.md
View file

@ -31,7 +31,7 @@ You should start learning the components that you plan on working on before the
Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from prospective contributors who have already started to act like free and open source developers.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22) (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder](/doc/qubes-builder-v2/), our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
### Contributor proposal guidelines
@ -174,45 +174,6 @@ If applicable, links to more information or discussions
**Mentor**: [Frédéric Pierret](/team/)
<!--
REMOVED as of February 2022: work is being done on this
### Wayland support in GUI agent and/or GUI daemon
**Project**: Wayland support in GUI agent and/or GUI daemon
**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects:
1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver
2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied)
**Expected results**:
Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period.
- design relevant GUI agent/daemon changes, the GUI protocol should not be affected
- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon)
- implement relevant GUI agent/daemon changes
- implement tests for new GUI handling, similar to existing tests for X11 based GUI
Relevant links:
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
**Knowledge prerequisite**:
- Wayland architecture
- basics of X11 (for understanding existing code)
- C language
- using shared memory (synchronization methods etc)
**Mentor**: [Marek Marczykowski-Górecki](/team/).
-->
### Qubes Live USB
@ -252,26 +213,6 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
**Mentor**: [Frédéric Pierret](/team/)
<!--
### Unikernel-based firewallvm with Qubes firewall settings support
REMOVED as of January 2020: work is being done on this
**Project**: Unikernel based firewallvm with Qubes firewall settings support
**Brief explanation**: [blog post](http://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
**Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first.
**Knowledge prerequisite**:
- [OCaml](https://ocaml.org/) + [MirageOS](https://mirage.io/) or other unikernel framework,
- Xen network stack,
- Qubes networking model & firewall semantics.
**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
-->
### LogVM(s)
**Project**: LogVM(s)
@ -422,7 +363,7 @@ for more information and qubes-specific background.
**Difficulty**: medium
**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder-v2/) [[2]](https://github.com/QubesOS/qubes-builderv2), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Size of the project**: 350 hours
@ -461,44 +402,6 @@ Some related discussion:
**Mentor**: [Marek Marczykowski-Górecki](/team/)
<!--
REMOVED as of February 2021: work is being done on this
### Porting Qubes to POWER9/PPC64
**Project**: Porting Qubes to POWER9/ppc64
**Brief explanation**:
Qubes currently supports the x86_64 CPU architecture. PowerPC is desirable for security purposes as it is the only architecture where one can get performant hardware with entirely open source firmware. Xen has **deprecated** support for Power9/PPC64 processors. Here are two directions to tackle this project from:
- Port Qubes to KVM then work on ppc64 specifics
- Implement some missing functionality in KVM then implement KVM support in the Qubes Hypervisor Abstraction Layer and build process. Improving the HAL will also be beneficial for simplifying the process of porting to further architectures and hypervisors.
- Port Xen to ppc64 then work on Qubes specifics
- For more information on porting Xen see [this thread](https://markmail.org/message/vuk7atnyqfq52epp).
More information and further links can be found in the related issue:
[#4318](https://github.com/QubesOS/qubes-issues/issues/4318).
**Expected results**:
- Add cross-compilation support to qubes-builder and related components.
- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals
- General ppc64 architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
-->
### Android development in Qubes
**Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio
@ -538,12 +441,14 @@ Since the Admin API is continuously growing and changing, continuous security as
A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments.
**Expected results**:
- fully automated & extensible Fuzzer for parts of the Admin API
- user & developer documentation
**Difficulty**: medium
**Prerequisites**:
- basic Python understanding
- some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os))
- a hacker's curiosity
@ -560,6 +465,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
**Brief explanation**: Since recently, Xen supports "unified EFI boot" which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in [issue #4371](https://github.com/QubesOS/qubes-issues/issues/4371)
**Expected results**:
- a tool to prepare relevant boot files for unified Xen EFI boot - this includes collecting Xen, dom0 kernel, initramfs, config file, and possibly few more (ucode update?); the tool should then sign the file with user provided key (preferably propose to generate it too)
- integrate it with updates mechanism, so new Xen or dom0 kernel will be picked up automatically
- include a fallback configuration that can be used for troubleshooting (main unified Xen EFI intentionally does not allow to manipulate parameters at boot time)
@ -567,6 +473,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
**Difficulty**: hard
**Knowledge prerequisite**:
- basic understanding of Secure Boot
- Bash and Python scripting
@ -586,6 +493,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of
**Difficulty**: medium
**Knowledge prerequisite**:
- Python scripting
- Basic knowledge of Linux system services management (systemd, syslog etc)

90
developer/general/gsod.md
View file

@ -6,9 +6,9 @@ ref: 242
title: Google Season of Docs (GSoD)
---
Thank you for your interest in participating in the [2023 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2023 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
Thank you for your interest in participating in the [2024 Google Season of Docs](https://developers.google.com/season-of-docs/) program with the [Qubes OS team](/team/). This page details our 2024 project idea as well as completed past projects. You can read more about the Google Season of Docs in the official [guides](https://developers.google.com/season-of-docs/docs/) and [FAQ](https://developers.google.com/season-of-docs/docs/faq).
## Instructional video series -- Qubes OS
## Update and Expand How-To Guides -- Qubes OS
### About the Qubes OS Project
@ -18,10 +18,62 @@ Qubes OS was launched in 2011 and has [received praise from security experts and
### The project's problem
There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with.
- Some of the existing content is stale. It refers to previous Qubes releases and has not yet been updated to the cover the latest stable release.
- There are important topic areas that the current guides do not completely cover, such as "understanding Qubes OS," "using Qubes OS in practice," "Qubes OS workflow for coding," "printing," and "audio."
- The guides do not consistently address users of all skill and experience levels (beginner, intermediate, and expert).
- Some of the guides lack relevant illustrations and screenshots.
- When the developers update a software tool, they should update all the guides that mentions this tool. However, there is currently no way for the developers to know which guides mention which tools.
### The project's scope
The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, Marta Marczykowska-Górecka, and Marek Marczykowski-Górecki, will supervise and support the writer.
### Measuring the project's success
We will consider the project successful if:
- Existing guides are updated to describe currently supported Qubes OS version
- Missing common guides are identified
- 2-3 new guides are written
### Timeline
| Dates | Action items |
| --------------- | --------------------------------------- |
| May | Orientation |
| June - November | Update & extend how-to guides |
| December | Final project evaluation and case study |
### Project budget
| Expense | Amount |
| --------------------------------------- | ------- |
| writer (10 hours/week, 6 months) | $12,000 |
| TOTAL | $12,000 |
### Additional information
Qubes OS regularly participates in Google Summer of Code and Google Season of Docs. This is our third time participating in Google Season of Docs. Our mentorships for GSoD 2019, 2020, and 2023 were successes, and the projects were completed within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers and have helped us to understand the benefits that technical writers can bring to our project.
## Past Projects
You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/).
You can view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://web.archive.org/web/20210723170547/https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
You can view the results of the project we had in 2023 [here](https://www.youtube.com/playlist?list=PLjwSYc73nX6aHcpqub-6lzJbL0vhLleTB).
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
### Instructional video series
#### The project's problem
There is user demand for high-quality, up-to-date video guides that take users from zero Linux knowledge to using Qubes as a daily driver and performing specific tasks inside of Qubes, but almost no such videos exist. Although most of the required knowledge is documented, many users report that they would prefer to watch videos rather than read text or that they would find videos easier to understand and follow along with.
#### The project's scope
This project consists of creating a series of instructional videos that satisfy the following criteria:
- Prospective users who are not yet familiar with Linux or Qubes OS can easily understand and follow the videos.
@ -59,7 +111,7 @@ Below is an example of the content (which is already [documented](/doc/)) that t
- Passwordless root
- Anti Evil Maid
- Split GPG
- U2F proxy
- CTAP proxy
- YubiKey
- Whonix
- How to install and use a VPN in Qubes
@ -68,7 +120,7 @@ Below is an example of the content (which is already [documented](/doc/)) that t
The project is estimated to need around six months to complete (see the timeline below). Qubes team members, including Michael Carbone, Andrew Wong, and Marek Marczykowski-Górecki, will supervise and support the creator.
### Measuring the project's success
#### Measuring the project's success
We will consider the project successful if, after publication of the video series:
@ -76,34 +128,6 @@ We will consider the project successful if, after publication of the video serie
- The reception to the videos is generally positive and complaints about quality and accuracy are minimal.
- Appropriate analytics (e.g., YouTube metrics) are average or better for videos of this type (to be determined in consultation with the creator).
### Timeline
| Dates | Action items |
| -------------- | --------------------------------------- |
| March | Orientation |
| April--October | Create Qubes OS video series |
| November | Final project evaluation and case study |
### Project budget
| Expense | Amount |
| --------------------------------------- | ------- |
| Video creator (20 hours/week, 6 months) | $12,000 |
| TOTAL | $12,000 |
### Additional information
Qubes OS regularly participates in Google Summer of Code and Google Season of Docs. This is our third time participating in Google Season of Docs. Our mentorships for GSoD 2019 and 2020 were successes, and both projects were completed within the times allotted. The past Google Season of Docs projects have given us experience in working with technical writers and have helped us to understand the benefits that technical writers can bring to our project. While our experience in working with video creators is more limited, we are keenly aware of the benefits of high-quality video content, as well as the significant time, resources, and talent required to create it.
## Past Projects
You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
You can also view the project we had in 2020 in the [2020 GSoD archive](https://developers.google.com/season-of-docs/docs/2020/participants/project-qubesos-c1e0) and the [2020 writer's report](https://gist.github.com/PROTechThor/bfe9b8b28295d88c438b6f6c754ae733).
Here are some successful projects which have been implemented in the past by Google Season of Docs participants.
### Consolidate troubleshooting guides
**Project**: Consolidate troubleshooting guides

2
developer/general/package-contributions.md
View file

@ -71,7 +71,7 @@ The review procedure is as follows:
1. Someone, S, wishes to make a change to a package, P.
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib](https://github.com/QubesOS-contrib).
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
If the pull request passes the PM's review, the PM adds a [signed](/doc/code-signing/) *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed](/doc/code-signing/) *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.

2
developer/releases/2_0/release-notes.md
View file

@ -68,7 +68,7 @@ Note: if the user has custom Template VMs (i.e. other than the default template,
#### From Qubes R1 to R2 beta1
If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here?](/doc/upgrade-to-r2/).
If you're already running Qubes Release 1, you don't need to reinstall, it's just enough to update the packages in your Dom0 and the template VM(s). This procedure is described [here](/doc/upgrade-to-r2/).
#### From Qubes R1 or R2 Beta 1 to R2 beta2

2
developer/releases/4_0/release-notes.md
View file

@ -9,7 +9,7 @@ title: Qubes R4.0 release notes
New features since 3.2
----------------------
* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)
* Core management scripts rewrite with better structure and extensibility, [current API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/) and the documentation API index as a [webarchive](https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)
* [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0
* All `qvm-*` command-line tools rewritten, some options have changed
* Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM

31
developer/releases/4_2/release-notes.md
View file

@ -1,6 +1,6 @@
---
layout: doc
title: Qubes OS 4.2.0 release notes
title: Qubes OS 4.2 release notes
permalink: /doc/releases/4.2/release-notes/
---
@ -16,6 +16,7 @@ permalink: /doc/releases/4.2/release-notes/
- Qubes Global Settings ([#6898](https://github.com/QubesOS/qubes-issues/issues/6898))
- Create New Qube
- Qubes Update ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
- New `qubes-vm-update` tool ([#7443](https://github.com/QubesOS/qubes-issues/issues/7443))
- Unified `grub.cfg` location for both UEFI and legacy boot ([#7985](https://github.com/QubesOS/qubes-issues/issues/7985))
- PipeWire support ([#6358](https://github.com/QubesOS/qubes-issues/issues/6358))
- fwupd integration for firmware updates ([#4855](https://github.com/QubesOS/qubes-issues/issues/4855))
@ -42,9 +43,33 @@ The new Qubes OS Policy Editor tool:
## Known issues
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. ([#5031](https://github.com/QubesOS/qubes-issues/issues/5031), [#6062](https://github.com/QubesOS/qubes-issues/issues/6062))
- DomU firewalls have completely switched to nftables. Users should add their custom rules to the `custom-input` and `custom-forward` chains. (For more information, see issues [#5031](https://github.com/QubesOS/qubes-issues/issues/5031) and [#6062](https://github.com/QubesOS/qubes-issues/issues/6062).)
For a full list of open bug reports affecting 4.2, please see [here](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen). We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply any and all available bug fixes.
- Templates restored in 4.2 from a pre-4.2 backup continue to target their original Qubes OS release repos. If you are using fresh templates on a clean 4.2 installation, or if you performed an [in-place upgrade from 4.1 to 4.2](/doc/upgrade/4.2/#in-place-upgrade), then this does not affect you. (For more information, see issue [#8701](https://github.com/QubesOS/qubes-issues/issues/8701).)
Also see the [full list of open bug reports affecting Qubes 4.2](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+label%3Aaffects-4.2+label%3A%22T%3A+bug%22+is%3Aopen).
We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after installation in order to apply all available bug fixes.
## Notes
- Qubes 4.2 does not support Debian 11 templates (see [supported template releases](/doc/supported-releases/#templates)). Please [upgrade your Debian templates](/doc/templates/debian/#upgrading) to Debian 12.
- Qubes 4.2.2 includes a fix for [#8332: File-copy qrexec service is overly restrictive](https://github.com/QubesOS/qubes-issues/issues/8332). As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability.
- After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
- Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service.
- Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules:
```
qubes.Filecopy +allow-all-names @anyvm @anyvm deny
```
- For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc).
- Beginning with Qubes 4.2, the recommended way to update Qubes OS via the command line has changed. Salt is no longer the preferred method, though it is still supported. Instead, `qubes-dom0-update` is recommended for updating dom0, and `qubes-vm-update` is recommended for updating templates and standalones. (The recommended way to update via the GUI has not changed. The Qubes Update tool is still the preferred method.) For more information, see [How to update](/doc/how-to-update/).
## Download

5
developer/releases/todo.md
View file

@ -37,6 +37,7 @@ On final release
* finish release notes
* update InstallationInstructions
* build ISO and push to mirrors
* push `qubes-release` package to `current`
* notify @Rudd-O about the new ISO for new torrent hosting
* write blog post
* announce on Twitter
* write news post
* announce

4
developer/releases/version-scheme.md
View file

@ -71,7 +71,7 @@ When enough progress has been made, we announce the first stable release, e.g.
`3.0.0`. This is not only a version but an actual release. It is considered
stable, and we commit to supporting it according to our [support
schedule](/doc/supported-releases/). Core components are branched at this
moment, and bug fixes are backported from the master branch. Please see [help,
moment, and bug fixes are backported from the main branch. Please see [help,
support, mailing lists, and forum](/support/) for places to ask questions about
stable releases. No major features or interface incompatibilities are to be
included in this release. We release bug fixes as patch releases (`3.0.1`,
@ -173,7 +173,7 @@ We mark each component version in the repository by tag containing
At the release of some release we create branches named like `release2`. Only
bug fixes and compatible improvements are backported to these branches. These
branches should compile. All new development is done in `master` branch. This
branches should compile. All new development is done in `main` branch. This
branch is totally unsupported and may not even compile depending on maintainer
of repository.

234
developer/services/admin-api.md
View file

@ -62,94 +62,100 @@ yet documented.
The API should be implemented as a set of qrexec calls. This is to make it easy
to set the policy using current mechanism.
| call | dest | argument | inside | return | note |
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
| `admin.vm.Remove` | vm | - | - | - |
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
| `admin.label.Remove` | `dom0` | label | - | - |
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
| `admin.property.Get` | `dom0` | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.GetAll` | `dom0` | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.property.GetDefault` | `dom0` | property | - | `type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.Help` | `dom0` | property | - | `help` |
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
| `admin.property.Reset` | `dom0` | property | - | - |
| `admin.property.Set` | `dom0` | property | value | - |
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
| `admin.vm.property.Get` | vm | property | - | `default={True|False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.GetAll` | vm | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.vm.property.GetDefault` | vm | property | - | `type={str|int|bool|vm|label|type} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.Help` | vm | property | - | `help` |
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
| `admin.vm.property.Reset` | vm | property | - | - |
| `admin.vm.property.Set` | vm | property | value | - |
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
| `admin.vm.feature.Get` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature | - | value |
| `admin.vm.feature.Remove` | vm | feature | - | - |
| `admin.vm.feature.Set` | vm | feature | value | - |
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
| `admin.vm.tag.Remove` | vm | tag | - | - |
| `admin.vm.tag.Set` | vm | tag | - | - |
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `admin.vm.device.<class>.Attach` | vm | device | options | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.Set.persistent`| vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.device.<class>.List` | vm | - | - | `<device> <options>\n` | options can include `persistent=True` for "persistently" attached devices (default is temporary)
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <properties> description=<desc>\n` | optional service argument may be used to get info about a single device, <br/>optional (device class specific) properties are in `key=value` form, <br/>`description` must be the last one and is the only one allowed to contain spaces
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
| `admin.pool.Remove` | `dom0` | pool | - | - |
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
| `admin.pool.volume.Set.revisions_to_keep`| `dom0` | pool | `<vid> <value>` | - |
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
| `admin.vm.volume.Set.revisions_to_keep`| vm | volume | value | - |
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
| `admin.vm.Start` | vm | - | - | - |
| `admin.vm.Shutdown` | vm | - | - | - |
| `admin.vm.Pause` | vm | - | - | - |
| `admin.vm.Unpause` | vm | - | - | - |
| `admin.vm.Kill` | vm | - | - | - |
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
| `admin.Events` | `dom0|vm` | - | - | events |
| `admin.vm.Stats` | `dom0|vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
| call | dest | argument | inside | return | note |
|------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
| `admin.vm.List` | `dom0 | <vm>` | - | - | `<name> class=<class> state=<state>\n` |
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
| `admin.vm.CreateInPool.<class>` | `dom0` | template | `name=<name> label=<label> `<br/>`pool=<pool> pool:<volume>=<pool>` | - | either use `pool=` to put all volumes there, <br/>or `pool:<volume>=` for individual volumes - both forms are not allowed at the same time
| `admin.vm.CreateDisposable` | template | - | - | name | Create new DisposableVM, `template` is any AppVM with `dispvm_allowed` set to True, or `dom0` to use default defined in `default_dispvm` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from `admin.vm.Create.DispVM` is automatic (random) name generation.
| `admin.vm.Remove` | vm | - | - | - |
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
| `admin.label.Remove` | `dom0` | label | - | - |
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
| `admin.property.Get` | `dom0` | property | - | `default={True |False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.GetAll` | `dom0` | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.property.GetDefault` | `dom0` | property | - | `type={str |int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Values are of type `str` and each entry is suffixed with newline character.
| `admin.property.Help` | `dom0` | property | - | `help` |
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
| `admin.property.Reset` | `dom0` | property | - | - |
| `admin.property.Set` | `dom0` | property | value | - |
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
| `admin.vm.property.Get` | vm | property | - | `default={True |False} `<br/>`type={str|int|bool|vm|label|list} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.GetAll` | vm | - | - | `<property-name> <full-value-as-in-property.Get>\n` | Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal `\n` and literal `\` are encoded as `\\`.
| `admin.vm.property.GetDefault` | vm | property | - | `type={str |int|bool|vm|label|type} <value>` | Type `list` is added in R4.1. Each list entry is suffixed with a newline character.
| `admin.vm.property.Help` | vm | property | - | `help` |
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
| `admin.vm.property.Reset` | vm | property | - | - |
| `admin.vm.property.Set` | vm | property | value | - |
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
| `admin.vm.feature.Get` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
| `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm | feature | - | value |
| `admin.vm.feature.Remove` | vm | feature | - | - |
| `admin.vm.feature.Set` | vm | feature | value | - |
| `admin.vm.notes.Get` | vm | - | - | notes |
| `admin.vm.notes.Set` | vm | - | notes | - |
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
| `admin.vm.tag.Remove` | vm | tag | - | - |
| `admin.vm.tag.Set` | vm | tag | - | - |
| `admin.vm.firewall.Get` | vm | - | - | `<rule>\n` | rules syntax as in [firewall interface](/doc/vm-interface/#firewall-rules-in-4x) with addition of `expire=` and `comment=` options; `comment=` (if present) must be the last option
| `admin.vm.firewall.Set` | vm | - | `<rule>\n` | - | set firewall rules, see `admin.vm.firewall.Get` for syntax
| `admin.vm.firewall.Reload` | vm | - | - | - | force reload firewall without changing any rule
| `admin.vm.device.<class>.Attach` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/>optional options given in `key=value` format, separated with spaces; <br/>options can include `persistent=True` to "persistently" attach the device (default is temporary)
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
| `admin.vm.device.<class>.Assign` | vm | device | assignment-serialization | - | `device` is in form `<backend-name>+<device-ident>` <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Unassign` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
| `admin.vm.device.<class>.Set.required` | vm | device | `True`\|`False` | - | `device` is in form `<backend-name>+<device-ident>`
| `admin.vm.deviceclass.List` | `dom0` | - | - | `<deviceclass>\n` |
| `admin.vm.device.<class>.Available` | vm | device-ident | - | `<device-ident> <device-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `device-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Assigned` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.vm.device.<class>.Attached` | vm | device-ident | - | `<device-ident> <assignment-serialization>\n` | optional service argument may be used to get info about a single device, <br/> `assignment-serialization` is specified in the section Device Serialization.
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
| `admin.pool.Remove` | `dom0` | pool | - | - |
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
| `admin.pool.volume.Set.revisions_to_keep` | `dom0` | pool | `<vid> <value>` | - |
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
| `admin.pool.volume.CloneFrom` | `dom0` | pool | vid | token, to be used in `admin.pool.volume.CloneTo` | obtain a token to copy volume `vid` in `pool`;<br/>the token is one time use only, it's invalidated by `admin.pool.volume.CloneTo`, even if the operation fails |
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
| `admin.vm.volume.Set.revisions_to_keep` | vm | volume | value | - |
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
| `admin.vm.volume.ImportWithSize` | vm | volume | `<size_in_bytes>\n<raw volume data>` | - | new version of `admin.vm.volume.Import`, allows new volume to be different size |
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
| `admin.vm.volume.CloneFrom` | vm | volume | - | token, to be used in `admin.vm.volume.CloneTo` | obtain a token to copy `volume` of `vm`;<br/>the token is one time use only, it's invalidated by `admin.vm.volume.CloneTo`, even if the operation fails |
| `admin.vm.volume.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
| `admin.vm.Start` | vm | - | - | - |
| `admin.vm.Shutdown` | vm | - | - | - |
| `admin.vm.Pause` | vm | - | - | - |
| `admin.vm.Unpause` | vm | - | - | - |
| `admin.vm.Kill` | vm | - | - | - |
| `admin.backup.Execute` | `dom0` | config id | - | - | config in `/etc/qubes/backup/<id>.conf`, only one backup operation of given `config id` can be running at once |
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
| `admin.Events` | `dom0 | vm` | - | - | events |
| `admin.vm.Stats` | `dom0 | vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
Volume properties:
@ -301,6 +307,58 @@ destination_vm: sys-net
destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
```
## Device Serialization
Both device and assignment serialization is ASCII-encoded and contains
space-separated key-value pairs. The format includes an `=` between the key
and value, and the value is always enclosed in single quotes (`'`).
Values may contain spaces or even single quotes, which are escaped with a backslash.
If a value is not set (`None`), it is represented as `'unknown'`.
For boolean values, `True` is represented as `'yes'`, and `False` as `'no'`.
The order of key-value pairs is irrelevant. Keys starting with `_`
are considered extra properties and are saved in `data` or `options`
for device or assignment respectively.
Information about the serialization format of specific properties can be found below.
Format:
```
<ident> <property_1>='<value_1>' <property_2>='<value_2>' <property_3>='<value_3>'...
```
Detailed serialization format for a device:
- `ident='<ident>'`
- `backend_domain='<backend_domain.name>'`
- `devclass='<devclass>'`
- `vendor='<vendor>'`
- `product='<product>'`
- `manufacturer='<manufacturer>'`
- `name='<name>'`
- `serial='<serial>'`
- `self_identity='<self_identity>'`
- `interfaces='<interface1><interface2>...'`
Each device interface is represented with a 7-character length. Each device has at least one interface. Since the length of the interface representation is known, they are serialized as a single string with each interface representation concatenated one after another. The order is irrelevant.
- `parent_ident='<parent.ident>' parent_devclass='<parent.devclass>'`
- `attachment='<attachment.name>'`
- `_<key1>='<value1>' _<key2>='<value2>' ...` (extra parameters)
Detailed serialization format for an assignment:
- `ident='<ident>'`
- `backend_domain='<backend_domain.name>'`
- `devclass='<devclass>'`
- `frontend_domain='<frontend_domain.name>'`
- `required='<yes/no>'` (default 'no')
- `attach_automatically='<yes/no>'` (default 'no')
- `_<key1>='<str(value1)>' _<key2>='<str(value2)>' ...` (options)
Example device serialization:
```
1-1.1.1 manufacturer='unknown' self_identity='0000:0000::?******' serial='unknown' ident='1-1.1.1' product='Qubes' vendor='ITL' name='Some untrusted garbage' devclass='bus' backend_domain='vm' interfaces=' ******u03**01' _additional_info='' _date='06.12.23' parent_ident='1-1.1' parent_devclass='None'
```
## General notes
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call

4
developer/services/dom0-secure-updates.md
View file

@ -33,11 +33,11 @@ Keeping Dom0 not connected to any network makes it hard, however, to provide upd
The update process is initiated by [qubes-dom0-update script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-dom0-update), running in Dom0.
Updates (\*.rpm files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qubes-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a ~~~/var/lib/qubes/dom0-updates~~~ directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the ~~~--installroot=~~~ option.
Updates (`*.rpm` files) are checked and downloaded by UpdateVM, which by default is the same as the firewall VM, but can be configured to be any other, network-connected VM. This is done by [qubes-download-dom0-updates.sh script](https://github.com/QubesOS/qubes-core-agent-linux/blob/release2/misc/qubes-download-dom0-updates.sh) (this script is executed using qrexec by the previously mentioned qubes-dom0-update). Note that we assume that this script might get compromised and fetch maliciously compromised downloads -- this is not a problem as Dom0 verifies digital signatures on updates later. The downloaded rpm files are placed in a `/var/lib/qubes/dom0-updates` directory on UpdateVM filesystem (again, they might get compromised while being kept there, still this isn't a problem). This directory is passed to yum using the `--installroot=` option.
Once updates are downloaded, the update script that runs in UpdateVM requests an RPM service [qubes.ReceiveUpdates](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes.ReceiveUpdates) to be executed in Dom0. This service is implemented by [qubes-receive-updates script](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-receive-updates) running in Dom0. The Dom0's qubes-dom0-update script (which originally initiated the whole update process) waits until qubes-receive-updates finished.
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received \*.rpm files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
The qubes-receive-updates script processes the untrusted input from Update VM: it first extracts the received `*.rpm` files (that are sent over qrexec data connection) and then verifies digital signature on each file. The qubes-receive-updates script is a security-critical component of the Dom0 update process (as is the [qfile-dom0-unpacker.c](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qfile-dom0-unpacker.c) and the rpm utility, both used by the qubes-receive-updates for processing the untrusted input).
Once qubes-receive-updates finished unpacking and verifying the updates, the updates are placed in ``qubes-receive-updates`` directory in Dom0 filesystem. Those updates are now trusted. Dom0 is configured (see /etc/yum.conf in Dom0) to use this directory as a default (and only) [yum repository](https://github.com/QubesOS/qubes-core-admin-linux/blob/release2/dom0-updates/qubes-cached.repo).

2
developer/services/qfilecopy.md
View file

@ -24,6 +24,6 @@ This has the following disadvantages:
In modern Qubes OS releases, we have reimplemented interVM file copy using qrexec, which addresses the above mentioned disadvantages. Nowadays, 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.
The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the qubes.OpenInVM action can be done on a normal AppVM, too.
The rpc action for regular file copy is *qubes.Filecopy*, the rpc client is named *qfile-agent*, the rpc server is named *qfile-unpacker*. For DispVM copy, the rpc action is *qubes.OpenInVM*, the rpc client is named *qopen-in-vm*, rpc server is named *vm-file-editor*. Note that the *qubes.OpenInVM* action can be done on a normal AppVM, too.
Being a rpc server, *qfile-unpacker* must be coded securely, as it processes potentially untrusted data format. Particularly, we do not want to use external tar or cpio and be prone to all vulnerabilities in them; we want a simplified, small utility, that handles only directory/file/symlink file type, permissions, mtime/atime, and assume user/user ownership. In the current implementation, the code that actually parses the data from srcVM has ca 100 lines of code and executes chrooted to the destination directory. The latter is hardcoded to `~user/QubesIncoming/srcVM`; because of chroot, there is no possibility to alter files outside of this directory.

12
developer/services/qmemman.md
View file

@ -15,7 +15,7 @@ Rationale
Traditionally, Xen VMs are assigned a fixed amount of memory. It is not the optimal solution, as some VMs may require more memory than assigned initially, while others underutilize memory. Thus, there is a need for solution capable of shifting free memory from VM to another VM.
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://web.archive.org/web/20210712161104/https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
- It does not provide real RAM, just an interface to copy memory to/from fast, RAM-based storage. It is perfect for swap, good for file cache, but not ideal for many tasks.
- It is deeply integrated with the Linux kernel. When Qubes will support Windows guests natively, we would have to port *tmem* to Windows, which may be challenging.
@ -24,13 +24,19 @@ Therefore, in Qubes another solution is used. There is the *qmemman* dom0 daemon
Similarly, when there is need for Xen free memory (for instance, in order to create a new VM), traditionally the memory is obtained from dom0 only. When *qmemman* is running, it offers an interface to obtain memory from all domains.
To sum up, *qmemman* pros and cons. Pros:
To sum up, *qmemman* pros and cons.
<div class="focus">
<i class="fa fa-check"></i> <strong>Pros</strong>
</div>
- provides automatic balancing of memory across participating PV and HVM domains, based on their memory demand
- works well in practice, with less than 1% CPU consumption in the idle case
- simple, concise implementation
Cons:
<div class="focus">
<i class="fa fa-times"></i> <strong>Cons</strong>
</div>
- 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

66
developer/services/qrexec-internals.md
View file

@ -122,25 +122,25 @@ Details of all possible use cases and the messages involved are described below.
qrexec-client -d domX [-l local_program] user:cmd
(If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
- (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
`qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port).
- `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port` also set to 0 (allocate a port).
- **dom0**: `qrexec-daemon` allocates a free port (in this case 513), and sends a `MSG_EXEC_CMDLINE` back to the client with connection parameters (**domX** and 513) and with command field empty.
`qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
- `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
- Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
- **domX**: `qrexec-agent` receives `MSG_EXEC_CMDLINE`, and starts the command (`user:cmd`, or `cmd` as user `user`). If possible, this is actually delegated to a separate server (`qrexec-fork-server`) also running on domX.
After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
- After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
- Data is forwarded between the `qrexec-client` in **dom0** and the command executed in **domX** using `MSG_DATA_STDIN`, `MSG_DATA_STDOUT` and `MSG_DATA_STDERR`.
Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
- Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
- When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
### domX: request execution of service `admin.Service` in dom0
@ -150,41 +150,41 @@ Details of all possible use cases and the messages involved are described below.
qrexec-client-vm dom0 admin.Service [local_program] [params]
(If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
- (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
`qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
- `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
`qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
- `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
`qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
- `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
- **dom0**: `qrexec-daemon` receives the request and triggers `qrexec-policy` program, passing all necessary parameters: source domain **domX**, target domain **dom0**, service `admin.Service` and identifier `SOCKET11`.
`qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
- `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
(If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
- (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
- **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0"
The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
- The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
- The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
`qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
- `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
`qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
- `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
`qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
- `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
- Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
- **dom0**: Because the command has the form `QUBESRPC: ...`, it is started through the `qubes-rpc-multiplexer` program with the provided parameters (`admin.Service domX name dom0`). That program finds and executes the necessary script in `/etc/qubes-rpc/`.
- **domX**: `qrexec-agent` receives the `MSG_SERVICE_CONNECT` and passes the connection parameters back to the connected `qrexec-client-vm`. It identifies the `qrexec-client-vm` by the request identifier (`SOCKET11` means file descriptor 11).
`qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
- `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
- Data is forwarded between **dom0** and **domX** as in the previous example (dom0-VM).
@ -196,37 +196,37 @@ Details of all possible use cases and the messages involved are described below.
qrexec-client-vm domY qubes.Service [local_program] [params]
(If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
- (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
- The request is forwarded as `MSG_TRIGGER_SERVICE3` to `qrexec-daemon` running in **dom0**, then to `qrexec-policy`, then (if allowed) to `qrexec-client`.
This is the same as in the previous example (VM-dom0).
- This is the same as in the previous example (VM-dom0).
- **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX"
The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
- The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
- The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
`qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
- `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
`qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
- `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
- Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
Having notified both domains about a connection, `qrexec-client` now exits.
- Having notified both domains about a connection, `qrexec-client` now exits.
- **domX**: `qrexec-agent` receives a `MSG_SERVICE_CONNECT` with connection parameters (**domY** port 513) and request identifier (`SOCKET11`). It sends the connection parameters back to the right `qrexec-client-vm`.
`qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
- `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
- **domY**: `qrexec-agent` receives a `MSG_EXEC_CMDLINE` with the command to execute (`user:QUBESRPC...`) and connection parameters (**domX** port 513).
It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
- It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
- Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
- After that, the data is passed between **domX** and **domY** as in the previous examples (dom0-VM, VM-dom0).
@ -251,6 +251,6 @@ It is a [socket-based Qubes RPC service](/doc/qrexec-socket-services/). Requests
There are two endpoints:
- `policy.Ask` - ask the user about whether to execute a given action
- `policy.Notify` - notify the user about about an action.
- `policy.Notify` - notify the user about an action.
See [qrexec-policy-agent.rst](https://github.com/QubesOS/qubes-core-qrexec/blob/master/Documentation/qrexec-policy-agent.rst) for protocol details.
See [qrexec-policy-agent.md](https://github.com/QubesOS/qubes-core-qrexec/blob/master/doc/qrexec-policy-agent.md) for protocol details.

1
developer/services/qrexec-socket-services.md
View file

@ -62,6 +62,7 @@ See the below example.
`qrexec-policy-agent` is the program that handles "ask" prompts for Qubes RPC calls.
It is a good example of an application that:
* Uses Python and asyncio.
* Runs as a daemon, to save some overhead on starting process.
* Runs as a normal user.

55
developer/services/qrexec.md
View file

@ -22,14 +22,14 @@ However, the OS needs a mechanism to allow the administrative domain (dom0) to f
For instance, when a user selects an application from the KDE menu, it should start in the selected VM.
Also, it is often useful to be able to pass stdin/stdout/stderr from an application running in a VM to dom0 (and the other way around).
(For example, so that a VM can notify dom0 that there are updates available for it).
By default, Qubes allows VMs initiate such communications in specific circumstances.
The qrexec framework generalizes this process by providing a remote procedure call (RPC) protocol for the Qubes architecture.
By default, Qubes allows VMs to initiate such communications in specific circumstances.
The qrexec framework generalizes this process by providing a remote procedure call (RPC) for the Qubes architecture.
It allows users and developers to use and design secure inter-VM tools.
## Qrexec basics: architecture and examples
Qrexec is built on top of *vchan*, a Xen library providing data links between VMs.
During domain startup , a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
During domain startup, a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
They are connected over a **vchan** channel.
`qrexec-daemon` listens for connections from a dom0 utility named `qrexec-client`.
Let's say we want to start a process (call it `VMprocess`) in a VM (`someVM`).
@ -47,18 +47,18 @@ For example, the following command creates an empty file called `hello-world.txt
$ qrexec-client -e -d someVM user:'touch hello-world.txt'
```
The string before the colon specifies what user to run the command as.
The `-e` flag tells `qrexec-client` to exit immediately after sending the execution request and receiving a status code from `qrexec-agent` (whether the process creation succeeded).
The string before the colon specifies which user will run the command.
The `-e` flag tells `qrexec-client` to exit immediately after sending the execution request and receiving a status code from `qrexec-agent` (if the process creation succeeded).
With this option, no further data is passed between the domains.
By contrast, the following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
```
$ qrexec-client -d someVM user:bash
```
The `qvm-run` command is heavily based on `qrexec-client`.
It also takes care of additional activities, e.g. starting the domain if it is not up yet and starting the GUI daemon.
Thus, it is usually more convenient to use `qvm-run`.
It also handles additional activities, e.g. starting the domain if the domain is not up yet and starting the GUI daemon.
It is usually more convenient to use `qvm-run`.
There can be an almost arbitrary number of `qrexec-client` processes for a given domain.
The limiting factor is the number of available vchan channels, which depends on the underlying hypervisor, as well the domain's OS.
@ -70,27 +70,28 @@ For more details on the qrexec framework and protocol, see "[Qubes RPC internals
Some common tasks (like copying files between VMs) have an RPC-like structure: a process in one VM (say, the file sender) needs to invoke and send/receive data to some process in other VM (say, the file receiver).
The Qubes RPC framework was created to securely facilitate a range of such actions.
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
Therefore the design decision was made to pass all control communication via dom0, that can enforce proper authorization.
Then, it is natural to reuse the already-existing qrexec framework.
Inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
The design decision was made to pass all control communication via dom0 which can enforce proper authorization.
It is therefore natural to reuse the already-existing qrexec framework.
Also, note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
There are cases when VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
Thus, the framework allows dom0 to be the RPC target as well.
Note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
There are cases when a VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
This framework allows dom0 to be the RPC target as well.
Thanks to the framework, RPC programs are very simple -- both RPC client and server just use their stdin/stdout to pass data.
The framework does all the inner work to connect these processes to each other via `qrexec-daemon` and `qrexec-agent`.
Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to a normal domain, all one needs is to pass `@dispvm` as the remote domain name.
The framework does all the inner work to connect the processes to eachother via `qrexec-daemon` and `qrexec-agent`.
Disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to an AppVM or StandaloneVM: all one needs is to pass `@dispvm` as the remote domain name.
## Qubes RPC administration
### Policy files
The dom0 directory `/etc/qubes/policy.d/` contains files that set policy for each available RPC action that a VM might call.
The dom0 directories `/etc/qubes/policy.d/` and `/run/qubes/policy.d/` contain files that set policy for each available RPC action that a VM might call.
For example, `/etc/qubes/policy.d/90-default.policy` contains the default policy settings.
When making changes to existing policies it is recommended that you create a *new* policy file starting with a lower number, like `/etc/qubes/policy.d/30-user.policy`.
You may keep your custom policies in one file like `/etc/qubes/policy.d/30-user.policy`, or you may choose to have multiple files, like `/etc/qubes/policy.d/10-copy.policy`, `/etc/qubes/policy.d/10-open.policy`.
Together the contents of these files make up the RPC access policy database: the files are merged, with policies in lower number files overriding policies in higher numbered files.
If there are entries in both `/run/qubes/policy.d/` and `/etc/qubes/policy.d/` with the same name, it isn't specified which takes precedence, so you should avoid this situation.
Policies are defined in lines with the following format:
@ -103,14 +104,14 @@ You can specify the source and destination by name or by one of the reserved key
Service calls from dom0 are currently always allowed, and `@dispvm` means "new VM created for this particular request," so it is never a source of request.)
Other methods using *tags* and *types* are also available (and discussed below).
Whenever a RPC request for an action is received, the domain checks the first matching line of the files in `/etc/qubes/policy.d/` to determine access:
Whenever a RPC request for an action is received, the domain checks the first matching line of the files in `/etc/qubes/policy.d/` and `/run/qubes/policy.d/` to determine access:
whether to allow the request, what VM to redirect the execution to, and what user account the program should run under.
Note that if the request is redirected (`target=` parameter), policy action remains the same -- even if there is another rule which would otherwise deny such request.
If no policy rule is matched, the action is denied.
In the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself -- in which case it must have executable permission set (`chmod +x`):
- `/etc/qubes-rpc/RPC_ACTION_NAME` when you make it in the template qube;
- `/usr/local/etc/qubes-rpc/RPC_ACTION_NAME` for making it only in an app qube.
Files in `/run/qubes/policy.d/` are deleted when the system is rebooted.
This is useful for temporary policy that contains the name or UUID of a disposable VM, which will not be meaningful after the system has rebooted.
Such policy files can be created manually, but they are usually created automatically by a Qrexec call to dom0.
### Making an RPC call
@ -135,6 +136,17 @@ It is also possible to call service without specific client program -- in which
$ qrexec-client-vm target_vm_name RPC_ACTION_NAME
```
### Answering an RPC call
In other for a RPC call to be answered in the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself -- in which case it must have executable permission set (`chmod +x`):
- `/etc/qubes-rpc/RPC_ACTION_NAME` when you make it in the template qube;
- `/usr/local/etc/qubes-rpc/RPC_ACTION_NAME` for making it only in an app qube.
The source VM name can then be accessed in the server process via
`QREXEC_REMOTE_DOMAIN` environment variable. (Note the source VM has *no*
control over the name provided in this variable--the name of the VM is
provided by dom0, and so is trusted.)
### Specifying VMs: tags, types, targets, etc.
There are severals methods for specifying source/target VMs in RPC policies.
@ -238,7 +250,6 @@ This means it is possible to install a different script for a particular service
See [below](#rpc-service-with-argument-file-reader) for an example of an RPC service using an argument.
<!-- TODO document "Yes to All" authorization if it is reintroduced -->
## Qubes RPC examples

24
developer/services/qrexec2.md
View file

@ -17,7 +17,7 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM)
services. It offers a mechanism to start programs in VMs, redirect their
stdin/stdout, and a policy framework to control this all.
## Qrexec basics ##
## Qrexec basics
During each domain creation a process named `qrexec-daemon` is started in
dom0, and a process named `qrexec-agent` is started in the VM. They are
@ -56,7 +56,7 @@ There is a similar command line utility available inside Linux AppVMs (note
the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent
sections.
## Qubes RPC services ##
## Qubes RPC services
Apart from simple Dom0-\>VM command executions, as discussed above, it is
also useful to have more advanced infrastructure for controlled inter-VM
@ -90,7 +90,7 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout
of the server process with the corresponding stdin/stdout of the requesting
process in the requesting VM (see example Hello World service described below).
## Qubes RPC administration ##
## Qubes RPC administration
Besides each VM needing to provide explicit programs to serve each supported
service, the inter-VM service RPC is also governed by a central policy in Dom0.
@ -135,7 +135,7 @@ if still there is no policy file after prompting, the action is denied.
On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file
name of the program that will be invoked.
### Requesting VM-VM (and VM-Dom0) services execution ###
### Requesting VM-VM (and VM-Dom0) services execution
In a src VM, one should invoke the qrexec client via the following command:
@ -161,7 +161,7 @@ If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*,
connect directly to `/var/run/qubes/qrexec-agent-fdpass` socket as described
[below](#all-the-pieces-together-at-work).
### Revoking "Yes to All" authorization ###
### Revoking "Yes to All" authorization
Qubes RPC policy supports an "ask" action, that will prompt the user whether
a given RPC call should be allowed. It is set as default for services such
@ -184,7 +184,7 @@ A user might also want to set their own policies in this section. This may
mostly serve to prevent the user from mistakenly copying files or text from
a trusted to untrusted domain, or vice-versa.
### Qubes RPC "Hello World" service ###
### Qubes RPC "Hello World" service
We will show the necessary files to create a simple RPC call that adds two
integers on the target VM and returns back the result to the invoking VM.
@ -232,7 +232,7 @@ be allowed.
**Note:** For a real world example of writing a qrexec service, see this
[blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html).
### More high-level RPCs? ###
### More high-level RPCs?
As previously noted, Qubes aims to provide mechanisms that are very simple
and thus with very small attack surface. This is the reason why the inter-VM
@ -242,14 +242,14 @@ users/app developers are always free to run more high-level RPC protocols on
top of qrexec. Care should be taken, however, to consider potential attack
surfaces that are exposed to untrusted or less trusted VMs in that case.
# Qubes RPC internals #
## Qubes RPC internals
(*This is about the implementation of qrexec v2. For the implementation of
qrexec v3, see [here](/doc/qrexec-internals/). Note that the user
API in v3 is backward compatible: qrexec apps written for Qubes R2 should
run without modification on Qubes R3.*)
## Dom0 tools implementation ##
## Dom0 tools implementation
Players:
@ -262,7 +262,7 @@ Players:
**Note:** None of the above tools are designed to be used by users.
## Linux VMs implementation ##
## Linux VMs implementation
Players:
@ -275,7 +275,7 @@ Players:
**Note:** None of the above tools are designed to be used by
users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
## Windows VMs implementation ##
## Windows VMs implementation
`%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things
Lab\Qubes OS Windows Tools` by default).
@ -291,7 +291,7 @@ Lab\Qubes OS Windows Tools` by default).
**Note:** None of the above tools are designed to be used by
users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
## All the pieces together at work ##
## All the pieces together at work
**Note:** This section is not needed to use qrexec for writing Qubes
apps. Also note the [qrexec framework implemention in Qubes R3](/doc/qrexec3/)

11
developer/system/gui.md
View file

@ -16,8 +16,8 @@ title: GUI virtualization
All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers:
- *`dummyqsb_drv`* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
- *`qubes_drv`* - it provides a virtual keyboard and mouse (in fact, more, see below)
- `dummyqsb_drv` - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
- `qubes_drv` - it provides a virtual keyboard and mouse (in fact, more, see below)
For each AppVM, there is a pair of `qubes-gui` (running in AppVM) and `qubes-guid` (running in the AppVM’s GuiVM, dom0 by default) processes connected over vchan.
The main responsibilities of `qubes-gui` are:
@ -49,7 +49,7 @@ In the case of Qubes, `qubes-gui` does not transfer all changed pixels via vchan
and pass this to dom0 via the deprecated `MFNDUMP` message.
- New `qubes-gui` versions will rely on `qubes-drv` having allocated
memory using gntalloc, and then pass the grant table indexes gntalloc
has chosen to the GUI daemon using using the `WINDOW_DUMP` message.
has chosen to the GUI daemon using the `WINDOW_DUMP` message.
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.
@ -90,9 +90,10 @@ Clipboard sharing implementation
Certainly, it would be insecure to allow AppVM to read/write the clipboards of other AppVMs unconditionally.
Therefore, the following mechanism is used:
- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0.
- there is a "qubes clipboard" in dom0 - its contents are stored in a regular file in dom0 as `/run/qubes/qubes-clipboard.bin`.
- 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.
- a supplementary JSON metadata file will be saved as `/run/qubes/qubes-clipboard.bin.metadata` on global clipboard copy or paste actions. Explanation of each field is available in `xside.h` header file of `qubes-guid` under `clipboard_metadata` structure. While the output from `qubes-guid` is fully JSON compatible, the `qubes-guid` parser is limited. It expects line breaks after each key-value pair and only one key-value pair per line. Opening and closing curly braces should be on their own lines. There should be no leading white-space.
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.
@ -118,7 +119,7 @@ AppVM -> GuiVM messages
Proper handling of the below messages is security-critical.
Note that all messages except for `CLIPBOARD`, `MFNDUMP`, and `WINDOW_DUMP` 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).
Window manager hints and flags are described in the [Extended Window Manager Hints (EWMH) spec](https://standards.freedesktop.org/wm-spec/latest/), especially under the `_NET_WM_STATE` section.

5
developer/system/networking.md
View file

@ -62,9 +62,12 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs
![ipv6-2](/attachment/doc/ipv6-2.png)
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, the standard Qubes firewall can be used to limit what network resources are available to each qube. Currently only the `qvm-firewall` command supports adding IPv6 rules, the GUI firewall editor will have this ability later.
**Note:** Setting or unsetting the `ipv6` feature only affects qubes-configured networking. It does not affect e.g. external interfaces. If you want to restrict IPv6 on these interfaces change the settings in Network Manager. Alternatively, disable IPv6 support using methods appropriate to the underlying template.
### Limitations
Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.

16
developer/system/template-implementation.md
View file

@ -27,7 +27,7 @@ This is mounted as /rw and here is placed all VM private data. This includes:
- */usr/local* – which is symlink to /rw/usrlocal
- some config files (/rw/config) called by qubes core scripts (ex /rw/config/rc.local)
**Note:** Whenever a TemplateBasedVM is created, the contents of the `/home` directory of its parent TemplateVM [are *not* copied to the child TemplateBasedVM's `/home`](/doc/templates/#inheritance-and-persistence). The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not 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 *not* copied to the [child TemplateBasedVM's](/doc/templates/#inheritance-and-persistence) `/home`. The child TemplateBasedVM's `/home` is independent from its parent TemplateVM's `/home`, which means that any changes to the parent TemplateVM's `/home` will not 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)
@ -73,19 +73,9 @@ When TemplateVM is stopped, the xen script moves root-cow.img to root-cow.img.ol
#### Rollback template changes
There is possibility to rollback last template changes. Saved root-cow.img.old contains all changes made during last TemplateVM run. Rolling back changes is done by reverting this "binary patch".
There is possibility to rollback last template changes. Using the automatic snapshot that is normally saved every time the template is shutdown.
This is done using snapshot-merge device-mapper target (available from 2.6.34 kernel). It requires that no other snapshot device uses underlying block devices (root.img, root-cow.img via loop device). Because of this all AppVMs based on this template must be halted during this operation.
Steps performed by **qvm-revert-template-changes**:
1. Ensure that no other VMs uses this template.
2. Prepare snapshot device with ***root-cow.img.old*** instead of *root-cow.img* (*/etc/xen/scripts/block-snapshot prepare*).
3. Replace *snapshot* device-mapper target with *snapshot-merge*, other parameters (chunk size etc) remains untouched. Now kernel starts merging changes stored in *root-cow.img.old* into *root.img*. d-m device can be used normally (if needed).
4. Waits for merge completed: *dmsetup status* shows used snapshot blocks – it should be equal to metadata size when completed.
5. Replace *snapshot-merge* d-m target back to *snapshot*.
6. Cleanup snapshot device (if nobody uses it at the moment).
7. Move *root-cow.img.old* to *root-cow.img* (overriding existing file).
Refer to volume backup and revert [documentation](/doc/volume-backup-revert) for more information.
### Snapshot device in AppVM

2
developer/system/template-manager.md
View file

@ -23,7 +23,7 @@ specifically override the changes.) Other operations that work well on normal
VMs are also somewhat inconsistent on RPM-managed templates. This includes
actions such as renaming
([#839](https://github.com/QubesOS/qubes-issues/issues/839)), removal
([#5509](https://github.com/QubesOS/qubes-issues/issues/5509)) and
([#5509](https://web.archive.org/web/20210526123932/https://github.com/QubesOS/qubes-issues/issues/5509)) and
backup/restore ([#1385](https://github.com/QubesOS/qubes-issues/issues/1385),
[#1453](https://github.com/QubesOS/qubes-issues/issues/1453), [discussion
thread

50
developer/system/vm-sudo.md Normal file
View file

@ -0,0 +1,50 @@
---
lang: en
layout: doc
permalink: /doc/vm-sudo-implementation/
redirect_from:
- /en/doc/vm-sudo-implementation/
- /doc/VMSudo-implementation/
ref: 341
title: Passwordless root access in qubes
---
The rationale behind passwordless root in qubes is set out [here](/doc/vm-sudo). Implementation is by the qubes-core-agent-passwordless-root package.
This page sets out the configuration changes made, with (not necessary complete) list of mechanisms depending on each of them:
1. sudo (`/etc/sudoers.d/qubes`):
```
Defaults !requiretty
%qubes ALL=(ALL) ROLE=unconfined_r TYPE=unconfined_t NOPASSWD: ALL
(...)
```
- Easy user -> root access (main option for the user).
- `qvm-usb` (not really working, as of R2).
2. PolicyKit (`/etc/polkit-1/rules.d/00-qubes-allow-all.rules`):
```
//allow any action, detailed reasoning in sudoers.d/qubes
polkit.addRule(function(action,subject) { if (subject.isInGroup("qubes")) return polkit.Result.YES; });
```
PAM (`/etc/pam.d/su.qubes` or `/usr/share/pam-configs/su.qubes`)
```
auth sufficient pam_succeed_if.so use_uid user ingroup qubes
```
- NetworkManager configuration from normal user (`nm-applet`).
- Updates installation (`gpk-update-viewer`).
- User can use pkexec just like sudo Note: above is needed mostly because Qubes user GUI session isn't treated by PolicyKit/logind as "local" session because of the way in which X server and session is started.
Perhaps we will address this issue in the future, but this is really low priority.
Patches welcomed anyway.
3. Empty root password:
- Used for access to 'root' account from text console (`qvm-console-dispvm`) - the only way to access the VM when GUI isn't working.
- Can be used for easy 'su -' from user to root.

2
external/building-guides/building-archlinux-template.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-archlinux-template.md
redirect_to: https://forum.qubes-os.org/t/19052
ref: 116
title: Building Arch Linux template
---

2
external/building-guides/building-non-fedora-template.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/building-non-fedora-template/
- /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/building/building-non-fedora-template.md
redirect_to: https://forum.qubes-os.org/t/18972
ref: 117
title: Building non-Fedora template
---

2
external/building-guides/building-whonix-template.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /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
redirect_to: https://forum.qubes-os.org/t/18981
ref: 115
title: Building Whonix templates
---

2
external/configuration-guides/change-time-zone.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/change-time-zone/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/change-time-zone.md
redirect_to: https://forum.qubes-os.org/t/18983
ref: 109
title: Changing your time zone
---

2
external/configuration-guides/disk-trim.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/disk-trim/
- /doc/DiskTRIM/
- /wiki/DiskTRIM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/disk-trim.md
redirect_to: https://forum.qubes-os.org/t/19054
ref: 104
title: Disk TRIM
---

2
external/configuration-guides/external-audio.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/external-audio/
- /doc/ExternalAudio/
- /wiki/ExternalAudio/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/external-audio.md
redirect_to: https://forum.qubes-os.org/t/18984
ref: 100
title: External audio
---

2
external/configuration-guides/fetchmail.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/fetchmail/
- /doc/Fetchmail/
- /wiki/Fetchmail/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/fetchmail.md
redirect_to: https://forum.qubes-os.org/t/18985
ref: 114
title: Fetchmail
---

2
external/configuration-guides/install-nvidia-driver.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/install-nvidia-driver/
- /doc/InstallNvidiaDriver/
- /wiki/InstallNvidiaDriver/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/install-nvidia-driver.md
redirect_to: https://forum.qubes-os.org/t/18987
ref: 96
title: How to install an Nvidia driver
---

2
external/configuration-guides/multiboot.md vendored
View file

@ -1,7 +1,7 @@
---
lang: en
layout: doc
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md
redirect_to: https://forum.qubes-os.org/t/18988
ref: 112
title: Multibooting
---

2
external/configuration-guides/multimedia.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/multimedia/
- /doc/Multimedia/
- /wiki/Multimedia/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multimedia.md
redirect_to: https://forum.qubes-os.org/t/19055
ref: 105
title: How to make a multimedia template
---

2
external/configuration-guides/mutt.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/mutt/
- /doc/Mutt/
- /wiki/Mutt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/mutt.md
redirect_to: https://forum.qubes-os.org/t/18989
ref: 106
title: Mutt
---

2
external/configuration-guides/network-bridge-support.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/network-bridge-support/
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-bridge-support.md
redirect_to: https://forum.qubes-os.org/t/18990
ref: 113
title: Network bridge support
---

2
external/configuration-guides/network-printer.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/network-printer/
- /doc/NetworkPrinter/
- /wiki/NetworkPrinter/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/network-printer.md
redirect_to: https://forum.qubes-os.org/t/19056
ref: 108
title: Network printer
---

2
external/configuration-guides/postfix.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/postfix/
- /doc/Postfix/
- /wiki/Postfix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/postfix.md
redirect_to: https://forum.qubes-os.org/t/18991
ref: 107
title: Postfix
---

2
external/configuration-guides/rxvt.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/rxvt/
- /doc/Rxvt/
- /wiki/Rxvt/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/rxvt.md
redirect_to: https://forum.qubes-os.org/t/18992
ref: 103
title: Rxvt
---

9
external/configuration-guides/tips-and-tricks.md vendored
View file

@ -1,9 +0,0 @@
---
lang: en
layout: doc
redirect_from:
- /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
---

2
external/configuration-guides/vpn.md vendored
View file

@ -7,7 +7,7 @@ redirect_from:
- /en/doc/vpn/
- /doc/VPN/
- /wiki/VPN/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md
redirect_to: https://forum.qubes-os.org/t/19061
ref: 102
title: VPN
---

2
external/configuration-guides/w3m.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/mutt/
- /doc/W3m/
- /wiki/W3m/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/w3m.md
redirect_to: https://forum.qubes-os.org/t/18993
ref: 101
title: Reducing the fingerprint of the text-based web browser w3m
---

2
external/configuration-guides/zfs.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/zfs/
- /doc/ZFS/
- /wiki/ZFS/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/zfs.md
redirect_to: https://forum.qubes-os.org/t/18994
ref: 111
title: ZFS
---

2
external/customization-guides/dark-theme.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/dark-theme/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/dark-theme.md
redirect_to: https://forum.qubes-os.org/t/18997
ref: 74
title: Dark theme
---

2
external/customization-guides/fedora-minimal-template-customization.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
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
redirect_to: https://forum.qubes-os.org/t/18999
ref: 76
title: Fedora minimal template customization
---

2
external/customization-guides/language-localization.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/language-localization/
- /doc/LanguageLocalization/
- /wiki/LanguageLocalization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/language-localization.md
redirect_to: https://forum.qubes-os.org/t/19001
ref: 73
title: Language localization
---

2
external/customization-guides/removing-templatevm-packages.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/removing-templatevm-packages/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/removing-templatevm-packages.md
redirect_to: https://forum.qubes-os.org/t/19002
ref: 75
title: Removing template packages
---

2
external/customization-guides/windows-template-customization.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/windows-template-customization/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/customization/windows-template-customization.md
redirect_to: https://forum.qubes-os.org/t/19005
ref: 72
title: Windows template customization
---

2
external/os-guides/centos.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/templates/centos/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/centos.md
redirect_to: https://forum.qubes-os.org/t/19006
ref: 81
title: CentOS template
---

2
external/os-guides/gentoo.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/templates/gentoo/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/gentoo.md
redirect_to: https://forum.qubes-os.org/t/19007
ref: 221
title: Gentoo template
---

2
external/os-guides/linux-hvm-tips.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/linux-hvm-tips/
- /doc/LinuxHVMTips/
- /wiki/LinuxHVMTips/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md
redirect_to: https://forum.qubes-os.org/t/19008
ref: 82
title: Linux HVM tips
---

2
external/os-guides/netbsd.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/netbsd/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/netbsd.md
redirect_to: https://forum.qubes-os.org/t/19009
ref: 84
title: How to create a NetBSD qube
---

9
external/os-guides/pentesting.md vendored
View file

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

2
external/os-guides/pentesting/blackarch.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/blackarch/
- /doc/blackarch/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/blackarch.md
redirect_to: https://forum.qubes-os.org/t/19010
ref: 88
title: How to create a BlackArch qube
---

2
external/os-guides/pentesting/kali.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/kali/
- /doc/kali/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/kali.md
redirect_to: https://forum.qubes-os.org/t/19071
ref: 87
title: How to create a Kali Linux qube
---

2
external/os-guides/pentesting/ptf.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/pentesting/ptf/
- /doc/ptf/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/pentesting/ptf.md
redirect_to: https://forum.qubes-os.org/t/19011
ref: 89
title: How to create penetration testers framework (PTF) qube
---

2
external/os-guides/ubuntu.md vendored
View file

@ -7,7 +7,7 @@ redirect_from:
- /en/doc/templates/ubuntu/
- /doc/Templates/Ubuntu/
- /wiki/Templates/Ubuntu/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/os/ubuntu.md
redirect_to: https://qubes.3isec.org
ref: 80
title: Ubuntu template
---

2
external/privacy-guides/anonymizing-your-mac-address.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/anonymizing-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
redirect_to: https://forum.qubes-os.org/t/19072
ref: 67
title: Anonymizing your MAC address
---

2
external/privacy-guides/signal.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/signal/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/signal.md
redirect_to: https://forum.qubes-os.org/t/19073
ref: 70
title: Signal
---

2
external/privacy-guides/tails.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/tails/
- /doc/running-tails/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/tails.md
redirect_to: https://forum.qubes-os.org/t/19012
ref: 71
title: Running Tails in qubes
---

2
external/privacy-guides/torvm.md vendored
View file

@ -8,7 +8,7 @@ redirect_from:
- /doc/TorVM/
- /doc/UserDoc/TorVM/
- /wiki/UserDoc/TorVM/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/torvm.md
redirect_to: https://forum.qubes-os.org/t/19013
ref: 68
title: TorVM
---

2
external/privacy-guides/whonix.md vendored
View file

@ -16,7 +16,7 @@ redirect_from:
- /doc/privacy/uninstall-whonix/
- /doc/whonix/update/
- /doc/privacy/updating-whonix/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/privacy/whonix.md
redirect_to: https://forum.qubes-os.org/t/19014
ref: 69
title: Whonix for privacy & anonymity
---

2
external/security-guides/multifactor-authentication.md vendored
View file

@ -5,7 +5,7 @@ redirect_from:
- /doc/multifactor-authentication/
- /en/doc/multifactor-authentication/
- /doc/Multi-factorAuthentication/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/multifactor-authentication.md
redirect_to: https://forum.qubes-os.org/t/19016
ref: 78
title: Multifactor authentication
---

2
external/security-guides/security-guidelines.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/security-guidelines/
- /doc/SecurityGuidelines/
- /wiki/SecurityGuidelines/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md
redirect_to: https://forum.qubes-os.org/t/19075
ref: 79
title: Security guidelines
---

2
external/security-guides/split-bitcoin.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/split-bitcoin/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/security/split-bitcoin.md
redirect_to: https://forum.qubes-os.org/t/19017
ref: 77
title: Split Bitcoin
---

2
external/troubleshooting/application-troubleshooting.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/application-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/application-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19019
ref: 236
title: Application troubleshooting
---

2
external/troubleshooting/intel-igfx-troubleshooting.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/intel-igfx-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/intel-igfx-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19081
ref: 90
title: Intel integrated graphics troubleshooting
---

2
external/troubleshooting/macbook-troubleshooting.md vendored
View file

@ -1,7 +1,7 @@
---
lang: en
layout: doc
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/macbook-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19020
ref: 238
title: Apple MacBook troubleshooting
---

2
external/troubleshooting/nvidia-troubleshooting.md vendored
View file

@ -4,7 +4,7 @@ layout: doc
redirect_from:
- /doc/NvidiaTroubleshooting/
- /wiki/NvidiaTroubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/nvidia-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19021
ref: 91
title: Nvidia troubleshooting
---

2
external/troubleshooting/sony-vaio-tinkering.md vendored
View file

@ -6,7 +6,7 @@ redirect_from:
- /en/doc/sony-vaio-tinkering/
- /doc/SonyVaioTinkering/
- /wiki/SonyVaioTinkering/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/sony-vaio-tinkering.md
redirect_to: https://forum.qubes-os.org/t/19022
ref: 93
title: Sony Vaio tinkering
---

2
external/troubleshooting/tails-troubleshooting.md vendored
View file

@ -3,7 +3,7 @@ lang: en
layout: doc
redirect_from:
- /doc/tails-troubleshooting/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/tails-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19023
ref: 237
title: Tails troubleshooting
---

2
external/troubleshooting/thinkpad-troubleshooting.md vendored
View file

@ -11,7 +11,7 @@ redirect_from:
- /en/doc/lenovo450-tinkering/
- /doc/Lenovo450Tinkering/
- /wiki/Lenovo450Tinkering/
redirect_to: https://github.com/Qubes-Community/Contents/blob/master/docs/troubleshooting/thinkpad-troubleshooting.md
redirect_to: https://forum.qubes-os.org/t/19024
ref: 95
title: Lenovo ThinkPad troubleshooting
---

10
introduction/faq.md
View file

@ -144,7 +144,7 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu
(For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
<div class="focus">
<i class="fa fa-times"></i> <strong>Cons</strong>
<i class="fa fa-times"></i> <strong>Cons</strong>
</div>
- Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need.
@ -190,7 +190,7 @@ By default, Qubes OS uses [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key
### What do all these terms mean?
All Qubes-specific terms are defined in the [glossary](/doc/glossary/)
All Qubes-specific terms are defined in the [glossary](/doc/glossary/).
### Does Qubes run every app in a separate VM?
@ -459,7 +459,7 @@ You have to restart the NetVM after the template has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
You shouldn't do that, because it poses a security risk for your Qubes OS installation.
But if you understand the risk and accept it, read [documentation on multibooting](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/multiboot.md).
But if you understand the risk and accept it, read [documentation on multibooting](https://forum.qubes-os.org/t/18988).
It begins with an explanation of the risks with such a setup.
### Which version of Qubes am I running?
@ -678,7 +678,7 @@ Any rpm-based, 64-bit environment, the preferred OS being Fedora.
### How do I build Qubes from sources?
See [these instructions](/doc/qubes-builder/).
See [these instructions](/doc/qubes-builder-v2/).
### How do I submit a patch?
@ -806,4 +806,4 @@ If you need to support not-fully-updated systems, check for the existence of `/u
Yes, Qubes natively supports automation via [Salt (SaltStack)](/doc/salt/).
There is also the unofficial [ansible-qubes toolkit](https://github.com/Rudd-O/ansible-qubes).
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://github.com/Qubes-Community/Contents/blob/master/docs/security/security-guidelines.md#dom0-precautions).)
(**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, [allowing it to manage dom0 may be a security risk](https://forum.qubes-os.org/t/19075#dom0-precautions).)

142
introduction/getting-started.md
View file

@ -18,14 +18,13 @@ Dive right in to [organizing your qubes](/doc/how-to-organize-your-qubes/).)
## The Basics
Qubes OS is an operating system built out of securely-isolated compartments
called [qubes](/doc/glossary/#qube). For example, you might have a work qube, a
personal qube, a banking qube, a web browsing qube, and so on. You can have as
many qubes as you want! Most of the time, you'll be using an [app
qube](/doc/glossary/#app-qube), which is a qube intended for running software
Qubes OS is an operating system built out of securely-isolated compartments, or [qubes](/doc/glossary/#qube).
You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on.
You can have as many qubes as you want! Most of the time, you'll be using an [app
qube](/doc/glossary/#app-qube), a qube for running software
programs like web browsers, email clients, and word processors. Each app qube
is based on another type of qube called a [template](/doc/glossary/#template).
More than one qube can be based on the same template. Importantly, a qube
The same template can be a base for various qubes. Importantly, a qube
cannot modify its template in any way. This means that, if a qube is ever
compromised, its template and any other qubes based on that template will
remain safe. This is what makes Qubes OS so secure. Even if an attack is
@ -35,9 +34,8 @@ Suppose you want to use your favorite web browser in several different qubes.
You'd install the web browser in a template, then every qube based on that
template would be able to run the web browser software (while still being
forbidden from modifying the template and any other qubes). This way, you only
have to install the web browser a single time, and updating the template serves
to update all the qubes based on it. This elegant design saves time and space
while enhancing security.
have to install the web browser a single time, and updating the template updates all the qubes based on it.
This elegant design saves time and space while enhancing security.
There are also some "helper" qubes in your system. Each qube that connects to
the Internet does so through a network-providing [service
@ -54,45 +52,43 @@ corresponding version number. There are many ready-to-use
many as you like.
Last but not least, there's a very special [admin
qube](/doc/glossary/#admin-qube) which, as the name suggests, is used to
administer your entire system. There's only one admin qube, and it's called
[dom0](/doc/glossary/#dom0). You can think of it as the master qube, holding
ultimate power over everything that happens in Qubes OS. Dom0 is more trusted
than any other qube. If dom0 were ever compromised, it would be "game over."
The entire system would effectively be compromised. That's why everything in
Qubes OS is specifically designed to protect dom0 and ensure that doesn't
qube](/doc/glossary/#admin-qube) used to administer your entire system.
There's only one admin qube, and it's called [dom0](/doc/glossary/#dom0).
You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS.
Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be "game over"- an effective compromise of the entire system.
That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't
happen. Due to its overarching importance, dom0 has no network connectivity and
is used only for running the [desktop
environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window
manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be
used for anything else. In particular, you should never run user applications
in dom0. (That's what your app qubes are for!)
in dom0. (That's what your app qubes are for!) In short, be very careful when interacting with dom0.
### Color & Security
You'll choose a **color** for each of your qubes out of a predefined set of
colors. Each window on your desktop will have its frame colored according to
the color of that qube. These colored frames help you keep track of which qube
each window belongs to and how trustworthy it is. This is especially helpful
when you have the same app running in multiple qubes at the same time. For
colors. The color of the frame of each window on your desktop will correspond to the color of that qube.
These colored frames help you keep track of which qube you're currently using.
You may use them to show how trustworthy it is. This is especially helpful
when you have the same program running in multiple qubes at the same time. For
example, if you're logged in to your bank account in one qube while doing some
random web surfing in a different qube, you wouldn't want to accidentally enter
your banking password in the latter! The colored frames help to avoid such
mistakes.
[![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png)
[![snapshot_41.png](/attachment/doc/r4.1-snapshot_40.png)](/attachment/doc/r4.1-snapshot_40.png)
Most Qubes users associate red with what's untrusted and dangerous (like a red
light: stop! danger!), green with what's safe and trusted, and yellow and
orange with things in the middle. This color scheme also extends to include
blue and black, which are usually interpreted as indicating progressively more
trusted domains than green, with black being ultimately trusted. Color and
associated meanings are ultimately up to you, however. The system itself does
not treat the colors differently. If you create two identical qubes --- black
stop light signalling danger), green with what's safe and trusted, and yellow and
orange with things in-between. This color scheme also includes
blue and black, commonly interpreted as indicating progressively more
trusted domains than green, with black being ultimately trusted. However, color and
associated meanings are entirely up to you. The system itself does
not treat the colors differently - they're all equally safe on their own. If you create two identical qubes --- black
and red, say --- they'll be the same until you start using them differently.
Feel free to use the colors in whatever way is most useful to you. For example,
Feel free to use the colors in the way that best meets your needs. For example,
you might decide to use three or four qubes for work activities and give them
all the same color --- or all different colors. It's entirely up to you.
all the same color --- or all different colors depending on the nature of the task they are used for.
### User Interface
@ -104,27 +100,24 @@ the window managers [i3](/doc/i3/) and [AwesomeWM](/doc/awesomewm/).
[![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png)
The bar at the top of your screen in Qubes 4.0 includes the following XFCE
The bar at the top of your screen in Qubes 4.2 includes the following XFCE
component areas:
- The **Tray**, where many functional widgets live.
- The **App Menu**, where you go to open an application within a qube, to open
a dom0 terminal, to access administrative UI tools such as the Qube Manager,
or to access settings panels for your desktop environment.
- The **Task Bar** where buttons for open and hidden windows live.
- **Spaces**, an interface for [virtual
desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do
not have any inherent security isolation properties, but some users find them
useful for organizing things.
- The **Task Bar** where buttons for open and hidden windows live.
- The **App Menu**, where you go to open an application within a qube, to open
a dom0 terminal, to access administrative UI tools such as the Qube Manager,
or to access settings panels for your desktop environment.
To learn more about how to customize your desktop environment, we recommend you
spend some time going through [XFCE's documentation](https://docs.xfce.org/).
- The **Tray**, where many functional widgets live.
There are several tray widgets that are unique to Qubes OS:
- The **Whonix SDWDate** allows you to control the Tor connection in your
[`sys-whonix`](https://www.whonix.org/wiki/Qubes) qube.
- The **Qubes Clipboard** lets you easily copy text from dom0.
- The **Qubes Clipboard** lets you easily [copy text](https://wwwpreview.qubes-os.org/doc/how-to-copy-and-paste-text/) between various qubes and from dom0.
- The **Qubes Devices** widget allows you to attach and detach devices --- such
as USB drives and cameras --- to qubes.
- The **Qubes Disk Space** widget shows you how much storage you're using.
@ -136,50 +129,57 @@ There are several tray widgets that are unique to Qubes OS:
[![r4.1-widgets.png](/attachment/doc/r4.1-widgets.png)](/attachment/doc/r4.1-widgets.png)
To learn more about how to customize your desktop environment, we recommend you
go through [XFCE's documentation](https://docs.xfce.org/).
#### Qube Manager
To see all of your qubes at the same time, you can use the **Qube Manager** (go
to the App Menu → Qubes Tools → Qube Manager), which displays the states of
all the qubes in your system, even the ones that aren't running.
To see all of your qubes at the same time, you can use the **Qube Manager**.
It displays the states of all the qubes in your system, even the ones that aren’t running.
[![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png)
To access Qube Manager go to:
Qubes Icon (App Menu) → Settings Icon → Qubes Tools → **Qube Manager**
[![r4.1-qubes-manager.png](/attachment/doc/r4.1-qubes-manager.png)](/attachment/doc/r4.1-qubes-manager.png)
#### Command-line interface
All aspects of Qubes OS can be controlled using command-line tools. Opening a
terminal emulator in dom0 can be done in several ways:
All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator.
The default terminal emulator in Qubes is Xfce Terminal.
Opening a terminal emulator in dom0 can be done in several ways:
- Go to the App Menu and select **Terminal Emulator** at the top.
- Press `Alt`+`F3` and search for `xfce terminal`.
- Go to the App Menu, click on the Settings icon, choose Other from the drop-down menu, and select **Xfce Terminal Emulator** at the bottom.
- Press `Alt` + `F3` and search for `xfce terminal`.
- Right-click on the desktop and select **Open Terminal Here**.
Terminal emulators can also be run in other qubes as normal programs. Various
command-line tools are described as part of this guide, and the whole reference
can be found [here](/doc/tools/).
Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/).
Terminal emulators can also be run in other qubes as normal programs.
## First boot
When you install Qubes OS, a number of qubes are pre-configured for you:
- **Templates:** `fedora-XX` (`XX` being the version number)
- **App qubes** such as `work`, `personal`, `untrusted`, and `vault` are your "starter pack" qubes to compartmentalize tasks
and types of data to suit most basic needs. (There is nothing special about these pre-configured qubes - they are identical in nature to more specific ones you might wish to create later.)
- **Templates:** `fedora-XX`, `debian-XX` (`XX` being the version number)
- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`)
- **Admin qube:** `dom0`
- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`
- **App qubes** configured to prioritize security by compartmentalizing tasks
and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is
nothing special about these qubes. If you were to create a black qube and
name it `vault`, it would be the same as the pre-configured `vault` qube.
They're just suggestions to get you started. )
A variety of open-source applications such as file managers, command-line
terminals, printer managers, text editors, and "applets" used to configure
different things like audio or parts of the user interface are also installed
by default—most within the templates. Most are bundled with each template.
Other software installed in Qubes OS by default includes open-source applications such as file managers,
command-line terminals, printer managers, text editors, and applets for configuring audio and user interface settings.
Most of these applications are incorporated within each template.
### Adding, removing, and listing qubes
You can easily create a new qube with the **Create Qubes VM** option in the App
Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add**
and **Remove** buttons. You can also add, remove, and list qubes from the
To create a new qube or remove one, use **Create Qubes VM** option in the App Menu.
Creating a New Qube:
Qubes Icon → Settings → Qubes Tools → Qube Manager → Create Qubes VM → **New Qube**
Removing a qube:
To remove a qube, use the **Delete qube button** as the final step instead.
You can also add, remove, and list qubes from the
command line using the following tools:
- `qvm-create`
@ -188,14 +188,8 @@ command line using the following tools:
### How many qubes do I need?
That's a great question, but there's no one-size-fits-all answer. It depends on
the structure of your digital life, and this is at least a little different for
everyone. If you plan on using your system for work, then it also depends on
what kind of job you do.
It's a good idea to start out with the qubes created automatically by the
installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start
to feel that some activity just doesn't fit into any of your existing qubes, or
It's a good idea to start out with the pre-installed app qubes: `work`, `personal`, `untrusted`, and `vault`.
If you start to feel that some activity just doesn't fit into any of your existing qubes, or
you want to partition some part of your life, you can easily create a new qube
for it. You'll also be able to easily [copy any
files](/doc/how-to-copy-and-move-files) you need to the newly-created qube.
@ -252,5 +246,5 @@ GitHub](https://github.com/QubesOS).
## Documentation
Peruse our extensive library of [documentation](/doc/) for users and developers
Browse our extensive library of [documentation](/doc/) for users and developers
of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)!

6
introduction/intro.md
View file

@ -19,7 +19,7 @@ title: Introduction
<p>
Qubes OS is a free and open-source, security-oriented operating system for
single-user desktop computing. Qubes OS leverages
<a href="https://wiki.xen.org/wiki/Xen_Project_Software_Overview">
<a href="https://wiki.xenproject.org/wiki/Xen_Project_Software_Overview">
Xen-based virtualization</a> to allow for the creation and management of
isolated compartments called <a href="/doc/glossary#qube">qubes</a>.
</p>
@ -136,9 +136,9 @@ title: Introduction
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>U2F proxy</h3>
<h3>CTAP proxy</h3>
<p>
Operate <a href="/doc/u2f-proxy/">Qubes U2F proxy</a> to use your
Operate <a href="/doc/ctap-proxy/">Qubes CTAP proxy</a> to use your
two-factor authentication devices without exposing your web browser to the
full USB stack.
</p>

70
introduction/issue-tracking.md
View file

@ -41,7 +41,7 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure
1. Carefully read our issue tracking [guidelines](#guidelines). If your issue would violate any of the guidelines, **stop**. Please do not submit it.
2. [Search through the existing issues](#search-tips), both open and closed, to see if your issue already exists. If it does, **stop**. [Do not open a duplicate.](/doc/issue-tracking/#new-issues-should-not-be-duplicates-of-existing-issues) Instead, comment on the existing issue.
3. Go [here](https://github.com/QubesOS/qubes-issues/issues/new/choose).
4. Select the [type](#type) of issue you want to open.
4. Select the [type](#types) of issue you want to open.
5. Enter a descriptive title.
6. Do not delete the provided issue template. Fill out every applicable section.
7. Make sure to mention any relevant documentation and other issues you've already seen. We don't know what you've seen unless you tell us. If you don't list it, we'll assume you haven't seen it.
@ -51,47 +51,57 @@ Great! Thank you for taking the time and effort to help improve Qubes! To ensure
Eventually, your issue may be closed. See [how issues get closed](/doc/issue-tracking/#how-issues-get-closed) for details about when, why, and how this occurs.
## Labels and projects
## How issues are organized
Labels and projects are features of GitHub's issue tracking system that we use to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
Issues can have several different properties and be organized in various ways. This section explains how we use labels, issue types, projects, and other features of GitHub's issue tracking system in order to keep [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) organized.
### Labels
When an issue is first created, certain [labels](https://github.com/QubesOS/qubes-issues/labels) may automatically be applied to it based on the type of issue the reporter selected. For example, if someone selects the "Bug report" template, then the `T: bug` label will automatically be applied to that issue. After that, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones.
#### Type
There are three issue **types**: `T: bug`, `T: enhancement`, and `T: task`.
- `T: bug` --- Type: bug report. A problem or defect resulting in unintended behavior in something that exists.
- `T: enhancement` --- Type: enhancement. A new feature that does not yet exist **or** improvement of existing functionality.
- `T: task` --- Type: task. An action item that is neither a bug nor an enhancement.
Every open issue should have **exactly one** type. An open issue should not have more than one type, and it should not lack a type entirely. Bug reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then use `T: enhancement` instead. If something already exists, but you think it could be improved in some way, you should again use `T: enhancement`. `T: task` is for issues that fall under under neither `T: bug` nor `T: enhancement`.
When an issue is first created, it will receive the `P: default` (i.e., default priority) [label](https://github.com/QubesOS/qubes-issues/labels) automatically. After an issue has been created, only Qubes team members have permission to modify labels. Many labels have descriptions on them that can be viewed by hovering over them or on the [list of labels](https://github.com/QubesOS/qubes-issues/labels). Let's go over some of the most important ones.
#### Priority
There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have **exactly one** priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities.
There are several issue **priority** levels ranging from `P: minor` to `P: blocker` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=P%3A) for the full list). Every open issue should have exactly one priority. An open issue should not have more than one priority, and it should not lack a priority entirely. See [here](/doc/version-scheme/#bug-priorities) for details about how the developers use these priorities.
#### Component
There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have **at least one** component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
There are many **component** labels, each beginning with `C:` (see [here](https://github.com/QubesOS/qubes-issues/labels?q=C%3A) for the full list). Every open issue should have at least one component. An open issue may have more than one component, but it should not lack a component entirely. When no other component applies, use `C: other`.
#### Affected release
A label of the form `affects-<RELEASE_NUMBER>` indicates that an issue affects the corresponding Qubes OS release. An issue can have more than one of these labels if it affects multiple releases.
### Types
There are three issue [types](https://docs.github.com/en/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization): Bug, Feature, and Task.
- **Bug** --- An unexpected problem or behavior
- **Feature** --- A request, idea, or new functionality
- **Task** --- A specific piece of work
Every open issue should have exactly one type. **Bug** reports are for problems in things that already exist. If something doesn't exist yet, but you think it ought to exist, then that issue should instead be a **Feature** request. If something already exists, but you think it could be improved in some way, that also qualifies as a **Feature** request. The **Task** type is for issues that are actionable but that fall under neither the **Bug** nor **Feature** types.
### Projects
The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). A project is a way to create a group of multiple related issues. This is the preferred method of grouping issues, whereas trying to use normal issues as "meta-issues" or "epics" is discouraged.
According to GitHub, a [project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) is "an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively." The issue tracker has several [projects](https://github.com/QubesOS/qubes-issues/projects). Github projects allows more detailed issue states, and also attaching more metadata to issues. They also allow more focused view.
There is a special project in Qubes OS project: the [Current team tasks project](https://github.com/orgs/QubesOS/projects/19/views/1) which represents current work of the core team. Issues in this project's **backlog** section are not yet ready for work - they might be waiting for clarifications, blockers, decisions on priorities etc. Issues that are **ready** can be picked up by any team member. There should not be too many issues in **ready** column to decrease confusion and decision paralysis - good number is around 20. The **in review** state means that the developer is finished with the work (the completion state has been reached) - if something has to be postponed or abandoned, a justification should be posted in issue discussion.
### Meta-issues
A meta-issue is an issue that serves primarily to collect and organize a group of other issues. This group of other issues typically exists in a hierarchy of [sub-issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues), usually with the meta-issue at the top. (For example, we use meta-issues when we need a way to track work on specific features. We cannot use [projects](#projects) for this, because we already use a project for tracking the work of the Qubes team as a whole, and projects cannot contain milestones or other projects.)
Meta-issues should have informative descriptions, not just lists of issues. In particular, each meta-issue should explain its goal, what is in scope, and what the relevant categories and priorities are.
In addition, meta-issues should have clear, concrete, and actionable criteria for when they will be closed. Meta-issues should never be "open-ended" or expected to stay open indefinitely. If this ever becomes unclear, the meta-issue should be closed until it becomes clear.
## Search tips
- [Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3Abug+sort%3Aupdated-desc).
- [Search both open and closed issues.](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue) For example, you may be experiencing a bug that was just fixed, in which case the report for that bug is probably closed. In this case, it would be useful to view [all bug reports, both open and closed, with the most recently updated sorted to the top](https://github.com/QubesOS/qubes-issues/issues?q=label%3A%22T%3A+bug%22+sort%3Aupdated-desc).
- [Search with labels.](https://github.com/QubesOS/qubes-issues/labels) For example, you can search issues by priority ([blocker](https://github.com/QubesOS/qubes-issues/labels/P%3A%20blocker), [critical](https://github.com/QubesOS/qubes-issues/labels/P%3A%20critical), [major](https://github.com/QubesOS/qubes-issues/labels/P%3A%20major), etc.) and by component ([core](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+core%22), [manager/widget](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22C%3A+manager%2Fwidget%22+), [Xen](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+Xen%22), etc.).
- Search by closure reason: [`reason:complete`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3Acompleted) and [`reason:"not planned"`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3A%22not+planned%22).
- Search by closure reason: [`reason:completed`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3Acompleted) and [`reason:"not planned"`](https://github.com/QubesOS/qubes-issues/issues?q=reason%3A%22not+planned%22).
- [Search by project](https://github.com/QubesOS/qubes-issues/projects).
@ -105,7 +115,7 @@ This guideline is important for keeping issues focused on *actionable informatio
### Do not submit questions
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes. Instead, see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate place to ask questions. By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
[qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is not the place to ask questions. This includes, but is not limited to, troubleshooting questions and questions about how to do things with Qubes. Instead, see [Help, Support, Mailing Lists, and Forum](/support/) for appropriate places to ask questions. By contrast, [qubes-issues](https://github.com/QubesOS/qubes-issues/issues) is meant for tracking more general bugs, enhancements, and tasks that affect a broad range of Qubes users.
### Use the issue template
@ -188,8 +198,26 @@ We close issues at step 3. Then, as updates are released, the issue automaticall
Therefore, if you see that an issue is closed, but the fix is not yet available to you, be aware that it may be at an intermediate stage of this process between issue closure and the update being available in whichever repos you have enabled in whichever version of Qubes you're using.
In order to assist with this, we have a label called [backport pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may be need to adjust it manually.
In order to assist with this, we have a label called [backport pending](https://github.com/QubesOS/qubes-issues/labels/backport%20pending), which means, "The fix has been released for the testing release but is pending backport to the stable release." Our infrastructure will attempt to apply this label automatically, when appropriate, but it is not perfect, and the developers may need to adjust it manually.
### Understanding open and closed issues
Every issue is always in one of two states: open or closed, with open being the default. The **open** and **closed** states mean that, according to our available information at present, the issue in question either **is** or **is not** (respectively) actionable for the Qubes team. The open and closed states do not mean anything more than this, and it's important not to read anything else into them. It's also important to understand that closing an issue is, in effect, nothing more than changing a virtual tag on an issue. Closing an issue is never "final" in any sense, and it does not affect the issue itself in any other way. Issues can be opened and closed instantly with a single button press an unlimited number of times at no cost. In fact, since the open and closed states reflect our available information at present, one should expect these states to change back and forth as new information becomes available. Closed issues are fully searchable, just like open issues, and we explicitly instruct all users of the issue tracker to search *both* open *and* closed issues, which GitHub makes easy.
## Workflow and what do issue states mean
There are some rules we use when assigning issues and tagging them.
### Assigning issues
To avoid a situation where an issue is "dead" - assigned to someone who is not actively working on it - and to help the team organize their work, an issue should be assigned to a person who currently works on it, or will start working on it in a very near future (about a week or two). One person can have several issues assigned at the same time (for example they may be working on one another issue while waiting for review), but if an issue is no longer actively being worked on (for example when it's blocked by something else), it should be unassigned. At that point, if there is some partial work already done, there should be a comment about that, including link to the code (some WIP commit in some branch?) if applicable.
Issues should not be assigned as a todo-list several months in the future, or assigned to someone without their explicit confirmation that they are currently working on that issue or will start doing it shortly.
### Working on an issue
Every issue should involve a clear statement of success: when is the issue finished? It might not be clear to the person making the issue, especially if it's an enhancement request, but before work starts, the person working on the issue should make sure that it includes clear completion criteria in the description (via editing the description, if necessary). The completion criteria would ideally be a checklist, and consist of a list of pull requests/features, each preferably no more than two weeks of work. It's also important to remember tests and documentation should also be part of the issue, if applicable.
An issue should also have a rough estimate how much time it needs, if it's more than one-two days. Of course this might be updated later, if an issue turns out to be more (or maybe less) complicated than it has initially seemed.
When an issue is done (that is, the completion checklist has been completed), the issue should be moved to **ready** column in the *Current team tasks* project.

1
introduction/screenshots.md
View file

@ -61,6 +61,7 @@ Qubes is all about seamless integration from the user’s point of view. Here yo
[![r4.0-manager-and-sysnet-network-prompt.png](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png)](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png)
All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems)
* * * * *
[![r4.0-software-update.png](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png)

32
introduction/support.md
View file

@ -39,7 +39,7 @@ No worries! Here's how we recommend proceeding:
3. Try [searching the issue tracker](/doc/issue-tracking/#search-tips). There
may already be an open **or closed** issue about your problem. The issue
tracker is constantly being updated with known bugs and may contain
workarounds for problems you're experiencing. If there any pinned issues at
workarounds for problems you're experiencing. If there are any pinned issues at
the top, make sure to check them first!
4. Try [searching the Qubes Forum](https://forum.qubes-os.org/). There may
@ -176,7 +176,7 @@ information in your message. A great way to provide your hardware details is by
[generating and submitting a Hardware Compatibility List (HCL)
report](/doc/how-to-use-the-hcl/#generating-and-submitting-new-reports), then
linking to it in your message. [Ask questions the smart
way.](http://www.catb.org/esr/faqs/smart-questions.html)
way.](https://www.catb.org/esr/faqs/smart-questions.html)
### Be patient
@ -226,7 +226,7 @@ The moderation team aims to enforce our [Code of Conduct](/code-of-conduct/).
Beyond this, users should not expect any specific action from the moderation
team. Specifically, users should not request that posts or messages be deleted
or edited by a moderator. Users are reminded that, in most venues, anything
posted will be sent out as an email to other others, and these emails cannot be
posted will be sent out as an email to others, and these emails cannot be
deleted from others' inboxes.
### Specific mailing list rules and notes
@ -309,7 +309,7 @@ account is in no way required, expected, or encouraged. Many discussants
[mailing lists](https://en.wikipedia.org/wiki/Electronic_mailing_list),
interacting with them solely through plain text email with
[MUAs](https://en.wikipedia.org/wiki/Email_client) like
[Thunderbird](https://www.thunderbird.net/) and [Mutt](http://www.mutt.org/).
[Thunderbird](https://www.thunderbird.net/) and [Mutt](https://www.mutt.org/).
The Google Groups service is just free infrastructure, and we [distrust the
infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure). This
is why, for example, we encourage discussants to use [Split
@ -403,7 +403,7 @@ interface](https://groups.google.com/group/qubes-devel).
This list is for non-technical discussion and coordination around the Qubes OS
project.
Examples of topics or question suitable for this list include:
Examples of topics or questions suitable for this list include:
* Participation (talks, workshops, etc.) at upcoming events
* Project funding applications and strategies
@ -419,7 +419,7 @@ account is **not** required. Any email address will work.) To post a message to
the list, address your email to `qubes-project@googlegroups.com`. If your post
does not appear immediately, please allow time for moderation to occur. To
unsubscribe, send a blank email to
`qubes-project+unsubscribe@googlegroups.com`. This list also also has a
`qubes-project+unsubscribe@googlegroups.com`. This list also has a
[traditional mail
archive](https://www.mail-archive.com/qubes-project@googlegroups.com/) and an
optional [Google Groups web
@ -430,7 +430,7 @@ interface](https://groups.google.com/group/qubes-project).
This list is for discussion around the localization and translation of Qubes
OS, its documentation, and the website.
Examples of topics or question suitable for this list include:
Examples of topics or questions suitable for this list include:
* Questions about or issues with [Transifex](https://www.transifex.com/), the
translation platform we use
@ -499,11 +499,11 @@ too](https://forum.qubes-os.org/t/using-the-forum-via-email/533)!)
The Qubes OS Project has a presence on the following social media platforms:
- <a rel="me" href="https://twitter.com/QubesOS">Twitter</a>
- <a rel="me" href="https://mastodon.social/@QubesOS">Mastodon</a>
- <a rel="me" href="https://www.reddit.com/r/Qubes/">Reddit</a>
- <a rel="me" href="https://www.facebook.com/QubesOS/">Facebook</a>
- <a rel="me" href="https://www.linkedin.com/company/qubes-os/">LinkedIn</a>
- [Twitter](https://twitter.com/QubesOS)
- [Mastodon](https://mastodon.social/@QubesOS)
- [Reddit](https://www.reddit.com/r/Qubes/)
- [Facebook](https://www.facebook.com/QubesOS/)
- [LinkedIn](https://www.linkedin.com/company/qubes-os/)
Generally speaking, these are not intended to be primary support venues. (Those
would be [qubes-users](#qubes-users) and the [forum](#forum).) Rather, these
@ -514,8 +514,12 @@ news.
## Chat
If you'd like to chat, join us on the `#qubes` IRC channel (or its Matrix
bridge: `#qubes:libera.chat`).
If you'd like to chat, join us on
- the `#qubes` channel on `irc.libera.chat` or
- the `#qubes:invisiblethingslab.com` matrix channel.
these two should be linked/bridged, but for technical reasons currently are not.
## Unofficial venues

2
introduction/video-tours.md
View file

@ -22,7 +22,7 @@ Watch all the talks from Qubes OS Summit 2022, which took place September 9-11,
## Micah Lee presents "Qubes OS: The Operating System That Can Protect You Even If You Get Hacked"
[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://www.hope.net/schedule.html#-qubes-os-the-operating-system-that-can-protect-you-even-if-you-get-hacked-) at the [Circle of HOPE](https://www.hope.net/index.html) conference, which took place July 20-22, 2018 in New York City.
[Micah Lee](https://micahflee.com/), a long-time Qubes [advocate](/endorsements/), presented [Qubes OS: The Operating System That Can Protect You Even If You Get Hacked](https://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee) at the Circle of HOPE conference, which took place July 20-22, 2018 in New York City.
<div class="video more-bottom">
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://livestream.com/accounts/9197973/events/8286152/videos/178431606/player?autoPlay=false"></iframe>

1
project-security/security.md
View file

@ -93,4 +93,3 @@ of the actions listed above.
- [Marek Marczykowski-Górecki](/team/#marek-marczykowski-górecki)
- [Simon Gaiser (aka HW42)](/team/#simon-gaiser-aka-hw42)
- [Joanna Rutkowska](/team/#joanna-rutkowska) ([emeritus, canaries only](/news/2018/11/05/qubes-security-team-update/))

52
project-security/verifying-signatures.md
View file

@ -190,8 +190,9 @@ you see here may not be genuine. That's why we strongly suggest obtaining the
fingerprint from *multiple independent sources in several different ways*, then
comparing the strings of letters and numbers to make sure they match.
When it comes to PGP fingerprints, spaces and capitalization don't matter. In
other words, all of these fingerprints are considered the same:
For the purpose of convincing yourself that you know the authentic QMSK
fingerprint, spaces and capitalization don't matter. In other words, all of
these fingerprints are considered the same:
```
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
@ -201,12 +202,16 @@ other words, all of these fingerprints are considered the same:
```
Instead, what matters is that *all* the characters are present in *exactly* the
same order. If even one character is different, the fingerprints do not match.
Even if two fingerprints have all the same characters, if any of those
characters are in a different order, sequence, or position, then the
fingerprints do not match.
same order. If even one character is different, the fingerprints should not be
considered the same. Even if two fingerprints have all the same characters, if
any of those characters are in a different order, sequence, or position, then
the fingerprints should not be considered the same.
You may also sometimes see the entire fingerprint prefixed with `0x`, as in:
However, for the purpose of *searching for*, *looking up*, or *entering* keys,
spaces and capitalization can matter, depending on the software or tool you're
using. You may need to try different variations (e.g., with and without
spaces). You may also sometimes see (or need to enter) the entire fingerprint
prefixed with `0x`, as in:
```
0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
@ -214,10 +219,12 @@ You may also sometimes see the entire fingerprint prefixed with `0x`, as in:
```
The `0x` prefix is sometimes used to indicate that the string following it is a
hexadecimal value, and some PGP-related tools may require this prefix. For the
purpose of comparing fingerprints as described here, you may safely ignore the
`0x` prefix, as it is not part of the fingerprint. As long as the 40-character
string after the `0x` matches exactly, the fingerprint is the same.
hexadecimal value, and some PGP-related tools may require this prefix. Again,
for the purpose of convincing yourself that you know the authentic QMSK
fingerprint, you may safely ignore the `0x` prefix, as it is not part of the
fingerprint. As long as the 40-character string after the `0x` matches exactly,
the fingerprint is considered the same. The `0x` prefix only matters if the
software or tool you're using cares about it.
The general idea of "comparing fingerprints" is to go out into the world
(whether digitally, physically, or both) and find other 40-character strings
@ -368,11 +375,11 @@ by the QMSK:
```shell_session
$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
pub rsa4096 YYYY-MM-DD [SC]
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uid [ full ] Qubes OS Release X Signing Key
sig!3 1848792F9E2795E9 2017-03-06 Qubes OS Release X Signing Key
sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key
sig!3 XXXXXXXXXXXXXXXX YYYY-MM-DD Qubes OS Release X Signing Key
sig! DDFA1A3E36879494 YYYY-MM-DD Qubes Master Signing Key
gpg: 2 good signatures
```
@ -390,9 +397,9 @@ As a final sanity check, make sure the RSK is in your keyring with the correct
trust level:
```shell_session
$ gpg2 -k "Qubes OS Release"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
$ gpg2 -k "Qubes OS Release X Signing Key"
pub rsa4096 YYYY-MM-DD [SC]
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uid [ full ] Qubes OS Release X Signing Key
```
@ -526,7 +533,7 @@ $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
gpg: armor header: Version: GnuPG v2
gpg: original file name=''
gpg: Signature made Tue 20 Sep 2016 10:37:03 AM PDT using RSA key ID 03FA5082
gpg: Signature made <TIME> using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: textmode signature, digest algorithm SHA256
@ -571,7 +578,7 @@ executing this GPG command in the directory that contains both files:
```shell_session
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: armor header: Version: GnuPG v1
gpg: Signature made Tue 08 Mar 2016 07:40:56 PM PST using RSA key ID 03FA5082
gpg: Signature made <TIME> using RSA key ID 03FA5082
gpg: using PGP trust model
gpg: Good signature from "Qubes OS Release X Signing Key"
gpg: binary signature, digest algorithm SHA256
@ -691,8 +698,8 @@ Qubes ISOs](#how-to-verify-detached-pgp-signatures-on-qubes-isos).)
```shell_session
$ dd if=/dev/sdX bs=1M count=<ISO_SIZE> iflag=count_bytes | gpg -v --verify Qubes-RX-x86_64.iso.asc -
gpg: Signature made Thu 14 Jul 2022 08:49:38 PM PDT
gpg: using RSA key 5817A43B283DE5A9181A522E1848792F9E2795E9
gpg: Signature made <TIME>
gpg: using RSA key XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
gpg: using pgp trust model
gpg: Good signature from "Qubes OS Release X Signing Key" [full]
gpg: binary signature, digest algorithm SHA256, key algorithm rsa4096
@ -826,6 +833,7 @@ the arguments to `gpg2`. (The signature file goes first.)
### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."?
There are several possibilities:
- You don't have the [Qubes Master Signing
Key](#how-to-import-and-authenticate-the-qubes-master-signing-key).
- You have not [set the Qubes Master Signing Key's trust level

60
user/advanced-topics/bind-dirs.md
View file

@ -8,21 +8,20 @@ ref: 186
title: How to make any file persistent (bind-dirs)
---
## What are bind-dirs? ##
## What are bind-dirs?
With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
any arbitrary files or folders can be made persistent in app qubes.
## What is it useful for? ##
## What is it useful for?
In an app qube all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`.
This means that changes in the rest of the filesystem are lost when the app qube is shutdown.
bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone.
For example, in Whonix, Tor's data dir `/var/lib/tor` [has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5). In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone.
## How to use bind-dirs.sh? ##
## How to use bind-dirs.sh?
In this example, we want to make `/var/lib/tor` persistent. Enter all of the following commands in your app qube.
@ -60,7 +59,7 @@ In this example, we want to make `/var/lib/tor` persistent. Enter all of the fol
From now on, all files in the `/var/lib/tor` directory will persist across reboots.
You can make make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
You can make as many files or folders persist as you want simply by making multiple entries in the `50_user.conf` file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file would also persist across reboots.
```
@ -68,13 +67,13 @@ binds+=( '/var/lib/tor' )
binds+=( '/etc/tor/torrc' )
```
## Other Configuration Folders ##
## Other Configuration Folders
* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
* `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration)
* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
## How does it work? ##
## How does it work?
bind-dirs.sh is called at startup of an app qube, and configuration files in the above configuration folders are parsed to build a bash array.
Files or folders identified in the array are copied to `/rw/bind-dirs` if they do not already exist there, and are then bind mounted over the original files/folders.
@ -84,7 +83,7 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir
If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot.
Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor`
## Limitations ##
## Limitations
* Files that exist in the template root image cannot be deleted in the app qubes root image using bind-dirs.sh.
* Re-running `sudo /usr/lib/qubes/init/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/init/bind-dirs.sh umount` does not work.
@ -93,9 +92,9 @@ Note that you must create the full folder structure under `/rw/bind-dirs` - e.g
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
* Some files are altered when a qube boots - e.g. `/etc/hosts`.
If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files).
## How to remove binds from bind-dirs.sh? ##
## How to remove binds from bind-dirs.sh?
`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are sourced as bash snippets in lexical order.
Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file.
@ -109,6 +108,45 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is strongly discouraged, since such changes get lost when that file is changed in the package on upgrades.)
## Custom persist feature ##
Custom persist is an optional advanced feature allowing the creation of minimal state AppVM. The purpose of such an AppVM is to avoid unwanted data to persist as much as possible by disabling the ability to configure persistence from the VM itself. When enabled, the following happens:
* ``/rw/config/rc.local`` is no longer executed
* ``/rw/config/qubes-firewall-user-script`` is ignored
* ``/rw/config/suspend-module-blacklist`` is ignored
* User bind dirs defined in ``/rw/config/qubes-bind-dirs.d`` are no longer read
* ``/home`` and ``/user/local`` are not persistent anymore unless explicitly configured.
Bind dirs are obviously still supported but this must be configured either in the template (``/usr/lib/qubes-bind-dirs.d`` and ``/etc/qubes-bind-dirs.d``) or from dom0 using ``qvm-features``. The bind dirs declaration must be done this way: ``qvm-features <VMNAME> custom-persist.<ARBITRARY NAME> [PRE-CREATION SETTINGS]<PATH>``
To use this feature, first, enable it:
```
qvm-service -e my-app-vm custom-persist
```
Then, configure a persistent directory with ``qvm-features``:
```
qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir
```
To re-enable ``/home`` and ``/usr/local`` persistence, just add them to the list:
```
qvm-features my-app-vm custom-persist.home /home
qvm-features my-app-vm custom-persist.usrlocal /usr/local
```
When starting the VM, declared custom-persist bind dirs are automatically added to the ``binds`` variable described above and are handled in the same way.
A user may want their bind-dirs to be automatically pre-created in ``/rw/bind-dirs``. Custom persist can do this for you by providing the type of the resource to create (file or dir), owner, group and mode. For example:
```
qvm-features my-app-vm custom-persist.downloads dir:user:user:0755:/home/user/Downloads
qvm-features my-app-vm custom-persist.my_ssh_known_hosts_file file:user:user:0600:/home/user/.ssh/known_hosts
```
## Discussion ##
[app qubes: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)

13
user/advanced-topics/config-files.md
View file

@ -11,15 +11,14 @@ ref: 180
title: Config files
---
Qubes-specific VM config files
------------------------------
## Qubes-specific VM config files
These files are placed in `/rw`, which survives a VM restart.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
The scripts here all run as root.
- `/rw/config/rc.local` - script runs at VM startup.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. The script need to have the executable permission set to be executed.
Example usage:
~~~
@ -33,6 +32,8 @@ The scripts here all run as root.
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
- `/rw/config/rc.local.d/*.rc` - scripts run at VM startup just before `/rw/config/rc.local`
- `/rw/config/rc.local-early.d/*.rc`, `/rw/config/rc.local-early` - scripts similar to `/rw/config/rc.local`, but running earlier in the system startup sequence - just before `sysinit.target`, and setting up the network.
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- In ProxyVMs (or app qubes with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
@ -76,8 +77,7 @@ Note that scripts need to be executable (`chmod +x`) to be used.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an app qube and have those changes persist.
GUI and audio configuration in dom0
-----------------------------------
## GUI and audio configuration in dom0
The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by `qubes-prefs` or the Qubes Manager tool.
Sample config (included in default installation):
@ -115,8 +115,7 @@ VM: {
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
**Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
- **Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".

2
user/advanced-topics/disposable-customization.md
View file

@ -27,7 +27,7 @@ Additionally, if you want to have menu entries for starting applications in disp
[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
```
**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
## Security

7
user/advanced-topics/gui-configuration.md
View file

@ -21,7 +21,7 @@ qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
qvm-features dom0 gui-videoram-overhead 0
```
Where `$WIDTH`×`$HEIGHT` is the maximum desktop size that you anticipate needing.
Where `$WIDTH` × `$HEIGHT` is the maximum desktop size that you anticipate needing.
For example, if you expect to use a 1080p display and a 4k display side-by-side, that is `(1920 + 3840) × 2160 × 4 / 1024 = 48600`, or slightly more than 48 MiB per qube.
After making these adjustments, the qubes need to be restarted.
@ -31,6 +31,7 @@ qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e
```
The amount of memory allocated per qube is the maximum of:
- `gui-videoram-min`
- current display + `gui-videoram-overhead`
@ -41,8 +42,8 @@ You might face issues when playing video, if the video is choppy instead of
smooth display this could be because the X server doesn't work. You can use the
Linux terminal (Ctrl-Alt-F2) after starting the virtual machine, login. You can
look at the Xorg logs file. As an option you can have the below config as
well present in `/etc/X11/xorg.conf.d/90-intel.conf`, depends on HD graphics
though -
well present in `/etc/X11/xorg.conf.d/90-intel.conf` (depends on HD graphics
though).
```bash
Section "Device"

30
user/advanced-topics/gui-domain.md
View file

@ -45,6 +45,8 @@ At this point, you need to shutdown all your running qubes as the `default_guivm
Here, we describe how to setup `sys-gui-gpu` which is a GUI domain with *GPU passthrough* in [GUI domain](/news/2020/03/18/gui-domain/#gpu-passthrough-the-perfect-world-desktop-solution).
> Note: the purpose of `sys-gui-gpu` is to improve Qubes OS security by detaching the GPU from dom0, this is not intended to improve GPU related performance within qubes, and this will not improve performance.
[![sys-gui-gpu](/attachment/posts/guivm-gpu.png)](/attachment/posts/guivm-gpu.png)
In `dom0`, enable the formula for `sys-gui-gpu` with pillar data:
@ -120,13 +122,33 @@ A VNC server session is running on `localhost:5900` in `sys-gui-vnc`. In order t
> **WARNING**: This setup raises multiple security issues: 1) Anyone who can reach the `VNC` server, can take over the control of the Qubes OS machine, 2) A second client can connect even if a connection is already active and potentially get disconnected, 3) You can get disconnected by some unrelated network issues. Generally, if this `VNC` server is exposed to open network, it must be protected with some other (cryptographic) layer like `VPN`. The setup as is, is useful only for purely testing machine.
### Troubleshooting
### Known issues
#### Application menu lacks qubes entries in a fresh GUI domain
See [QubesOS/qubes-issues#5804](https://github.com/QubesOS/qubes-issues/issues/5804)
#### Delete GUI domain
#### Cannot update dom0 from sys-gui
See [QubesOS/qubes-issues#8934](https://github.com/QubesOS/qubes-issues/issues/8934)
#### GUI of HVM qubes not visible
See [QubesOS/qubes-issues#9385](https://github.com/QubesOS/qubes-issues/issues/9385)
### Power saving/screensaver issues
See [QubesOS/qubes-issues#9033](https://github.com/QubesOS/qubes-issues/issues/9033), [QubesOS/qubes-issues#9384](https://github.com/QubesOS/qubes-issues/issues/9384), [QubesOS/qubes-issues#7989](https://github.com/QubesOS/qubes-issues/issues/7989)
#### Qube startup order (sys-usb and sys-gui)
See [QubesOS/qubes-issues#7954](https://github.com/QubesOS/qubes-issues/issues/7954)
#### Other GUI domain issues
see existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.
### Reverting sys-gui
The following commands have to be run in `dom0`.
@ -149,7 +171,3 @@ You are now able to delete the GUI domain, for example `sys-gui-gpu`:
```bash
qvm-remove -f sys-gui-gpu
```
#### General issues
For any general GUI domain issues, please take a loot at existing issues `QubesOS/qubes-issues` under [C: gui-domain](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+gui-domain%22) label.

55
user/advanced-topics/how-to-install-software-in-dom0.md
View file

@ -65,44 +65,15 @@ commands to `dnf` using `--action=...`.
**WARNING:** Downgrading a package can expose your system to security
vulnerabilities.
1. Download an older version of the package:
To downgrade a specific package in dom0:
~~~
sudo qubes-dom0-update package-version
~~~
Dnf will say that there is no update, but the package will nonetheless be
downloaded to dom0.
2. Downgrade the package:
~~~
sudo dnf downgrade package-version
~~~
sudo qubes-dom0-update --action=downgrade package-version
## How to re-install a package
You can re-install in a similar fashion to downgrading.
To re-install a package in dom0:
1. Download the package:
~~~
sudo qubes-dom0-update package
~~~
Dnf will say that there is no update, but the package will nonetheless be
downloaded to dom0.
2. Re-install the package:
~~~
sudo dnf reinstall package
~~~
Note that `dnf` will only re-install if the installed and downloaded
versions match. You can ensure they match by either updating the package to
the latest version, or specifying the package version in the first step
using the form `package-version`.
sudo qubes-dom0-update --action=reinstall package
## How to uninstall a package
@ -209,23 +180,7 @@ to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoy
This section describes changing the default kernel in dom0. It is sometimes
needed if you have upgraded to a newer kernel and are having problems booting,
for example. The procedure varies depending on if you are booting with UEFI or
grub. On the next kernel update, the default will revert to the newest.
### EFI
~~~
sudo nano /boot/efi/EFI/qubes/xen.cfg
~~~
In the `[global]` section at the top, change the `default=` line to match one
of the three boot entries listed below. For example:
~~~
default=4.19.67-1.pvops.qubes.x86_64
~~~
### Grub2
for example. On the next kernel update, the default will revert to the newest.
~~~
sudo nano /etc/default/grub

10
user/advanced-topics/i3.md
View file

@ -24,7 +24,7 @@ optionally in case you would prefer writing your own configuration (see
That's it. After logging out, you can select i3 in the login manager.
### Customization
# Customization
**Caution:** The following external resources may not have been reviewed by the Qubes team.
@ -34,13 +34,13 @@ That's it. After logging out, you can select i3 in the login manager.
* [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config)
* [dmenu script to open a terminal in a chosen VM](https://gist.github.com/dmoerner/65528941dd20b05c98ee79e92d7e0183)
## Compilation and installation from source
# Compilation and installation from source
Note that the compilation from source is done in a Fedora based domU (could
be dispvm). The end result is always an `.rpm` that is copied to dom0 and then
installed through the package manager.
### Getting the code
## Getting the code
Clone the i3-qubes repository here:
@ -57,7 +57,7 @@ OS and changes some defaults so the user can't override decisions.
If you want to make any changes to the package, this is the time and place to do
it.
### Building
## Building
You'll need to install the build dependencies, which are listed in
build-deps.list. You can verify them and then install them with:
@ -76,7 +76,7 @@ $ make verify-sources
$ make rpms
```
### Installing
## Installing
**Warning**: Manually installing software in dom0 is inherently risky, and the method described here circumvents the usual security mechanisms of qubes-dom0-update.

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