mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-04-25 10:19:23 -04:00
Compare commits
No commits in common. "main" and "qm_8a23c91c" have entirely different histories.
main
...
qm_8a23c91
@ -12,41 +12,42 @@ title: Development workflow
|
|||||||
|
|
||||||
A workflow for developing Qubes OS+
|
A workflow for developing Qubes OS+
|
||||||
|
|
||||||
To begin, setup [QubesBuilder](/doc/qubes-builder-v2/). This guide
|
First things first, setup [QubesBuilder](/doc/qubes-builder/). This guide
|
||||||
assumes you're using qubes-builder v2 to build Qubes.
|
assumes you're using qubes-builder to build Qubes.
|
||||||
|
|
||||||
## Repositories and committing Code
|
## Repositories and committing Code
|
||||||
|
|
||||||
Qubes source code is split into many git repos. These are all contained in the
|
Qubes is split into a bunch of git repos. These are all contained in the
|
||||||
`artifacts/sources` directory under qubes-builder. Subdirectories there are
|
`qubes-src` directory under qubes-builder. Subdirectories there are separate
|
||||||
separate components, stored in separate git repositories.
|
components, stored in separate git repositories.
|
||||||
|
|
||||||
The best way to write and contribute code is to create a git repo somewhere
|
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
|
`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
|
of Qubes, cd to the repo directory and add your repository as a remote in git
|
||||||
|
|
||||||
**Example:**
|
**Example:**
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
$ cd qubes-builder/artifacts/sources/qubes-manager
|
$ cd qubes-builder/qubes-src/qubes-manager
|
||||||
$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git
|
$ 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
|
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.
|
commits from the dev branches, merge them, and eventually push to your own repo
|
||||||
|
on github.
|
||||||
|
|
||||||
When you are ready to submit your changes to Qubes to be merged, push your
|
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
|
changes, then create a signed git tag (using `git tag -s`). Finally, send a
|
||||||
letter to the Qubes listserv describing the changes, and including a link to
|
letter to the Qubes listserv describing the changes and including the link to
|
||||||
your repository. If you are using GitHub you can instead create a pull request.
|
your repository. You can also create pull request on github. Don't forget to
|
||||||
Don't forget to include the public PGP key you use to sign your tags.
|
include your public PGP key you use to sign your tags.
|
||||||
|
|
||||||
### Kernel-specific notes
|
### Kernel-specific notes
|
||||||
|
|
||||||
#### Prepare fresh version of kernel sources, with Qubes-specific patches applied
|
#### Prepare fresh version of kernel sources, with Qubes-specific patches applied
|
||||||
|
|
||||||
In qubes-builder/artifacts/sources/linux-kernel:
|
In qubes-builder/qubes-src/linux-kernel:
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
make prep
|
make prep
|
||||||
@ -65,7 +66,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
|
#### Go to the kernel tree and update the version
|
||||||
|
|
||||||
In qubes-builder/artifacts/sources/linux-kernel:
|
In qubes-builder/qubes-src/linux-kernel:
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
cd kernel-3.4.18/linux-3.4.18
|
cd kernel-3.4.18/linux-3.4.18
|
||||||
@ -116,7 +117,9 @@ vi series.conf
|
|||||||
|
|
||||||
#### Building RPMs
|
#### Building RPMs
|
||||||
|
|
||||||
Now is a good moment to make sure you have changed the kernel release name in
|
TODO: Is this step generic for all subsystems?
|
||||||
|
|
||||||
|
Now it is a good moment to make sure you have changed kernel release name in
|
||||||
rel file. For example, if you change it to '1debug201211116c' the
|
rel file. For example, if you change it to '1debug201211116c' the
|
||||||
resulting RPMs will be named
|
resulting RPMs will be named
|
||||||
'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help
|
'kernel-3.4.18-1debug20121116c.pvops.qubes.x86\_64.rpm'. This will help
|
||||||
@ -128,23 +131,34 @@ your changes locally.
|
|||||||
To actually build RPMs, in qubes-builder:
|
To actually build RPMs, in qubes-builder:
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
./qb -c linux-kernel package fetch prep build
|
make linux-kernel
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
RPMs will appear in
|
RPMs will appear in qubes-src/linux-kernel/pkgs/fc20/x86\_64:
|
||||||
`artifacts/repository/destination_name/package_name`
|
|
||||||
(for example `artifacts/repository/host-fc37/linux-kernel-6.6.31-1.1/`
|
|
||||||
|
|
||||||
### Useful [QubesBuilder](/doc/qubes-builder-v2/) commands
|
~~~
|
||||||
|
-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
|
||||||
|
~~~
|
||||||
|
|
||||||
1. `./qb package diff` - show uncommitted changes
|
### Useful [QubesBuilder](/doc/qubes-builder/) commands
|
||||||
2. ` ./qb repository check-release-status-for-component` and
|
|
||||||
`./qb repository check-release-status-for-template`- show version of each
|
1. `make check` - will check if all the code was committed into repository and
|
||||||
component/template (based on git tags)
|
if all repository are tagged with signed tag.
|
||||||
3. `./qb package sign` - sign built packages
|
2. `make show-vtags` - show version of each component (based on git tags) -
|
||||||
4. `./qb package publish` and `./qb package upload` - publish signed packages
|
mostly useful just before building ISO. **Note:** this will not show version
|
||||||
and upload published
|
for components containing changes since last version tag.
|
||||||
repository
|
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.
|
||||||
|
|
||||||
## Copying Code to dom0
|
## Copying Code to dom0
|
||||||
|
|
||||||
@ -283,12 +297,12 @@ if [ "$1" = "tb" ]; then
|
|||||||
exit $?
|
exit $?
|
||||||
fi
|
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
|
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
|
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
|
the same name. In any case it points at repository matching current directory
|
||||||
name.
|
name.
|
||||||
|
|
||||||
@ -307,7 +321,7 @@ current and current-testing).
|
|||||||
|
|
||||||
### RPM packages - yum repo
|
### 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:
|
`~/repo-yum-upload` directory) and replace `update_repo.sh` script with:
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
@ -323,7 +337,7 @@ find -type f -name '*.rpm' -delete
|
|||||||
qrexec-client-vm $VMNAME local.UpdateYum
|
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
|
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
|
packages (it is possible to force yum to install unsigned packages, but it
|
||||||
isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
|
isn't possible for `qubes-dom0-update` tool). Fill `~/.rpmmacros` with
|
||||||
@ -403,7 +417,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:
|
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 different `update_repo.sh` script in source VM (below)
|
||||||
- use `local.UpdateApt` qrexec service in target VM (code below)
|
- use `local.UpdateApt` qrexec service in target VM (code below)
|
||||||
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
|
- in target VM additionally place `update-local-repo.sh` script in repository dir (code below)
|
||||||
|
|||||||
@ -1,162 +0,0 @@
|
|||||||
---
|
|
||||||
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:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# 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.
|
|
||||||
|
|
||||||
@ -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
|
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.
|
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-v2/).
|
The below example however will assume that you set up a build environment as described in the [Qubes Builder documentation](/doc/qubes-builder/).
|
||||||
|
|
||||||
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
|
Assuming you cloned the `qubes-builder` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests:
|
||||||
|
|
||||||
|
|||||||
@ -205,10 +205,9 @@ pushd ${HOME}/builder >/dev/null
|
|||||||
|
|
||||||
# the following are needed only if you have sources outside builder
|
# the following are needed only if you have sources outside builder
|
||||||
#rm -rf qubes-src/core-admin
|
#rm -rf qubes-src/core-admin
|
||||||
#qb -c core-admin package fetch
|
#make COMPONENTS=core-admin get-sources
|
||||||
|
|
||||||
qb -c core-admin -d host-fc41 prep build
|
make core-admin
|
||||||
# update your dom0 fedora distribution as appropriate
|
|
||||||
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
|
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
|
||||||
qtb-runtests
|
qtb-runtests
|
||||||
```
|
```
|
||||||
|
|||||||
@ -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.
|
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-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.
|
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.
|
||||||
|
|
||||||
### Contributor proposal guidelines
|
### Contributor proposal guidelines
|
||||||
|
|
||||||
@ -422,7 +422,7 @@ for more information and qubes-specific background.
|
|||||||
|
|
||||||
**Difficulty**: medium
|
**Difficulty**: medium
|
||||||
|
|
||||||
**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.
|
**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.
|
||||||
|
|
||||||
**Size of the project**: 350 hours
|
**Size of the project**: 350 hours
|
||||||
|
|
||||||
|
|||||||
@ -62,98 +62,95 @@ yet documented.
|
|||||||
The API should be implemented as a set of qrexec calls. This is to make it easy
|
The API should be implemented as a set of qrexec calls. This is to make it easy
|
||||||
to set the policy using current mechanism.
|
to set the policy using current mechanism.
|
||||||
|
|
||||||
| call | dest | argument | inside | return | note |
|
| call | dest | argument | inside | return | note |
|
||||||
|------------------------------------------------|------------|--------------|---------------------------------------------------------------------|-----------------------------------------------------| ---- |
|
| ------------------------------------- | --------- | --------- | ----------------------------------------- | --------------------------------------------------------- | ---- |
|
||||||
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
|
| `admin.vmclass.List` | `dom0` | - | - | `<class>\n` |
|
||||||
| `admin.vm.List` | `dom0 | <vm>` | - | - | `<name> class=<class> state=<state>\n` |
|
| `admin.vm.List` | `dom0|<vm>` | - | - | `<name> class=<class> state=<state>\n` |
|
||||||
| `admin.vm.Create.<class>` | `dom0` | template | `name=<name> label=<label>` | - |
|
| `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.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.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.vm.Remove` | vm | - | - | - |
|
||||||
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
|
| `admin.label.List` | `dom0` | - | - | `<property>\n` |
|
||||||
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
|
| `admin.label.Create` | `dom0` | label | `0xRRGGBB` | - |
|
||||||
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
|
| `admin.label.Get` | `dom0` | label | - | `0xRRGGBB` |
|
||||||
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
|
| `admin.label.Index` | `dom0` | label | - | `<label-index>` |
|
||||||
| `admin.label.Remove` | `dom0` | label | - | - |
|
| `admin.label.Remove` | `dom0` | label | - | - |
|
||||||
| `admin.property.List` | `dom0` | - | - | `<property>\n` |
|
| `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.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.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.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.Help` | `dom0` | property | - | `help` |
|
||||||
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
|
| `admin.property.HelpRst` | `dom0` | property | - | `help.rst` |
|
||||||
| `admin.property.Reset` | `dom0` | property | - | - |
|
| `admin.property.Reset` | `dom0` | property | - | - |
|
||||||
| `admin.property.Set` | `dom0` | property | value | - |
|
| `admin.property.Set` | `dom0` | property | value | - |
|
||||||
| `admin.vm.property.List` | vm | - | - | `<property>\n` |
|
| `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.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.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.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.Help` | vm | property | - | `help` |
|
||||||
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
|
| `admin.vm.property.HelpRst` | vm | property | - | `help.rst` |
|
||||||
| `admin.vm.property.Reset` | vm | property | - | - |
|
| `admin.vm.property.Reset` | vm | property | - | - |
|
||||||
| `admin.vm.property.Set` | vm | property | value | - |
|
| `admin.vm.property.Set` | vm | property | value | - |
|
||||||
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
|
| `admin.vm.feature.List` | vm | - | - | `<feature>\n` |
|
||||||
| `admin.vm.feature.Get` | vm | feature | - | value |
|
| `admin.vm.feature.Get` | vm | feature | - | value |
|
||||||
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
|
| `admin.vm.feature.CheckWithTemplate` | vm | feature | - | value |
|
||||||
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
|
| `admin.vm.feature.CheckWithNetvm` | vm | feature | - | value |
|
||||||
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
|
| `admin.vm.feature.CheckWithAdminVM` | vm | feature | - | value |
|
||||||
| `admin.vm.feature.CheckWithTemplateAndAdminVM` | vm | feature | - | value |
|
| `admin.vm.feature.CheckWithTemplateAndAdminVM`| vm | feature | - | value |
|
||||||
| `admin.vm.feature.Remove` | vm | feature | - | - |
|
| `admin.vm.feature.Remove` | vm | feature | - | - |
|
||||||
| `admin.vm.feature.Set` | vm | feature | value | - |
|
| `admin.vm.feature.Set` | vm | feature | value | - |
|
||||||
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
|
| `admin.vm.tag.List` | vm | - | - | `<tag>\n` |
|
||||||
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
|
| `admin.vm.tag.Get` | vm | tag | - | `0` or `1` | retcode? |
|
||||||
| `admin.vm.tag.Remove` | vm | tag | - | - |
|
| `admin.vm.tag.Remove` | vm | tag | - | - |
|
||||||
| `admin.vm.tag.Set` | 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.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.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.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.deviceclass.List` | `dom0` | - | - | `<class>\n` |
|
||||||
| `admin.vm.device.<class>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`.
|
| `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>.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>.Detach` | vm | device | - | - | `device` is in form `<backend-name>+<device-ident>`
|
||||||
| `admin.vm.device.<class>.Unassign` | 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>.Set.required` | 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.deviceclass.List` | `dom0` | - | - | `<deviceclass>\n` |
|
| `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.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.pool.List` | `dom0` | - | - | `<pool>\n` |
|
||||||
| `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.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
|
||||||
| `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.Info` | `dom0` | pool | - | `<property>=<value>\n` |
|
||||||
| `admin.pool.List` | `dom0` | - | - | `<pool>\n` |
|
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
|
||||||
| `admin.pool.ListDrivers` | `dom0` | - | - | `<pool-driver> <property> ...\n` | Properties allowed in `admin.pool.Add`
|
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
|
||||||
| `admin.pool.Info` | `dom0` | pool | - | `<property>=<value>\n` |
|
| `admin.pool.Remove` | `dom0` | pool | - | - |
|
||||||
| `admin.pool.Add` | `dom0` | driver | `<property>=<value>\n` | - |
|
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
|
||||||
| `admin.pool.Set.revisions_to_keep` | `dom0` | pool | `<value>` | - |
|
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
|
||||||
| `admin.pool.Remove` | `dom0` | pool | - | - |
|
| `admin.pool.volume.Set.revisions_to_keep`| `dom0` | pool | `<vid> <value>` | - |
|
||||||
| `admin.pool.volume.List` | `dom0` | pool | - | volume id |
|
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
|
||||||
| `admin.pool.volume.Info` | `dom0` | pool | vid | `<property>=<value>\n` |
|
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
|
||||||
| `admin.pool.volume.Set.revisions_to_keep` | `dom0` | pool | `<vid> <value>` | - |
|
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
|
||||||
| `admin.pool.volume.ListSnapshots` | `dom0` | pool | vid | `<snapshot>\n` |
|
| `admin.pool.volume.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
|
||||||
| `admin.pool.volume.Snapshot` | `dom0` | pool | vid | snapshot |
|
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
|
||||||
| `admin.pool.volume.Revert` | `dom0` | pool | `<vid> <snapshot>` | - |
|
| `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.Resize` | `dom0` | pool | `<vid> <size_in_bytes>` | - |
|
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
|
||||||
| `admin.pool.volume.Import` | `dom0` | pool | `<vid>\n<raw volume data>` | - |
|
| `admin.vm.volume.List` | vm | - | - | `<volume>\n` | `<volume>` is per-VM volume name (`root`, `private`, etc), `<vid>` is pool-unique volume id
|
||||||
| `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.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
|
||||||
| `admin.pool.volume.CloneTo` | `dom0` | pool | `<vid> <token>` | - | copy volume pointed by a token to volume `vid` in `pool` |
|
| `admin.vm.volume.Set.revisions_to_keep`| vm | volume | value | - |
|
||||||
| `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.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
|
||||||
| `admin.vm.volume.Info` | vm | volume | - | `<property>=<value>\n` |
|
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
|
||||||
| `admin.vm.volume.Set.revisions_to_keep` | vm | volume | value | - |
|
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | id. |
|
||||||
| `admin.vm.volume.ListSnapshots` | vm | volume | - | snapshot | duplicate of `admin.pool.volume.`, but with other call params |
|
| `admin.vm.volume.Resize` | vm | volume | size_in_bytes | - | id. |
|
||||||
| `admin.vm.volume.Snapshot` | vm | volume | - | snapshot | id. |
|
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
|
||||||
| `admin.vm.volume.Revert` | vm | volume | snapshot | - | 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.Resize` | vm | volume | size_in_bytes | - | id. |
|
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
|
||||||
| `admin.vm.volume.Import` | vm | volume | raw volume data | - | id. |
|
| `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.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.CloneTo` | vm | volume | token, obtained with `admin.vm.volume.CloneFrom` | - | copy volume pointed by a token to `volume` of `vm` |
|
||||||
| `admin.vm.volume.Clear` | vm | volume | - | - | clear contents of volume |
|
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
|
||||||
| `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.Start` | vm | - | - | - |
|
||||||
| `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.Shutdown` | vm | - | - | - |
|
||||||
| `admin.vm.CurrentState` | vm | - | - | `<state-property>=<value>\n` | state properties: `power_state`, `mem`, `mem_static_max`, `cputime`
|
| `admin.vm.Pause` | vm | - | - | - |
|
||||||
| `admin.vm.Start` | vm | - | - | - |
|
| `admin.vm.Unpause` | vm | - | - | - |
|
||||||
| `admin.vm.Shutdown` | vm | - | - | - |
|
| `admin.vm.Kill` | vm | - | - | - |
|
||||||
| `admin.vm.Pause` | 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.vm.Unpause` | vm | - | - | - |
|
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
|
||||||
| `admin.vm.Kill` | vm | - | - | - |
|
| `admin.backup.Cancel` | `dom0` | config id | - | - | cancel running backup operation
|
||||||
| `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.Events` | `dom0|vm` | - | - | events |
|
||||||
| `admin.backup.Info` | `dom0` | config id | - | backup info | info what would be included in the backup
|
| `admin.vm.Stats` | `dom0|vm` | - | - | `vm-stats` events, see below | emit VM statistics (CPU, memory usage) in form of events
|
||||||
| `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:
|
Volume properties:
|
||||||
|
|
||||||
@ -305,58 +302,6 @@ destination_vm: sys-net
|
|||||||
destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /directory/for/backups
|
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
|
## General notes
|
||||||
|
|
||||||
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
|
- there is no provision for `qvm-run`, but there already exists `qubes.VMShell` call
|
||||||
|
|||||||
@ -62,12 +62,9 @@ Such configuration can be expressed by enabling `ipv6` feature only on some subs
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
**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
|
### Limitations
|
||||||
|
|
||||||
Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
|
Currently only IPv4 DNS servers are configured, regardless of `ipv6` feature state. It is done this way to avoid reconfiguring all connected qubes whenever IPv6 DNS becomes available or not. Configuring qubes to always use IPv6 DNS and only fallback to IPv4 may result in relatively long timeouts and poor usability.
|
||||||
But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.
|
But note that DNS using IPv4 does not prevent to return IPv6 addresses. In practice this is only a problem for IPv6-only networks.
|
||||||
|
|
||||||
|
|||||||
@ -678,7 +678,7 @@ Any rpm-based, 64-bit environment, the preferred OS being Fedora.
|
|||||||
|
|
||||||
### How do I build Qubes from sources?
|
### How do I build Qubes from sources?
|
||||||
|
|
||||||
See [these instructions](/doc/qubes-builder-v2/).
|
See [these instructions](/doc/qubes-builder/).
|
||||||
|
|
||||||
### How do I submit a patch?
|
### How do I submit a patch?
|
||||||
|
|
||||||
|
|||||||
@ -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 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://archive.org/details/QubesOSTheOperatingSystemThatCanProtectYouEvenIfYouGetHackedTalkByMicahLee) at the Circle of HOPE 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://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.
|
||||||
|
|
||||||
<div class="video more-bottom">
|
<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>
|
<iframe class="responsive" referrerpolicy="no-referrer" scrolling="no" allowfullscreen src="https://livestream.com/accounts/9197973/events/8286152/videos/178431606/player?autoPlay=false"></iframe>
|
||||||
|
|||||||
@ -18,7 +18,7 @@ That way, they can be used to customize a single VM instead of all VMs based on
|
|||||||
The scripts here all run as root.
|
The scripts here all run as root.
|
||||||
|
|
||||||
- `/rw/config/rc.local` - script runs at VM startup.
|
- `/rw/config/rc.local` - script runs at VM startup.
|
||||||
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc. The script need to have the executable permission set to be executed.
|
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
|
||||||
Example usage:
|
Example usage:
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
@ -32,8 +32,6 @@ The scripts here all run as root.
|
|||||||
echo '127.0.0.1 example.com' >> /etc/hosts
|
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.
|
- `/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.
|
- 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.
|
||||||
|
|||||||
@ -17,7 +17,7 @@ How to test upcoming Qubes OS releases:
|
|||||||
|
|
||||||
- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
|
- Test the latest release candidate (RC) on the [downloads](/downloads/) page, if one is currently available. (Or try an older RC from our [FTP server](https://ftp.qubes-os.org/iso/).)
|
||||||
- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
|
- Try the [signed weekly builds](https://qubes.notset.fr/iso/). ([Learn more](https://forum.qubes-os.org/t/16929) and [track their status](https://github.com/fepitre/updates-status-iso/issues).)
|
||||||
- Use [qubes-builder](/doc/qubes-builder-v2/) to build the latest release yourself.
|
- Use [qubes-builder](/doc/qubes-builder/) to build the latest release yourself.
|
||||||
- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
|
- (No support) Experiment with developer alpha ISOs found from time to time at [Qubes OpenQA](https://openqa.qubes-os.org/).
|
||||||
|
|
||||||
Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
|
Please make sure to [report any bugs you encounter](/doc/issue-tracking/).
|
||||||
|
|||||||
@ -25,19 +25,19 @@ Qubes-certified computers are certified for a [major release](/doc/version-schem
|
|||||||
|
|
||||||
The current Qubes-certified models are listed below in reverse chronological order of certification.
|
The current Qubes-certified models are listed below in reverse chronological order of certification.
|
||||||
|
|
||||||
| Brand | Model | Certification details |
|
| Brand | Model | Certification details |
|
||||||
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||||
| [NovaCustom](https://novacustom.com/) | [V54 Series](https://novacustom.com/product/v54-series/) | [Certification details](/doc/certified-hardware/novacustom-v54-series/) |
|
| [NovaCustom](https://novacustom.com/) | [V54 Series](https://novacustom.com/product/v54-series/) | [Certification details](/doc/certified-hardware/novacustom-v54-series/) |
|
||||||
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) | [Certification details](/doc/certified-hardware/nitropad-v56/) |
|
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad V56](https://shop.nitrokey.com/shop/nitropad-v56-684) | [Certification details](/doc/certified-hardware/nitropad-v56/) |
|
||||||
| [NovaCustom](https://novacustom.com/) | [V56 Series](https://novacustom.com/product/v56-series/) | [Certification details](/doc/certified-hardware/novacustom-v56-series/) |
|
| [NovaCustom](https://novacustom.com/) | [V56 Series](https://novacustom.com/product/v56-series/) | [Certification details](/doc/certified-hardware/novacustom-v56-series/) |
|
||||||
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) | [Certification details](/doc/certified-hardware/nitropc-pro-2/) |
|
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523) | [Certification details](/doc/certified-hardware/nitropc-pro-2/) |
|
||||||
| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook) | [Certification details](/doc/certified-hardware/starlabs-starbook/) |
|
| [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook) | [Certification details](/doc/certified-hardware/starlabs-starbook/) |
|
||||||
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) | [Certification details](/doc/certified-hardware/nitropc-pro/) |
|
| [Nitrokey](https://www.nitrokey.com/) | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) | [Certification details](/doc/certified-hardware/nitropc-pro/) |
|
||||||
| [NovaCustom](https://novacustom.com/) | [NV41 Series](https://novacustom.com/product/nv41-series/) | [Certification details](/doc/certified-hardware/novacustom-nv41-series/) |
|
| [NovaCustom](https://novacustom.com/) | [NV41 Series](https://novacustom.com/product/nv41-series/) | [Certification details](/doc/certified-hardware/novacustom-nv41-series/) |
|
||||||
| [3mdeb](https://3mdeb.com/) | [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
|
| [3mdeb](https://3mdeb.com/) | [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) | [Certification details](/doc/certified-hardware/dasharo-fidelisguard-z690/) |
|
||||||
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) | [Certification details](/doc/certified-hardware/nitropad-t430/) |
|
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad T430](https://shop.nitrokey.com/shop/product/nitropad-t430-119) | [Certification details](/doc/certified-hardware/nitropad-t430/) |
|
||||||
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) | [Certification details](/doc/certified-hardware/nitropad-x230/) |
|
| [Nitrokey](https://www.nitrokey.com/) | [NitroPad X230](https://shop.nitrokey.com/shop/product/nitropad-x230-67) | [Certification details](/doc/certified-hardware/nitropad-x230/) |
|
||||||
| [Insurgo](https://insurgo.ca/) | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
|
| [Insurgo](https://insurgo.ca/) | [PrivacyBeast X230](https://insurgo.ca/produit/qubesos-certified-privacybeast_x230-reasonably-secured-laptop/) | [Certification details](/doc/certified-hardware/insurgo-privacybeast-x230/) |
|
||||||
|
|
||||||
## Become hardware certified
|
## Become hardware certified
|
||||||
|
|
||||||
|
|||||||
@ -6,11 +6,11 @@ title: Dasharo FidelisGuard Z690
|
|||||||
image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
|
image: /attachment/posts/dasharo-fidelisguard-z690_2.jpg
|
||||||
---
|
---
|
||||||
|
|
||||||
The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
|
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
|
||||||
|
|
||||||
[](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
[](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
||||||
|
|
||||||
The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
|
The [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) is a full desktop PC build that brings the [Dasharo](https://dasharo.com/) open-source firmware distribution to the MSI PRO Z690-A DDR4 motherboard with Qubes OS preinstalled. The full configuration includes:
|
||||||
|
|
||||||
| Part | Model Name |
|
| Part | Model Name |
|
||||||
|------------- | -------------------------------------------------------------- |
|
|------------- | -------------------------------------------------------------- |
|
||||||
@ -21,7 +21,7 @@ The [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https
|
|||||||
| Storage | SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe |
|
| Storage | SSD Intel 670p 512 GB M.2 2280 PCI-E x4 Gen3 NVMe |
|
||||||
| Enclosure | SilentiumPC Armis AR1 |
|
| Enclosure | SilentiumPC Armis AR1 |
|
||||||
|
|
||||||
[](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
[](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
||||||
|
|
||||||
This computer comes with a "Dasharo Supporters Entrance Subscription," which includes the following:
|
This computer comes with a "Dasharo Supporters Entrance Subscription," which includes the following:
|
||||||
|
|
||||||
@ -31,8 +31,8 @@ This computer comes with a "Dasharo Supporters Entrance Subscription," which inc
|
|||||||
- Dasharo Premier Support through an invite-only Matrix channel
|
- Dasharo Premier Support through an invite-only Matrix channel
|
||||||
- Influence on the Dasharo feature roadmap
|
- Influence on the Dasharo feature roadmap
|
||||||
|
|
||||||
[](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
[](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
||||||
|
|
||||||
For further details, please see the [Dasharo FidelisGuard Z690](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page.
|
For further details, please see the [Dasharo FidelisGuard Z690](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/) product page.
|
||||||
|
|
||||||
[](https://web.archive.org/web/20240917145232/https://shop.3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
[](https://3mdeb.com/shop/open-source-hardware/dasharo-fidelisguard-z690-qubes-os-certified/)
|
||||||
|
|||||||
@ -114,7 +114,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
|
|||||||
other security updates directly to users. By contrast, on AMD client (as
|
other security updates directly to users. By contrast, on AMD client (as
|
||||||
opposed to server) platforms, microcode updates are typically shipped only as
|
opposed to server) platforms, microcode updates are typically shipped only as
|
||||||
part of system firmware and generally cannot be loaded from the operating
|
part of system firmware and generally cannot be loaded from the operating
|
||||||
system [^1]. This means that AMD users typically must wait for:
|
system. This means that AMD users typically must wait for:
|
||||||
|
|
||||||
1. AMD to distribute microcode updates to original equipment manufacturers
|
1. AMD to distribute microcode updates to original equipment manufacturers
|
||||||
(OEMs), original design manufacturers (ODMs), and motherboard manufacturers
|
(OEMs), original design manufacturers (ODMs), and motherboard manufacturers
|
||||||
@ -123,7 +123,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
|
|||||||
the user's system.
|
the user's system.
|
||||||
|
|
||||||
Historically, AMD has often been slow to complete step (1), at least for its
|
Historically, AMD has often been slow to complete step (1), at least for its
|
||||||
client (as opposed to server) platforms [^2]. In some cases, AMD has made fixes
|
client (as opposed to server) platforms. In some cases, AMD has made fixes
|
||||||
available for its server platforms very shortly after a security embargo was
|
available for its server platforms very shortly after a security embargo was
|
||||||
lifted, but it did not make fixes available for client platforms facing the
|
lifted, but it did not make fixes available for client platforms facing the
|
||||||
same vulnerability until weeks or months later. (A "security embargo" is the
|
same vulnerability until weeks or months later. (A "security embargo" is the
|
||||||
@ -163,17 +163,3 @@ We recommend consulting these resources when selecting hardware for Qubes OS:
|
|||||||
|
|
||||||
- You can check whether an Intel processor has VT-x and VT-d on
|
- You can check whether an Intel processor has VT-x and VT-d on
|
||||||
[ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
|
[ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
|
||||||
|
|
||||||
[^1]: There is an `amd-ucode-firmware` package, but it only contains
|
|
||||||
microcode for servers and outdated microcode for Chromebooks. Also,
|
|
||||||
the [AMD security website](https://www.amd.com/en/resources/product-security.html)
|
|
||||||
only lists microcode as a mitigation for data center CPUs.
|
|
||||||
|
|
||||||
[^2]: As shown on [the AMD page for Speculative Return Stack Overflow](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7005.html),
|
|
||||||
updated AGESA™ firmware for AMD Ryzen™ Threadripper™ 5000WX Processors
|
|
||||||
was not available until 2024-01-11, even though the vulnerability became
|
|
||||||
public on 2023-08-08. AMD did not provide updated firmware for other client
|
|
||||||
processors until a date between 2023-08-22 to 2023-08-25.
|
|
||||||
|
|
||||||
For Zenbleed, firmware was not available until 2024 for most client parts,
|
|
||||||
even though server parts got microcode on 2023-06-06.
|
|
||||||
|
|||||||
@ -12,17 +12,13 @@ title: Emergency backup recovery (v4)
|
|||||||
This page describes how to perform an emergency restore of a backup created on
|
This page describes how to perform an emergency restore of a backup created on
|
||||||
Qubes R4.X (which uses backup format version 4).
|
Qubes R4.X (which uses backup format version 4).
|
||||||
|
|
||||||
The Qubes backup system is designed with emergency disaster recovery in mind. No
|
The Qubes backup system has been designed with emergency disaster recovery in
|
||||||
special Qubes-specific tools are required to access data backed up by Qubes. In
|
mind. No special Qubes-specific tools are required to access data backed up by
|
||||||
the event a Qubes system is unavailable, you can access your data on any
|
Qubes. In the event a Qubes system is unavailable, you can access your data on
|
||||||
GNU/Linux system by following the instructions on this page.
|
any GNU/Linux system with the following procedure.
|
||||||
|
|
||||||
**Important:** You may wish to store a copy of these instructions with your
|
Required `scrypt` Utility
|
||||||
Qubes backups. All Qubes documentation, including this page, is available in
|
-------------------------
|
||||||
plain text format in the [qubes-doc](https://github.com/QubesOS/qubes-doc) Git
|
|
||||||
repository.
|
|
||||||
|
|
||||||
## Required `scrypt` utility
|
|
||||||
|
|
||||||
In Qubes 4.X, backups are encrypted and integrity-protected with
|
In Qubes 4.X, backups are encrypted and integrity-protected with
|
||||||
[scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
|
[scrypt](https://www.tarsnap.com/scrypt.html). You will need a copy of this
|
||||||
@ -38,8 +34,8 @@ easier scripting, which means you'll need to enter the passphrase for each file
|
|||||||
separately, instead of using `echo ... | scrypt`.
|
separately, instead of using `echo ... | scrypt`.
|
||||||
|
|
||||||
Here are instructions for obtaining a compiled `scrypt` binary. This example
|
Here are instructions for obtaining a compiled `scrypt` binary. This example
|
||||||
uses an RPM-based system (Fedora), but the same general procedure should work on
|
uses an RPM-based system (Fedora), but the same general procedure should work
|
||||||
any GNU/Linux system.
|
on any GNU/Linux system.
|
||||||
|
|
||||||
1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
|
1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
|
||||||
Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
|
Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
|
||||||
@ -50,7 +46,7 @@ any GNU/Linux system.
|
|||||||
|
|
||||||
[user@restore ~]$ dnf download scrypt
|
[user@restore ~]$ dnf download scrypt
|
||||||
|
|
||||||
Or, if that doesn't work:
|
or, if that doesn't work:
|
||||||
|
|
||||||
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
|
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
|
||||||
|
|
||||||
@ -66,35 +62,60 @@ any GNU/Linux system.
|
|||||||
|
|
||||||
[user@restore ~]$ sudo dnf install rpmdevtools
|
[user@restore ~]$ sudo dnf install rpmdevtools
|
||||||
|
|
||||||
5. Extract the `scrypt` binary from the RPM and make it conveniently
|
5. Extract the `scrypt` binary from the RPM.
|
||||||
available.
|
|
||||||
|
|
||||||
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
|
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
|
||||||
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
|
|
||||||
|
|
||||||
## Emergency recovery instructions
|
6. (Optional) Create an alias for the new binary.
|
||||||
|
|
||||||
|
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"
|
||||||
|
|
||||||
|
Emergency Recovery Instructions
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
**Note:** In the following example, the backup file is both *encrypted* and
|
**Note:** In the following example, the backup file is both *encrypted* and
|
||||||
*compressed*.
|
*compressed*.
|
||||||
|
|
||||||
1. Untar the backup metadata from the main backup file.
|
1. Untar the main backup file.
|
||||||
|
|
||||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
|
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
|
||||||
backup-header backup-header.hmac qubes.xml.000.enc
|
|
||||||
backup-header
|
backup-header
|
||||||
backup-header.hmac
|
backup-header.hmac
|
||||||
qubes.xml.000.enc
|
qubes.xml.000.enc
|
||||||
|
vm1/private.img.000.enc
|
||||||
|
vm1/private.img.001.enc
|
||||||
|
vm1/private.img.002.enc
|
||||||
|
vm1/icon.png.000.enc
|
||||||
|
vm1/firewall.xml.000.enc
|
||||||
|
vm1/whitelisted-appmenus.list.000.enc
|
||||||
|
dom0-home/dom0user.000.enc
|
||||||
|
|
||||||
|
**To extract only specific VMs:** Each VM in the backup file has its path
|
||||||
|
listed in `qubes.xml.000.enc`. Decrypt it. (In this example, the password is
|
||||||
|
`password`.)
|
||||||
|
|
||||||
|
[user@restore ~]$ cat backup-header | grep backup-id
|
||||||
|
backup-id=20190128T123456-1234
|
||||||
|
[user@restore ~]$ scrypt dec -P qubes.xml.000.enc qubes.xml.000
|
||||||
|
Please enter passphrase: 20190128T123456-1234!qubes.xml.000!password
|
||||||
|
[user@restore ~]$ tar -i -xvf qubes.xml.000
|
||||||
|
|
||||||
|
Now that you have the decrypted `qubes.xml.000` file, search for the
|
||||||
|
`backup-path` property inside of it. With the `backup-path`, extract only
|
||||||
|
the files necessary for your VM (`vmX`).
|
||||||
|
|
||||||
|
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456 \
|
||||||
|
backup-header backup-header.hmac vmX/
|
||||||
|
|
||||||
2. Set the backup passphrase environment variable. While this isn't strictly
|
2. Set the backup passphrase environment variable. While this isn't strictly
|
||||||
required, it will be handy later and will avoid saving the passphrase in the
|
required, it will be handy later and will avoid saving the passphrase in
|
||||||
shell's history.
|
the shell's history.
|
||||||
|
|
||||||
[user@restore ~]$ read -r backup_pass
|
[user@restore ~]$ read -r backup_pass
|
||||||
|
|
||||||
Type in your passphrase (it will be visible on screen!) and press Enter.
|
3. Verify the integrity of `backup-header`. For compatibility reasons,
|
||||||
|
`backup-header.hmac` is an encrypted *and integrity protected*
|
||||||
3. Verify the integrity of `backup-header` using `backup-header.hmac` (an
|
version of `backup-header`.
|
||||||
encrypted *and integrity protected* version of `backup-header`).
|
|
||||||
|
|
||||||
[user@restore ~]$ set +H
|
[user@restore ~]$ set +H
|
||||||
[user@restore ~]$ echo "backup-header!$backup_pass" |\
|
[user@restore ~]$ echo "backup-header!$backup_pass" |\
|
||||||
@ -102,34 +123,34 @@ any GNU/Linux system.
|
|||||||
diff -qs backup-header backup-header.verified
|
diff -qs backup-header backup-header.verified
|
||||||
Files backup-header and backup-header.verified are identical
|
Files backup-header and backup-header.verified are identical
|
||||||
|
|
||||||
**Note:** If this command fails, it may be that the backup was tampered with
|
**Note:** If this command fails, it may be that the backup was tampered
|
||||||
or is in a different format. In the latter case, look inside `backup-header`
|
with or is in a different format. In the latter case, look inside
|
||||||
at the `version` field. If it contains a value other than `version=4`, go to
|
`backup-header` at the `version` field. If it contains a value other than
|
||||||
the instructions for that format version:
|
`version=4`, go to the instructions for that format version:
|
||||||
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
|
- [Emergency Backup Recovery without Qubes (v2)](/doc/backup-emergency-restore-v2/)
|
||||||
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
|
- [Emergency Backup Recovery without Qubes (v3)](/doc/backup-emergency-restore-v3/)
|
||||||
|
|
||||||
4. Read `backup-header`.
|
4. Read `backup-header`:
|
||||||
|
|
||||||
[user@restore ~]$ cat backup-header
|
[user@restore ~]$ cat backup-header
|
||||||
version=4
|
version=4
|
||||||
encrypted=True
|
encrypted=True
|
||||||
compressed=True
|
compressed=True
|
||||||
compression-filter=gzip
|
compression-filter=gzip
|
||||||
hmac-algorithm=scrypt
|
backup_id=20161020T123455-1234
|
||||||
backup-id=20230405T123455-1234
|
|
||||||
|
|
||||||
5. Set `backup_id` to the value in the last line of `backup-header`. (Note that
|
5. Set `backup_id` to the value in the last line of `backup-header`:
|
||||||
there is a hyphen in `backup-id` in the file, whereas there is an underscore
|
|
||||||
in `backup_id` in the variable you're setting.)
|
|
||||||
|
|
||||||
[user@restore ~]$ backup_id=20230405T123455-1234
|
[user@restore ~]$ backup_id=20161020T123455-1234
|
||||||
|
|
||||||
6. Verify and decrypt, decompress, and extract the `qubes.xml` file.
|
6. Verify the integrity of your data, decrypt, decompress, and extract
|
||||||
|
`private.img`:
|
||||||
|
|
||||||
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
|
[user@restore ~]$ find vm1 -name 'private.img.*.enc' | sort -V | while read f_enc; do \
|
||||||
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
|
f_dec=${f_enc%.enc}; \
|
||||||
qubes.xml
|
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
|
||||||
|
done | gzip -d | tar -xv
|
||||||
|
vm1/private.img
|
||||||
|
|
||||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
If this pipeline fails, it is likely that the backup is corrupted or has
|
||||||
been tampered with.
|
been tampered with.
|
||||||
@ -137,66 +158,23 @@ any GNU/Linux system.
|
|||||||
**Note:** If your backup was compressed with a program other than `gzip`,
|
**Note:** If your backup was compressed with a program other than `gzip`,
|
||||||
you must substitute the correct compression program in the command above.
|
you must substitute the correct compression program in the command above.
|
||||||
This information is contained in `backup-header` (see step 4). For example,
|
This information is contained in `backup-header` (see step 4). For example,
|
||||||
if your backup is compressed with `bzip2`, use `bzip2 -d` instead of `gzip
|
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
|
||||||
-d` in the command above. You might need to install a package of the same
|
command above.
|
||||||
name (in this example, `bzip2`) through your distribution's package manager.
|
|
||||||
|
|
||||||
7. Search inside of the `qubes.xml` file for the `backup-path` of the qube
|
7. Mount `private.img` and access your data.
|
||||||
whose data you wish to restore. If you install the `xmlstarlet` package, the
|
|
||||||
following command will convert `qubes.xml` to a friendlier listing for this
|
|
||||||
purpose:
|
|
||||||
|
|
||||||
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
|
[user@restore vm1]$ sudo mkdir /mnt/img
|
||||||
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
|
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
|
||||||
-n qubes.xml
|
[user@restore vm1]$ cat /mnt/img/home/user/your_data.txt
|
||||||
|
This data has been successfully recovered!
|
||||||
|
|
||||||
anon-whonix
|
8. Success! If you wish to recover data from more than one VM in your backup,
|
||||||
debian-11
|
simply repeat steps 6 and 7 for each additional VM.
|
||||||
default-mgmt-dvm
|
|
||||||
disp2345
|
|
||||||
fedora-37
|
|
||||||
fedora-37-dvm
|
|
||||||
personal vm123/
|
|
||||||
sys-firewall
|
|
||||||
sys-net
|
|
||||||
sys-usb
|
|
||||||
sys-whonix
|
|
||||||
untrusted
|
|
||||||
vault vm321/
|
|
||||||
whonix-gw-16
|
|
||||||
whonix-ws-16
|
|
||||||
whonix-ws-16-dvm
|
|
||||||
work
|
|
||||||
|
|
||||||
The example output above shows that the backup file includes a qube named
|
**Note:** You may wish to store a copy of these instructions with your
|
||||||
`personal` and a qube named `vault`, with `backup-path` values of `vm123/`
|
Qubes backups in the event that you fail to recall the above procedure
|
||||||
and `vm321/` respectively. (Every other listed qube was not selected to be
|
while this web page is inaccessible. All Qubes documentation, including
|
||||||
included in the backup file.) Use the corresponding value to untar the
|
this page, is available in plain text format in the following Git
|
||||||
necessary data files of the qube:
|
repository:
|
||||||
|
|
||||||
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
|
https://github.com/QubesOS/qubes-doc.git
|
||||||
|
|
||||||
8. Verify and decrypt the backed up data, decompress it, and extract it.
|
|
||||||
|
|
||||||
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
|
|
||||||
f_dec=${f_enc%.enc}; \
|
|
||||||
echo "$backup_id!$f_dec!$backup_pass" | scrypt dec -P $f_enc || break; \
|
|
||||||
done | gzip -d | tar -xv
|
|
||||||
vm123/private.img
|
|
||||||
|
|
||||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
|
||||||
been tampered with.
|
|
||||||
|
|
||||||
Also see the note in step 6 about substituting a different compression
|
|
||||||
program for `gzip`.
|
|
||||||
|
|
||||||
9. Mount `private.img` and access your data.
|
|
||||||
|
|
||||||
[user@restore ~]$ sudo mkdir /mnt/img
|
|
||||||
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
|
|
||||||
[user@restore ~]$ ls /mnt/img/home/user/
|
|
||||||
example_data_file.txt
|
|
||||||
...
|
|
||||||
|
|
||||||
Success! If you wish to recover data from more than one qube in your backup,
|
|
||||||
simply repeat steps 7, 8, and 9 for each additional qube.
|
|
||||||
|
|||||||
@ -89,7 +89,7 @@ the other. Alice's setup looks like this:
|
|||||||
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
|
[bind-dirs](/doc/bind-dirs/) to make those changes persistent, but sometimes
|
||||||
she doesn't want to get bogged down doing with all that and figures it
|
she doesn't want to get bogged down doing with all that and figures it
|
||||||
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
|
wouldn't be worth it just for this one qube. She's secretly glad that Qubes
|
||||||
OS doesn't judge her for this and just gives her the freedom to do things however
|
OS doesn't judge her this and just gives her the freedom to do things however
|
||||||
she likes while keeping everything securely compartmentalized. At times like
|
she likes while keeping everything securely compartmentalized. At times like
|
||||||
these, she takes comfort in knowing that things can be messy and disorganized
|
these, she takes comfort in knowing that things can be messy and disorganized
|
||||||
*within* a qube while her overall digital life remains well-organized.
|
*within* a qube while her overall digital life remains well-organized.
|
||||||
|
|||||||
@ -17,7 +17,6 @@ Fully updating your Qubes OS system means updating:
|
|||||||
- [dom0](/doc/glossary/#dom0)
|
- [dom0](/doc/glossary/#dom0)
|
||||||
- [templates](/doc/glossary/#template)
|
- [templates](/doc/glossary/#template)
|
||||||
- [standalones](/doc/glossary/#standalone) (if you have any)
|
- [standalones](/doc/glossary/#standalone) (if you have any)
|
||||||
- [firmware](/doc/glossary/#firmware)
|
|
||||||
|
|
||||||
## Security updates
|
## Security updates
|
||||||
|
|
||||||
@ -66,19 +65,10 @@ If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal"
|
|||||||
|
|
||||||
<div class="alert alert-danger" role="alert">
|
<div class="alert alert-danger" role="alert">
|
||||||
<i class="fa fa-exclamation-triangle"></i>
|
<i class="fa fa-exclamation-triangle"></i>
|
||||||
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code> and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
|
<b>Warning:</b> Updating with direct commands such as <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
|
Advanced users may wish to perform updates via the command-line interface. To update templates and standalones non-interactively, use the command `qubes-vm-update`, and to update dom0, use `qubes-dom0-update`. If you want to perform an update with more advanced user-configurable options (e.g., custom pre- or post-update scripts, custom workarounds), see: [update.qubes-dom0](/doc/salt/#updatequbes-dom0) and [update.qubes-vm](/doc/salt/#updatequbes-vm).
|
||||||
|
|
||||||
- If you are using Salt, one can use the following two Salt states.
|
|
||||||
|
|
||||||
- [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
|
|
||||||
- [update.qubes-vm](/doc/salt/#updatequbes-vm)
|
|
||||||
|
|
||||||
- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
|
|
||||||
|
|
||||||
Using either of these methods has the same effect as updating via the Qubes Update tool.
|
|
||||||
|
|
||||||
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
|
Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
|
||||||
|
|
||||||
@ -93,61 +83,3 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
|
|||||||
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
|
Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
|
||||||
|
|
||||||
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
|
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
|
||||||
|
|
||||||
## Microcode Updates
|
|
||||||
|
|
||||||
x86\_64 CPUs contain special low-level software called **microcode**, which
|
|
||||||
is used to implement certain instructions and runs on various processors that
|
|
||||||
are outside of Qubes OS's control. Most microcode is in an on-CPU ROM, but
|
|
||||||
CPU vendors provide patches that modify small parts of this microcode. These
|
|
||||||
patches can be loaded from the BIOS or by the OS.
|
|
||||||
|
|
||||||
The fixes for some QSBs require a microcode update to work. Furthermore,
|
|
||||||
microcode updates will sometimes fix vulnerabilities "silently". This means
|
|
||||||
that the vulnerability impacts the security of Qubes OS, but the Qubes OS
|
|
||||||
Security Team is not informed that a vulnerability exists, so no QSB is ever
|
|
||||||
issued. Therefore, it is critical to update microcode.
|
|
||||||
|
|
||||||
Intel provides microcode updates for all of their CPUs in a public Git
|
|
||||||
repository, and allows OS vendors (such as Qubes OS) to distribute the updates
|
|
||||||
free of charge. AMD, however, only provides microcode for server CPUs.
|
|
||||||
AMD client CPUs can only receive microcode updates via a system firmware
|
|
||||||
update. Worse, there is often a significant delay between when a vulnerability
|
|
||||||
becomes public and when firmware that includes updated microcode is available
|
|
||||||
to Qubes OS users. This is why Qubes OS recommends Intel CPUs instead of
|
|
||||||
AMD CPUs.
|
|
||||||
|
|
||||||
## Firmware updates
|
|
||||||
|
|
||||||
Modern computers have many processors other than those that run Qubes OS.
|
|
||||||
Furthermore, the main processor cores also run firmware, which is used to
|
|
||||||
boot the system and often provides some services at runtime. Both kinds
|
|
||||||
of firmware can have bugs and vulnerabilities, so it is critical to keep
|
|
||||||
them updated.
|
|
||||||
|
|
||||||
Some firmware is loaded by the OS at runtime.
|
|
||||||
Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
|
|
||||||
Other devices have persistent firmware that must be updated manually.
|
|
||||||
|
|
||||||
Qubes OS supports updating system firmware in three different ways.
|
|
||||||
Which one to use depends on the device whose firmware is being updated.
|
|
||||||
|
|
||||||
- If a device is attached to a domU, it should be updated using **fwupd**.
|
|
||||||
fwupd is included in both Debian and Fedora repositories.
|
|
||||||
It requires Internet access to use, but you can use the updates proxy if you
|
|
||||||
need to update firmware from an offline VM. You can use either the
|
|
||||||
command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
|
|
||||||
|
|
||||||
- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
|
|
||||||
This tool uses fwupd internally, but it fetches firmware and metadata over
|
|
||||||
qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
|
|
||||||
Unfortunately, their is no graphical interface for this tool yet.
|
|
||||||
|
|
||||||
- System76 systems use a special update tool which is simpler than fwupd.
|
|
||||||
Support for this tool is currently in progress. Once it is finished,
|
|
||||||
users will be able to use the **system76-firmware-cli** command-line
|
|
||||||
tool to update the firmware.
|
|
||||||
|
|
||||||
Firmware updates are important on all systems, but they are especially
|
|
||||||
important on AMD client systems. These doesn't support loading microcode from
|
|
||||||
the OS, so firmware updates are the **only** way to obtain microcode updates.
|
|
||||||
|
|||||||
@ -88,13 +88,6 @@ domUs lack direct hardware access.
|
|||||||
* Sometimes the term [VM](#vm) is used as a synonym for domU. This is
|
* Sometimes the term [VM](#vm) is used as a synonym for domU. This is
|
||||||
technically inaccurate, as [dom0](#dom0) is also a VM in Xen.
|
technically inaccurate, as [dom0](#dom0) is also a VM in Xen.
|
||||||
|
|
||||||
## firmware
|
|
||||||
|
|
||||||
Software that runs outside the control of the operating system.
|
|
||||||
Some firmware executes on the same CPU cores as Qubes OS does, but
|
|
||||||
all computers have many additional processors that the operating system
|
|
||||||
does not run on, and these computers also run firmware.
|
|
||||||
|
|
||||||
## HVM
|
## HVM
|
||||||
|
|
||||||
Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted,
|
Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted,
|
||||||
|
|||||||
@ -269,8 +269,7 @@ As an example we can take the use case of qube QubeDest running a web server lis
|
|||||||
|
|
||||||
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
|
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
|
||||||
|
|
||||||
You can get this information using various methods.
|
You can get this information using various methods, but only the first one can be used for `sys-net` outside world IP:
|
||||||
Only the first method can be used for `sys-net` to find the external IP:
|
|
||||||
|
|
||||||
- by running this command in each qube: `ip -4 -br a | grep UP`
|
- by running this command in each qube: `ip -4 -br a | grep UP`
|
||||||
- using `qvm-ls -n`
|
- using `qvm-ls -n`
|
||||||
@ -285,12 +284,7 @@ Note the IP addresses you will need, they will be required in the next steps.
|
|||||||
|
|
||||||
For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z.
|
For the following example, we assume that the physical interface ens6 in sys-net is on the local network 192.168.x.y with the IP 192.168.x.n, and that the IP address of sys-firewall is 10.137.1.z.
|
||||||
|
|
||||||
When writing rules in sys-net, you can use `iif` or `iifname`.
|
In the sys-net VM's Terminal, the first step is to define an ntables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
|
||||||
`iif` is faster, but can change where interfaces are dynamically created and destroyed, eg. ppp0.
|
|
||||||
In that case use `iifname`, like this `iifname ens6`.
|
|
||||||
`iifname` can also match wildcards - `iifname "eth*"`
|
|
||||||
|
|
||||||
In the sys-net VM's Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
||||||
@ -298,24 +292,25 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
|
|||||||
|
|
||||||
> Note: the name `custom-dnat-qubeDST` is arbitrary
|
> Note: the name `custom-dnat-qubeDST` is arbitrary
|
||||||
|
|
||||||
> Note: while we use a DNAT chain for a single qube, it's possible to have a single DNAT chain for multiple qubes
|
> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes
|
||||||
|
|
||||||
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
|
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
|
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
|
||||||
```
|
```
|
||||||
|
|
||||||
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
|
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
|
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
|
||||||
```
|
```
|
||||||
|
|
||||||
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
|
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
|
||||||
> If you want to expose the service on multiple interfaces, repeat steps 2 and 3 above, for each interface. Alternatively, you can leave out the interface completely.
|
|
||||||
|
|
||||||
Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
|
> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely.
|
||||||
|
|
||||||
|
Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`:
|
||||||
|
|
||||||
```
|
```
|
||||||
nft list table ip qubes
|
nft list table ip qubes
|
||||||
@ -325,12 +320,12 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
|
|||||||
|
|
||||||
```
|
```
|
||||||
chain custom-forward {
|
chain custom-forward {
|
||||||
iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
|
iif "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
|
||||||
}
|
}
|
||||||
|
|
||||||
chain custom-dnat-qubeDEST {
|
chain custom-dnat-qubeDEST {
|
||||||
type nat hook prerouting priority filter + 1; policy accept;
|
type nat hook prerouting priority filter + 1; policy accept;
|
||||||
iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
|
iif "ens6" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -356,20 +351,18 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-net`:
|
|||||||
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
||||||
then
|
then
|
||||||
# create the dnat rule
|
# create the dnat rule
|
||||||
nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
|
nft add rule qubes custom-dnat-qubeDEST iif == "ens6" saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
|
||||||
|
|
||||||
# allow forwarded traffic
|
# allow forwarded traffic
|
||||||
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
|
nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
|
||||||
fi
|
fi
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
**3. Route packets from the FirewallVM to the VM**
|
**3. Route packets from the FirewallVM to the VM**
|
||||||
|
|
||||||
For the following example, we use the fact that the interface of sys-firewall facing sys-net, is eth0.
|
For the following example, we use the fact that the physical interface of sys-firewall, facing sys-net, is eth0. Furthermore, we assume that the target VM running the web server has the IP address 10.137.0.xx and that the IP address of sys-firewall is 10.137.1.z.
|
||||||
This is allocated to iifgroup 1.
|
|
||||||
Furthermore, we assume that the IP address of sys-firewall is 10.137.1.z, and the target VM running the web server has the IP address 10.137.0.xx.
|
|
||||||
|
|
||||||
In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
|
In the sys-firewall VM's Terminal, add a DNAT chain that will contain routing rules:
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
||||||
@ -378,13 +371,13 @@ nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority fi
|
|||||||
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
|
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
|
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
|
||||||
```
|
```
|
||||||
|
|
||||||
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
|
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
|
||||||
|
|
||||||
```
|
```
|
||||||
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
|
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
|
||||||
```
|
```
|
||||||
|
|
||||||
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
|
> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules
|
||||||
@ -405,10 +398,10 @@ Content of `/rw/config/qubes-firewall-user-script` in `sys-firewall`:
|
|||||||
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
|
||||||
then
|
then
|
||||||
# create the dnat rule
|
# create the dnat rule
|
||||||
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
|
nft add rule qubes custom-dnat-qubeDEST iif == "eth0" tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
|
||||||
|
|
||||||
# allow forwarded traffic
|
# allow forwarded traffic
|
||||||
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
|
nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
|
||||||
fi
|
fi
|
||||||
~~~
|
~~~
|
||||||
|
|
||||||
|
|||||||
@ -37,123 +37,359 @@ Unfortunately this problem of signing reliability is not solvable by Split GPG.)
|
|||||||
With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
|
With Qubes Split GPG this problem is drastically minimized, because each time the key is to be used the user is asked for consent (with a definable time out, 5 minutes by default), plus is always notified each time the key is used via a tray notification from the domain where GPG backend is running.
|
||||||
This way it would be easy to spot unexpected requests to decrypt documents.
|
This way it would be easy to spot unexpected requests to decrypt documents.
|
||||||
|
|
||||||
## Configuration
|
[](/attachment/doc/r2-split-gpg-1.png)
|
||||||
|
[](/attachment/doc/r2-split-gpg-3.png)
|
||||||
|
|
||||||
Create/Edit `/etc/qubes/policy.d/30-user-gpg2.policy` in dom0, and add a line like this:
|
## Configuring Split GPG
|
||||||
|
|
||||||
|
In dom0, make sure the `qubes-gpg-split-dom0` package is installed.
|
||||||
|
|
||||||
```
|
```
|
||||||
qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
|
[user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0
|
||||||
```
|
```
|
||||||
|
|
||||||
Import/Generate your secret keys in the server domain.
|
Make sure you have the `qubes-gpg-split` package installed in the template you will use for the GPG domain.
|
||||||
For example:
|
|
||||||
|
For Debian or Whonix:
|
||||||
|
|
||||||
```
|
```
|
||||||
gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
|
[user@debian-10 ~]$ sudo apt install qubes-gpg-split
|
||||||
gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
|
|
||||||
```
|
|
||||||
or
|
|
||||||
|
|
||||||
```
|
|
||||||
gpg-server-vm$ gpg --gen-key
|
|
||||||
```
|
```
|
||||||
|
|
||||||
In dom0 enable the `split-gpg2-client` service in the client domain, for example via the command-line:
|
For Fedora:
|
||||||
|
|
||||||
```shell
|
|
||||||
dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME> split-gpg2-client on
|
|
||||||
```
|
|
||||||
|
|
||||||
To verify if this was done correctly:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
|
|
||||||
```
|
|
||||||
|
|
||||||
Output should be:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
split-gpg2-client on
|
|
||||||
```
|
|
||||||
|
|
||||||
Restart the client domain.
|
|
||||||
|
|
||||||
Export the **public** part of your keys and import them in the client domain.
|
|
||||||
Also import/set proper "ownertrust" values.
|
|
||||||
For example:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
gpg-server-vm$ gpg --export > public-keys-export
|
[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
|
||||||
gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
|
|
||||||
gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
|
|
||||||
|
|
||||||
gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
|
|
||||||
gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This should be enough to have it running:
|
### Setting up the GPG backend domain
|
||||||
|
|
||||||
|
First, create a dedicated app qube for storing your keys (we will be calling it the GPG backend domain).
|
||||||
|
It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose.
|
||||||
|
In later examples this app qube is named `work-gpg`, but of course it might have any other name.
|
||||||
|
|
||||||
|
Make sure that gpg is installed there.
|
||||||
|
At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later.
|
||||||
|
To check which private keys are in your GPG keyring, use:
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-gpg ~]$ gpg -K
|
||||||
|
/home/user/.gnupg/secring.gpg
|
||||||
|
-----------------------------
|
||||||
|
sec 4096R/3F48CB21 2012-11-15
|
||||||
|
uid Qubes OS Security Team <security@qubes-os.org>
|
||||||
|
ssb 4096R/30498E2A 2012-11-15
|
||||||
|
(...)
|
||||||
```
|
```
|
||||||
gpg-client-vm$ gpg -K
|
|
||||||
|
This is pretty much all that is required.
|
||||||
|
However, you might want to modify the default timeout: this tells the backend for how long the user's approval for key access should be valid.
|
||||||
|
(The default is 5 minutes.) You can change this via the `QUBES_GPG_AUTOACCEPT` environment variable.
|
||||||
|
You can override it e.g. in `~/.profile`:
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
|
||||||
|
```
|
||||||
|
|
||||||
|
Please note that previously, this parameter was set in ~/.bash_profile.
|
||||||
|
This will no longer work.
|
||||||
|
If you have the parameter set in ~/.bash_profile you *must* update your configuration.
|
||||||
|
|
||||||
|
Please be aware of the caveat regarding passphrase-protected keys in the [Current limitations](#current-limitations) section.
|
||||||
|
|
||||||
|
### Configuring the client apps to use Split GPG backend
|
||||||
|
|
||||||
|
Normally it should be enough to set the `QUBES_GPG_DOMAIN` to the GPG backend domain name and use `qubes-gpg-client` in place of `gpg`, e.g.:
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
|
||||||
|
[user@work-email ~]$ gpg -K
|
||||||
|
[user@work-email ~]$ qubes-gpg-client -K
|
||||||
|
/home/user/.gnupg/secring.gpg
|
||||||
|
-----------------------------
|
||||||
|
sec 4096R/3F48CB21 2012-11-15
|
||||||
|
uid Qubes OS Security Team <security@qubes-os.org>
|
||||||
|
ssb 4096R/30498E2A 2012-11-15
|
||||||
|
(...)
|
||||||
|
|
||||||
|
[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
|
||||||
|
(...)
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that running normal `gpg -K` in the demo above shows no private keys stored in this app qube.
|
||||||
|
|
||||||
|
A note on `gpg` and `gpg2`:
|
||||||
|
|
||||||
|
Throughout this guide, we refer to `gpg`, but note that Split GPG uses `gpg2` under the hood for compatibility with programs like Enigmail (which now supports only `gpg2`).
|
||||||
|
If you encounter trouble while trying to set up Split GPG, make sure you're using `gpg2` for your configuration and testing, since keyring data may differ between the two installations.
|
||||||
|
|
||||||
|
### Advanced Configuration
|
||||||
|
|
||||||
|
The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-email ~]$ sudo bash
|
||||||
|
[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
|
||||||
|
```
|
||||||
|
|
||||||
|
Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
|
||||||
|
|
||||||
|
```
|
||||||
|
work-email work-gpg allow
|
||||||
|
```
|
||||||
|
|
||||||
|
where `work-email` is the Thunderbird + Enigmail app qube and `work-gpg` contains your GPG keys.
|
||||||
|
|
||||||
|
You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
|
||||||
|
|
||||||
|
```
|
||||||
|
@anyvm @anyvm ask default_target=work-gpg
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up.
|
||||||
|
|
||||||
|
## Using Thunderbird
|
||||||
|
|
||||||
|
### Thunderbird 78 and higher
|
||||||
|
|
||||||
|
Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your `work-email` qube with Thunderbird rather than your offline `work-gpg` qube**.
|
||||||
|
|
||||||
|
In `work-email`, use the Thunderbird config editor (found at the bottom of preferences/options), and search for `mail.openpgp.allow_external_gnupg`. Switch the value to true. Still in config editor, search for `mail.openpgp.alternative_gpg_path`. Set its value to `/usr/bin/qubes-gpg-client-wrapper`. Restart Thunderbird after this change.
|
||||||
|
|
||||||
|
[](/attachment/doc/tb78-1.png)
|
||||||
|
[](/attachment/doc/tb78-2.png)
|
||||||
|
[](/attachment/doc/tb78-3.png)
|
||||||
|
|
||||||
|
You need to obtain your key ID which should be **exactly 16 characters**. Enter the command `qubes-gpg-client-wrapper -K --keyid-format long`:
|
||||||
|
|
||||||
|
```
|
||||||
|
[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
|
||||||
/home/user/.gnupg/pubring.kbx
|
/home/user/.gnupg/pubring.kbx
|
||||||
-----------------------------
|
-----------------------------
|
||||||
sec# rsa2048 2019-12-18 [SC] [expires: 2021-12-17]
|
sec rsa2048/777402E6D301615C 2020-09-05 [SC] [expires: 2022-09-05]
|
||||||
50C2035AF57B98CD6E4010F1B808E4BB07BA9EFB
|
F7D2D4E922DFB7B2589AF3E9777402E6D301615C
|
||||||
uid [ultimate] test
|
uid [ultimate] Qubes test <user@localhost>
|
||||||
ssb# rsa2048 2019-12-18 [E]
|
ssb rsa2048/370CE932085BA13B 2020-09-05 [E] [expires: 2022-09-05]
|
||||||
```
|
```
|
||||||
|
|
||||||
If you want change some server option copy `/usr/share/doc/split-gpg2/examples/qubes-split-gpg2.conf.example` to `~/.config/qubes-split-gpg2/qubes-split-gpg2.conf` and change it as desired, it will take precedence over other loaded files, such as the drop-in configuration files with the suffix `.conf` in `~/.config/qubes-split-gpg2/conf.d/`.
|
```
|
||||||
|
[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
|
||||||
|
```
|
||||||
|
|
||||||
If you have a passphrase on your keys and `gpg-agent` only shows the "keygrip" (something like the fingerprint of the private key) when asking for the passphrase, then make sure that you have imported the public key part in the server domain.
|
Open the Account Settings and open the *End-to-End Encryption* tab of the respective email account. Click the *Add Key* button. You'll be offered the choice *Use your external key through GnuPG*. Select it and click Continue.
|
||||||
|
|
||||||
## Subkeys vs primary keys
|
[](/attachment/doc/tb78-4.png)
|
||||||
|
[](/attachment/doc/tb78-5.png)
|
||||||
|
|
||||||
split-gpg2 only knows a hash of the data being signed.
|
The key ID reference you would need here is `777402E6D301615C`. Now paste or type the ID of the secret key that you would like to use. Be careful to enter it correctly, because your input isn't verified. Confirm to save this key ID. Now you can select the key ID to use.
|
||||||
Therefore, it cannot differentiate between e.g. signatures of a piece of data or signatures of another key.
|
|
||||||
This means that a client can use split-gpg2 to sign other keys, which split-gpg1 did not allow.
|
|
||||||
|
|
||||||
To prevent this, split-gpg2 creates a new GnuPG home directory and imports the secret subkeys (**not** the primary key!) to it.
|
[](/attachment/doc/tb78-6.png)
|
||||||
Clients will be able to use the secret parts of the subkeys, but not of the primary key.
|
[](/attachment/doc/tb78-7.png)
|
||||||
If your primary key is able to sign data and certify other keys, and your only subkey can only perform encryption, this means that all signing will fail.
|
|
||||||
To make signing work again, generate a subkey that is capable of signing but **not** certification.
|
|
||||||
split-gpg2 does not generate this key for you, so you need to generate it yourself.
|
|
||||||
If you want to generate a key in software, use the `addkey` command of `gpg2 --edit-key`.
|
|
||||||
If you want to generate a key on a smartcard or other hardware token, use `addcardkey` instead.
|
|
||||||
|
|
||||||
## Advanced usage
|
This key ID will be used to digitally sign or send an encrypted message with your account. For this to work, Thunderbird needs a copy of your public key. At this time, Thunderbird doesn't fetch the public key from `/usr/bin/qubes-gpg-client-wrapper`, you must manually import it. Export the key as follow (assuming the key ID would be `777402E6D301615C`):
|
||||||
|
|
||||||
There are a few option not described in this README.
|
[](/attachment/doc/tb78-8.png)
|
||||||
See the comments in the example (config and the source code)[https://github.com/QubesOS/qubes-app-linux-split-gpg2/blob/main/qubes-split-gpg2.conf.example].
|
[](/attachment/doc/tb78-9.png)
|
||||||
|
|
||||||
Similar to a smartcard, split-gpg2 only tries to protect the private key.
|
Use Thunderbird's Tools menu to open *OpenPGP Key Management*. In that window, use the File menu to access the *Import Public Key(s) From File* command. Open the file with your public key. After the import was successful, right click on the imported key in the list and select *Key Properties*. You must mark your own key as *Yes, I've verified in person this key has the correct fingerprint*.
|
||||||
For advanced usages, consider if a specialized RPC service would be better.
|
|
||||||
It could do things like checking what data is singed, detailed logging, exposing the encrypted content only to a VM without network, etc.
|
|
||||||
|
|
||||||
Using split-gpg2 as the "backend" for split-gpg1 is known to work.
|
Once this is done, you should be able to send an encrypted and signed email by selecting *Require Encryption* or *Digitally Sign This Message* in the compose menu *Options* or *Security* toolbar button. You can try it by sending an email to yourself.
|
||||||
|
|
||||||
## Allow key generation
|
[](/attachment/doc/tb78-10.png)
|
||||||
|
|
||||||
By setting `allow_keygen = yes` in `qubes-split-gpg2.conf` you can allow the client to generate new keys.
|
For more details about using smart cards/Split GPG with Thunderbird PGP feature, please see [Thunderbird:OpenPGP:Smartcards](https://wiki.mozilla.org/Thunderbird:OpenPGP:Smartcards) from which the above documentation is inspired.
|
||||||
Normal usage should not need this.
|
|
||||||
|
|
||||||
**Warning**: This feature is new and not much tested.
|
### Older Thunderbird versions
|
||||||
Therefore it's not security supported!
|
|
||||||
|
|
||||||
## Copyright
|
For Thunderbird versions below 78, the traditional Enigmail + Split GPG setup is required.
|
||||||
|
It is recommended to set up and use `/usr/bin/qubes-gpg-client-wrapper`, as discussed above, in Thunderbird through the Enigmail addon.
|
||||||
|
|
||||||
Copyright (C) 2014 HW42 <hw42@ipsumj.de>\
|
**Warning:** Before adding any account, configuring Enigmail with `/usr/bin/qubes-gpg-client-wrapper` is **required**. By default, Enigmail will generate a default GPG key in `work-email` associated with the newly created Thunderbird account. Generally, it corresponds to the email used in `work-gpg` associated to your private key. In consequence, a new, separate private key will be stored in `work-email` but it _does not_ correspond to your private key in `work-gpg`. Comparing the `fingerprint` or `expiration date` will show that they are not the same private key. In order to prevent Enigmail using this default generated local key in `work-email`, you can safely remove it.
|
||||||
Copyright (C) 2019 Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
|
|
||||||
|
|
||||||
This program is free software; you can redistribute it and/or modify
|
On a fresh Enigmail install, your need to change the default `Enigmail Junior Mode`. Go to Thunderbird preferences and then privacy tab. Select `Force using S/MIME and Enigmail`. Then, in the preferences of Enigmail, make it point to `/usr/bin/qubes-gpg-client-wrapper` instead of the standard GnuPG binary:
|
||||||
it under the terms of the GNU General Public License as published by
|
|
||||||
the Free Software Foundation; either version 2 of the License, or
|
|
||||||
(at your option) any later version.
|
|
||||||
|
|
||||||
This program is distributed in the hope that it will be useful,
|
[](/attachment/doc/tb-enigmail-split-gpg-settings-2.png)
|
||||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
||||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
||||||
GNU General Public License for more details.
|
|
||||||
|
|
||||||
You should have received a copy of the GNU General Public License along
|
## Using Keybase with Split GPG
|
||||||
with this program; if not, write to the Free Software Foundation, Inc.,
|
|
||||||
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
Keybase, a security focused messaging and file-sharing app with GPG integration, can be configured to use Split GPG.
|
||||||
|
|
||||||
|
The Keybase service does not preserve/pass the `QUBES_GPG_DOMAIN` environment variable through to underlying GPG processes, so it **must** be configured to use `/usr/bin/qubes-gpg-client-wrapper` (as discussed above) rather than `/usr/bin/qubes-gpg-client`.
|
||||||
|
|
||||||
|
The following command will configure Keybase to use `/usr/bin/qubes-gpg-client-wrapper` instead of its built-in GPG client:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
|
||||||
|
```
|
||||||
|
|
||||||
|
Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be able to use `keybase pgp select` to choose a GPG key from your backend GPG app qube and link that key to your Keybase identity.
|
||||||
|
|
||||||
|
## Using Git with Split GPG
|
||||||
|
|
||||||
|
Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed.
|
||||||
|
The most basic `~/.gitconfig` file enabling Split GPG looks something like this.
|
||||||
|
|
||||||
|
```
|
||||||
|
[user]
|
||||||
|
name = <YOUR_NAME>
|
||||||
|
email = <YOUR_EMAIL_ADDRESS>
|
||||||
|
signingKey = <YOUR_KEY_ID>
|
||||||
|
|
||||||
|
[gpg]
|
||||||
|
program = qubes-gpg-client-wrapper
|
||||||
|
```
|
||||||
|
|
||||||
|
Your key id is the public id of your signing key, which can be found by running `qubes-gpg-client --list-keys`.
|
||||||
|
In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-email ~]$ qubes-gpg-client --list-keys
|
||||||
|
/home/user/.gnupg/pubring.kbx
|
||||||
|
-----------------------------
|
||||||
|
pub ed25519 2022-08-16 [C]
|
||||||
|
E142F75A6B1B610E0E8F874FB45589245791CACB
|
||||||
|
uid [ultimate] Qubes User <user@example.com>
|
||||||
|
sub ed25519 2022-08-16 [S]
|
||||||
|
sub cv25519 2022-08-16 [E]
|
||||||
|
sub ed25519 2022-08-16 [A]
|
||||||
|
```
|
||||||
|
|
||||||
|
To sign commits, you now add the "-S" flag to your commit command, which should prompt for Split GPG usage.
|
||||||
|
If you would like to automatically sign all commits, you can add the following snippet to `~/.gitconfig`.
|
||||||
|
|
||||||
|
```
|
||||||
|
[commit]
|
||||||
|
gpgSign = true
|
||||||
|
```
|
||||||
|
|
||||||
|
Lastly, if you would like to add aliases to sign and verify tags using the conventions the Qubes OS Project recommends, refer to the [code signing documentation](/doc/code-signing/#using-pgp-with-git).
|
||||||
|
|
||||||
|
## Importing public keys
|
||||||
|
|
||||||
|
Use `qubes-gpg-import-key` in the client app qube to import the key into the GPG backend VM.
|
||||||
|
|
||||||
|
```shell_session
|
||||||
|
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
|
||||||
|
[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
|
||||||
|
```
|
||||||
|
|
||||||
|
A safe, unspoofable user consent dialog box is displayed.
|
||||||
|
|
||||||
|
[](/attachment/doc/r2-split-gpg-5.png)
|
||||||
|
|
||||||
|
Selecting "Yes to All" will add a line in the corresponding [RPC Policy](/doc/rpc-policy/) file.
|
||||||
|
|
||||||
|
## Advanced: Using Split GPG with Subkeys
|
||||||
|
|
||||||
|
Users with particularly high security requirements may wish to use Split GPG with [subkeys](https://wiki.debian.org/Subkeys).
|
||||||
|
However, this setup comes at a significant cost: It will be impossible to sign other people's keys with the master secret key without breaking this security model.
|
||||||
|
Nonetheless, if signing others' keys is not required, then Split GPG with subkeys offers unparalleled security for one's master secret key.
|
||||||
|
|
||||||
|
### Setup Description
|
||||||
|
|
||||||
|
In this example, the following keys are stored in the following locations (see below for definitions of these terms):
|
||||||
|
|
||||||
|
| PGP Key(s) | VM Name |
|
||||||
|
| ---------- | ------------ |
|
||||||
|
| `sec` | `vault` |
|
||||||
|
| `ssb` | `work-gpg` |
|
||||||
|
| `pub` | `work-email` |
|
||||||
|
|
||||||
|
* `sec` (master secret key)
|
||||||
|
|
||||||
|
Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
|
||||||
|
This key may be created *without* an expiration date.
|
||||||
|
This is for two reasons.
|
||||||
|
First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below).
|
||||||
|
Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used) or does not.
|
||||||
|
An adversary who *does* possess the passphrase can simply use it to legally extend the expiration date of the key (or remove it entirely).
|
||||||
|
An adversary who does *not* possess the passphrase cannot use the key at all.
|
||||||
|
In either case, an expiration date provides no additional benefit.
|
||||||
|
|
||||||
|
By the same token, however, having a passphrase on the key is of little value.
|
||||||
|
An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it.
|
||||||
|
An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key.
|
||||||
|
Therefore, using a passphrase at all should be considered optional.
|
||||||
|
It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised.
|
||||||
|
|
||||||
|
* `ssb` (secret subkey)
|
||||||
|
|
||||||
|
Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
|
||||||
|
You may also wish to give these subkeys reasonable expiration dates (e.g., one year).
|
||||||
|
Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires.
|
||||||
|
|
||||||
|
On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey.
|
||||||
|
If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails.
|
||||||
|
If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails.
|
||||||
|
|
||||||
|
On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them.
|
||||||
|
This can be problematic, since there is no consensus on how expired signatures should be handled.
|
||||||
|
Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
|
||||||
|
|
||||||
|
* `pub` (public key)
|
||||||
|
|
||||||
|
This is the complement of the master secret key.
|
||||||
|
It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
|
||||||
|
|
||||||
|
* `vault`
|
||||||
|
|
||||||
|
This is a network-isolated VM.
|
||||||
|
The initial master keypair and subkeys are generated in this VM.
|
||||||
|
The master secret key *never* leaves this VM under *any* circumstances.
|
||||||
|
No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances.
|
||||||
|
|
||||||
|
* `work-gpg`
|
||||||
|
|
||||||
|
This is a network-isolated VM.
|
||||||
|
This VM is used *only* as the GPG backend for `work-email`.
|
||||||
|
The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM.
|
||||||
|
Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances.
|
||||||
|
|
||||||
|
* `work-email`
|
||||||
|
|
||||||
|
This VM has access to the mail server.
|
||||||
|
It accesses the `work-gpg` VM via the Split GPG protocol.
|
||||||
|
The public key may be stored in this VM so that it can be attached to emails and for other such purposes.
|
||||||
|
|
||||||
|
### Security Benefits
|
||||||
|
|
||||||
|
In the standard Split GPG setup, there are at least two ways in which the `work-gpg` VM might be compromised.
|
||||||
|
First, an attacker who is capable of exploiting a hypothetical bug in `work-email`'s [MUA](https://en.wikipedia.org/wiki/Mail_user_agent) could gain control of the `work-email` VM and send a malformed request which exploits a hypothetical bug in the GPG backend (running in the `work-gpg` VM), giving the attacker control of the `work-gpg` VM.
|
||||||
|
Second, a malicious public key file which is imported into the `work-gpg` VM might exploit a hypothetical bug in the GPG backend which is running there, again giving the attacker control of the `work-gpg` VM.
|
||||||
|
In either case, such an attacker might then be able to leak both the master secret key and its passphrase (if any is used, it would regularly be input in the work-gpg VM and therefore easily obtained by an attacker who controls this VM) back to the `work-email` VM or to another VM (e.g., the `netvm`, which is always untrusted by default) via the Split GPG protocol or other [covert channels](/doc/data-leaks/).
|
||||||
|
Once the master secret key is in the `work-email` VM, the attacker could simply email it to himself (or to the world).
|
||||||
|
|
||||||
|
In the alternative setup described in this section (i.e., the subkey setup), even an attacker who manages to gain access to the `work-gpg` VM will not be able to obtain the user's master secret key since it is simply not there.
|
||||||
|
Rather, the master secret key remains in the `vault` VM, which is extremely unlikely to be compromised, since nothing is ever copied or transferred into it.
|
||||||
|
[^a-note] The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
|
||||||
|
(This is significantly less devastating than having to create a new *master* keypair.)
|
||||||
|
|
||||||
|
[^a-note]: In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the template](/doc/templates/#trusting-your-templates) upon which the `vault` VM is based.
|
||||||
|
|
||||||
|
### Subkey Tutorials and Discussions
|
||||||
|
|
||||||
|
(Note: Although the tutorials below were not written with Qubes Split GPG in mind, they can be adapted with a few commonsense adjustments.
|
||||||
|
As always, exercise caution and use your good judgment.)
|
||||||
|
|
||||||
|
* ["OpenPGP in Qubes OS" on the qubes-users mailing list](https://groups.google.com/d/topic/qubes-users/Kwfuern-R2U/discussion)
|
||||||
|
* ["Creating the Perfect GPG Keypair" by Alex Cabal](https://alexcabal.com/creating-the-perfect-gpg-keypair/)
|
||||||
|
* ["GPG Offline Master Key w/ smartcard" maintained by Abel Luck](https://gist.github.com/abeluck/3383449)
|
||||||
|
* ["Using GnuPG with QubesOS" by Alex](https://apapadop.wordpress.com/2013/08/21/using-gnupg-with-qubesos/)
|
||||||
|
|
||||||
|
## Current limitations
|
||||||
|
|
||||||
|
* Current implementation requires importing of public keys to the vault domain.
|
||||||
|
This opens up an avenue to attack the gpg running in the backend domain via a hypothetical bug in public key importing code.
|
||||||
|
See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
|
||||||
|
|
||||||
|
* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
|
||||||
|
Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.
|
||||||
|
|
||||||
|
* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
|
||||||
|
It will give an `Inappropriate ioctl for device` error.
|
||||||
|
Do not set passphrases for the private keys in the GPG backend domain.
|
||||||
|
Doing so won't provide any extra security anyway, as explained in the introduction and in [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
|
||||||
|
If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use `gpg2 --edit-key <key_id>` then `passwd` to set an empty passphrase.
|
||||||
|
Note that `pinentry` might show an error when you try to set an empty passphrase, but it will still make the change.
|
||||||
|
(See [this StackExchange answer](https://unix.stackexchange.com/a/379373) for more information.)
|
||||||
|
Note: The error shows only if you **do not** have graphical pinentry installed.
|
||||||
|
|||||||
@ -158,21 +158,68 @@ Please see [How to Install Software](/doc/how-to-install-software).
|
|||||||
|
|
||||||
## Uninstalling
|
## Uninstalling
|
||||||
|
|
||||||
To remove a template, the graphical `Qube Manager` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click "Delete qube" to begin removal. If no issues are found, a dialog box will request the template's name be typed as a final confirmation. Upon completion, the template will be deleted.
|
If you want to remove a template you must make sure that it is not being used.
|
||||||
|
You should check that the template is not being used by any qubes,
|
||||||
|
and also that it is not set as the default template.
|
||||||
|
|
||||||
|
The procedure for uninstalling a template depends on how it was created.
|
||||||
|
|
||||||
|
If the template was originaly created by cloning another template, then you can
|
||||||
|
delete it the same way as you would any other qube. In the Qube Manager,
|
||||||
|
right-click on the template and select **Delete qube**. (If you're not sure,
|
||||||
|
you can safely try this method first to see if it works.)
|
||||||
|
|
||||||
|
If, on the other hand, the template came pre-installed or was installed by
|
||||||
|
installing a template package in dom0, per the instructions
|
||||||
|
[above](#installing), then you must execute the following type of command in
|
||||||
|
dom0 in order to uninstall it:
|
||||||
|
|
||||||
Alternatively, to remove a template via the command line in dom0:
|
|
||||||
```
|
```
|
||||||
$ qvm-template remove <TEMPLATE_NAME>
|
$ qvm-template remove qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>
|
||||||
```
|
```
|
||||||
|
|
||||||
\<TEMPLATE_NAME> is the first column from the output of:
|
`qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>` is the name of the desired
|
||||||
|
template package.
|
||||||
|
|
||||||
|
You may see warning messages like the following:
|
||||||
|
|
||||||
```
|
```
|
||||||
$ qvm-template list --installed
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/whitelisted-appmenus.list: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/vm-whitelisted-appmenus.list: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.04: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.03: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.02: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.01: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/root.img.part.00: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/netvm-whitelisted-appmenus.list: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/icon.png: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/clean-volatile.img.tar: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.templates: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps.tempicons: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX/apps: remove failed: No such file or directory
|
||||||
|
warning: file /var/lib/qubes/vm-templates/fedora-XX: remove failed: No such file or directory
|
||||||
```
|
```
|
||||||
|
|
||||||
In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. "Global property default_template" requires [switching](#switching) the default_template property to another template. "Template for" can be resolved by [switching](#switching) the dependent qubes' template. Once the issues are addressed, attempt the removal again.
|
These are normal and expected. Nothing is wrong, and no action is required to
|
||||||
|
address these warnings.
|
||||||
|
|
||||||
If the template's entry in the Qubes Menu is not removed with its uninstallation, consult the [troubleshooting page](/doc/app-menu-shortcut-troubleshooting/#fixing-shortcuts).
|
If the uninstallation command doesn't work, pay close attention to
|
||||||
|
any error message: it may tell you what qube is using the template,
|
||||||
|
or if the template is default. In other cases, please see [VM Troubleshooting](/doc/vm-troubleshooting/).
|
||||||
|
|
||||||
|
If the Applications Menu entry doesn't go away after you uninstall a template,
|
||||||
|
execute the following type of command in dom0:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ rm ~/.local/share/applications/<TEMPLATE_NAME>
|
||||||
|
```
|
||||||
|
|
||||||
|
Applications Menu entries for backups of removed qubes can also be found in
|
||||||
|
`/usr/local/share/applications/` of dom0.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ rm /usr/local/share/applications/<TEMPLATE_NAME>
|
||||||
|
```
|
||||||
|
|
||||||
## Reinstalling
|
## Reinstalling
|
||||||
|
|
||||||
@ -387,9 +434,8 @@ this context: the same as their template filesystem, of course.
|
|||||||
|
|
||||||
* Some templates are available in ready-to-use binary form, but some of them
|
* Some templates are available in ready-to-use binary form, but some of them
|
||||||
are available only as source code, which can be built using the [Qubes
|
are available only as source code, which can be built using the [Qubes
|
||||||
Builder](https://github.com/QubesOS/qubes-builderv2/). In particular, some
|
Builder](/doc/qubes-builder/). In particular, some template "flavors" are
|
||||||
template "flavors" are available in source code form only. For the
|
available in source code form only. For the technical details of the template
|
||||||
technical details of the template
|
|
||||||
system, please see [Template Implementation](/doc/template-implementation/).
|
system, please see [Template Implementation](/doc/template-implementation/).
|
||||||
Take a look at the [Qubes Builder](/doc/qubes-builder-v2/) documentation for
|
Take a look at the [Qubes Builder](/doc/qubes-builder/) documentation for
|
||||||
instructions on how to compile them.
|
instructions on how to compile them.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user