Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-09 23:22:49 -04:00
Code Issues Projects Releases Packages Wiki Activity

Correct code-block lexers

Browse source 
Changing `bash` lexer to `console` because it is appropriate most of
the time. Then after a manual review, some lexer have been changed.

I used `text` each time I was unsure, and for prompt outputs.

The page `/developer/building/qubes-iso-building.rst` still need to be
reviewed (look for lines starting with `$ #`).

I'm not sure about the Windows pages, should we use
[doscon](https://pygments.org/docs/lexers/#pygments.lexers.shell.MSDOSSessionLexer)
or `powershell`?

Is there an appropriate lexer for `guid.conf` content?

**Statistics - Before**
    870 bash
      9 python
      9 c
      2 yaml

**Statistics - After**
    684 console
    111 text
     44 bash
     16 yaml
      9 systemd
      9 c
      8 python
      4 ini
      4 doscon
      2 markdown
      2 desktop
      1 xorg.conf
      1 xml+jinja
      1 xml
      1 kconfig
      1 html

This suggests that the default lexer should be `console`.
This commit is contained in:
parulin 2025-07-30 09:43:09 -04:00
parent b53776e1eb
commit ba399ac488
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
98 changed files with 1022 additions and 1029 deletions
Download patch file Download diff file Expand all files Collapse all files

107
developer/building/development-workflow.rst
View file

@ -38,7 +38,7 @@ Prepare fresh version of kernel sources, with Qubes-specific patches applied
In ``qubes-builder/artifacts/sources/linux-kernel``:
.. code:: bash
.. code:: console
make prep
@ -46,14 +46,9 @@ In ``qubes-builder/artifacts/sources/linux-kernel``:
The resulting tree will be in kernel-<VERSION>/linux-<VERSION>:
.. code:: bash
.. code:: console
ls -ltrd kernel*/linux*
.. code:: bash
drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18
drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
@ -65,7 +60,7 @@ Go to the kernel tree and update the version
In ``qubes-builder/artifacts/sources/linux-kernel``:
.. code:: bash
.. code:: console
cd kernel-3.4.18/linux-3.4.18
@ -77,7 +72,7 @@ Changing the config
In ``kernel-3.4.18/linux-3.4.18``:
.. code:: bash
.. code:: console
cp ../../config .config
make oldconfig
@ -86,7 +81,7 @@ In ``kernel-3.4.18/linux-3.4.18``:
Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``:
.. code:: bash
.. code:: console
make menuconfig
@ -94,7 +89,7 @@ Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``:
Copy the modified config back into the kernel tree:
.. code:: bash
.. code:: console
cp .config ../../../config
@ -106,20 +101,20 @@ Patching the code
TODO: describe the workflow for patching the code, below are some random notes, not working well
.. code:: bash
.. code:: console
ln -s ../../patches.xen
export QUILT_PATCHES=patches.xen
export QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
export QUILT_SERIES=../../series-pvops.conf
quilt new patches.xen/pvops-3.4-0101-usb-xen-pvusb-driver-bugfix.patch
quilt add drivers/usb/host/Kconfig drivers/usb/host/Makefile \
drivers/usb/host/xen-usbback/* drivers/usb/host/xen-usbfront.c \
include/xen/interface/io/usbif.h
*edit something*
quilt refresh
cd ../..
vi series.conf
@ -136,7 +131,7 @@ You might want to take a moment here to review (git diff, git status), commit yo
To actually build RPMs, in qubes-builder:
.. code:: bash
.. code:: console
./qb -c linux-kernel package fetch prep build
@ -177,14 +172,14 @@ TODO: edit this script to be more generic
.. code:: bash
#!/bin/sh
set -x
set -e
QUBES_PY_DIR=/usr/lib64/python2.6/site-packages/qubes
QUBES_PY=$QUBES_PY_DIR/qubes.py
QUBESUTILS_PY=$QUBES_PY_DIR/qubesutils.py
qvm-run -p qubes-devel 'cd qubes-builder/qubes-src/core/dom0; tar c qmemman/qmemman*.py qvm-core/*.py qvm-tools/* misc/vm-template-hvm.conf misc/qubes-start.desktop ../misc/block-snapshot aux-tools ../qrexec' |tar xv
cp $QUBES_PY qubes.py.bak$$
cp $QUBESUTILS_PY qubesutils.py.bak$$
@ -210,7 +205,7 @@ TODO: make it more generic
.. code:: bash
#!/bin/sh
BAK=qvm-tools.bak$$
mkdir -p $BAK
cp -a /usr/bin/qvm-* /usr/bin/qubes-* $BAK/
@ -231,7 +226,7 @@ Copy from dom0 to an appvm
domain=$1
file=$2
fname=`basename $file`
qvm-run $domain 'mkdir /home/user/incoming/dom0 -p'
cat $file| qvm-run --pass-io $domain "cat > /home/user/incoming/dom0/$fname"
@ -250,9 +245,9 @@ Service file (save in ``/usr/local/etc/qubes-rpc/local.Git`` in target VM):
.. code:: bash
#!/bin/sh
exec 2>/tmp/log2
read service rel repo
echo "Params: $service $rel $repo" >&2
# Adjust regexps if needed
@ -279,9 +274,9 @@ Client script (save in ``~/bin/git-qrexec`` in source VM):
.. code:: bash
#!/bin/sh
VMNAME=$1
(echo $GIT_EXT_SERVICE $2 $3; exec cat) | qrexec-client-vm $VMNAME local.Git
@ -302,14 +297,14 @@ You can create ``~/bin/add-remote`` script to ease adding remotes:
.. code:: bash
#!/bin/sh
[ -n "$1" ] || exit 1
if [ "$1" = "tb" ]; then
git remote add $1 "ext::git-qrexec testbuilder 3 `basename $PWD`"
exit $?
fi
git remote add $1 git@GitHub.com:$1/qubes-`basename $PWD`
@ -333,9 +328,9 @@ In source VM, grab `linux-yum <https://GitHub.com/QubesOS/qubes-linux-yum>`__ re
.. code:: bash
#!/bin/sh
VMNAME=repo-vm
set -e
qvm-copy-to-vm $VMNAME $1
# remove only files, leave directory structure
@ -347,7 +342,7 @@ In source VM, grab `linux-yum <https://GitHub.com/QubesOS/qubes-linux-yum>`__ re
In target VM, setup actual yum repository (also based on `linux-yum <https://GitHub.com/QubesOS/qubes-linux-yum>`__, this time without modifications). You will also need to setup some gpg key for signing packages (it is possible to force yum to install unsigned packages, but it isn’t possible for ``qubes-dom0-update`` tool). Fill ``~/.rpmmacros`` with key description:
.. code:: bash
.. code:: text
%_gpg_name Test packages signing key
@ -358,27 +353,27 @@ Then setup ``local.UpdateYum`` qrexec service (``/usr/local/etc/qubes-rpc/local.
.. code:: bash
#!/bin/sh
if [ -z "$QREXEC_REMOTE_DOMAIN" ]; then
exit 1
fi
real_repository=/home/user/linux-yum
incoming=/home/user/QubesIncoming/$QREXEC_REMOTE_DOMAIN
find $incoming -name '*.rpm' |xargs rpm -K |grep -iv pgp |cut -f1 -d: |xargs -r setsid -w rpm --addsign 2>&1
rsync -lr --remove-source-files $incoming/ $real_repository
cd $real_repository
export SKIP_REPO_CHECK=1
if [ -d $incoming/r3.1 ]; then
./update_repo-unstable.sh r3.1
fi
if [ -d $incoming/r3.0 ]; then
./update_repo-unstable.sh r3.0
fi
if [ -d $incoming/r2 ]; then
./update_repo-unstable.sh r2
fi
@ -401,7 +396,7 @@ Usage: setup ``builder.conf`` in source VM to use your dummy-uploader repository
Then use ``make update-repo-unstable`` to upload the packages. You can also specify selected components on command line, then build them and upload to the repository:
.. code:: bash
.. code:: console
make COMPONENTS="core-agent-linux gui-agent-linux linux-utils" qubes update-repo-unstable
@ -409,7 +404,7 @@ Then use ``make update-repo-unstable`` to upload the packages. You can also spec
On the test machine, add yum repository (``/etc/yum.repos.d``) pointing at just configured HTTP server. For example:
.. code:: bash
.. code:: ini
[local-test]
name=Test
@ -440,12 +435,12 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
.. code:: bash
#!/bin/sh
set -e
current_release=$1
VMNAME=repo-vm
qvm-copy-to-vm $VMNAME $1
find $current_release -type f -name '*.deb' -delete
rm -f $current_release/vm/db/*
@ -458,13 +453,13 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
.. code:: bash
#!/bin/sh
if [ -z "$QREXEC_REMOTE_DOMAIN" ]; then
exit 1
fi
incoming=/home/user/QubesIncoming/$QREXEC_REMOTE_DOMAIN
rsync -lr --remove-source-files $incoming/ /home/user/linux-deb/
cd /home/user/linux-deb
export SKIP_REPO_CHECK=1
@ -473,13 +468,13 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
./update-local-repo.sh r3.1/vm $dist
done
fi
if [ -d $incoming/r3.0 ]; then
for dist in `ls r3.0/vm/dists`; do
./update-local-repo.sh r3.0/vm $dist
done
fi
if [ -d $incoming/r2 ]; then
for dist in `ls r2/vm/dists`; do
./update-local-repo.sh r2/vm $dist
@ -495,17 +490,17 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
.. code:: bash
#!/bin/sh
set -e
# Set this to your local repository signing key
SIGN_KEY=01ABCDEF
[ -z "$1" ] && { echo "Usage: $0 <repo> <dist>"; exit 1; }
REPO_DIR=$1
DIST=$2
if [ "$DIST" = "wheezy-unstable" ]; then
DIST_TAG=deb7
elif [ "$DIST" = "jessie-unstable" ]; then
@ -513,7 +508,7 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
elif [ "$DIST" = "stretch-unstable" ]; then
DIST_TAG=deb9
fi
pushd $REPO_DIR
mkdir -p dists/$DIST/main/binary-amd64
dpkg-scanpackages --multiversion --arch "*$DIST_TAG*" . > dists/$DIST/main/binary-amd64/Packages
@ -535,7 +530,7 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
echo $1
}
calc_sha1 main/binary-amd64/Packages >> dists/$DIST/Release
rm -f $DIST/Release.gpg
rm -f $DIST/InRelease
gpg -abs -u "$SIGN_KEY" \
@ -543,7 +538,7 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
gpg -a -s --clearsign -u "$SIGN_KEY" \
< dists/$DIST/Release > dists/$DIST/InRelease
popd
if [ `id -u` -eq 0 ]; then
chown -R --reference=$REPO_DIR $REPO_DIR
fi
@ -552,7 +547,7 @@ Steps are mostly the same as in the case of yum repo. The only details that diff
Usage: add this line to ``/etc/apt/sources.list`` on test machine (adjust host and path):
.. code:: bash
.. code:: text
deb http://local-test.lan/linux-deb/r3.1 jessie-unstable main

14
developer/building/qubes-builder-v2.rst
View file

@ -52,7 +52,7 @@ This is a simple setup using a docker executor. This is a good default choice; i
3. Clone the qubes-builder v2 repository into a location of your choice:
.. code:: bash
.. code:: console
git clone https://github.com/QubesOS/qubes-builderv2
cd qubes-builderv2/
@ -88,28 +88,28 @@ 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:
.. code:: bash
.. code:: 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

40
developer/building/qubes-builder.rst
View file

@ -4,7 +4,7 @@ Qubes builder
.. warning::
**Note:** These instructions concern the older Qubes builder (v1). It supports only building Qubes 4.2 or earlier.The build process has been completely rewritten in `qubes-builder v2 <https://github.com/QubesOS/qubes-builderv2/>`__ . This can be used for building Qubes R4.2 and later, and all related components.
**Note: See** :doc:`ISO building instructions </developer/building/qubes-iso-building>` **for a streamlined overview on how to use the build system.**
@ -53,7 +53,7 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou
Usually you can install those packages by just issuing:
.. code:: bash
.. code:: console
sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA
@ -62,7 +62,7 @@ The build system creates build environments in chroots and so no other packages
The build system is configured via builder.conf file. You can use the setup.sh script to create and modify this file. Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.:
.. code:: bash
.. code:: console
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
@ -73,7 +73,7 @@ One additional useful requirement is that ‘sudo root’ must work without any
Additionally, if building with signing enabled (NO_SIGN is not set), you must adjust ``\~/.rpmmacros`` file so that it points to the GPG key used for package signing, e.g.:
.. code:: bash
.. code:: text
%_signature gpg
%_gpg_path /home/user/.gnupg
@ -84,38 +84,38 @@ It is also recommended that you use an empty passphrase for the private key used
So, to build Qubes you would do:
.. code:: bash
.. code:: console
# Import the Qubes master key
gpg --recv-keys 0xDDFA1A3E36879494
# Verify its fingerprint, set as 'trusted'.
# This is described here:
# https://www.qubes-os.org/doc/VerifyingSignatures
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
git clone https://github.com/QubesOS/qubes-builder.git qubes-builder
cd qubes-builder
# Verify its integrity:
git tag -v `git describe`
cp example-configs/qubes-os-master.conf builder.conf
# edit the builder.conf file and set the following variables:
# NO_SIGN="1"
# Download all components:
make get-sources
# And now to build all Qubes RPMs (this will take a few hours):
make qubes
# ... and then to build the ISO
make iso
@ -123,7 +123,7 @@ And this should produce a shiny new ISO.
You can also build selected component separately. Eg. to compile only gui virtualization agent/daemon:
.. code:: bash
.. code:: console
make gui-daemon
@ -152,7 +152,7 @@ You can also modify sources somehow if you wish. Here are some basic steps:
3. Download unmodified sources
.. code:: bash
.. code:: console
make get-sources
@ -163,14 +163,14 @@ You can also modify sources somehow if you wish. Here are some basic steps:
6. ``get-sources`` is already done, so continue with the next one. You can skip ``sign-all`` if you’ve disabled signing
.. code:: bash
.. code:: console
make vmm-xen core-admin linux-kernel gui-daemon template desktop-linux-kde installer-qubes-os manager linux-dom0-updates
7. build iso installation image
.. code:: bash
.. code:: console
make iso

84
developer/building/qubes-iso-building.rst
View file

@ -4,7 +4,7 @@ Qubes ISO building
.. warning::
**Note:** These instructions concern the older Qubes builder (v1). It supports only building Qubes 4.2 or earlier.The build process has been completely rewritten in `qubes-builder v2 <https://github.com/QubesOS/qubes-builderv2/>`__ . This can be used for building Qubes R4.2 and later versions, and all related components.
Build Environment
@ -15,14 +15,14 @@ Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below
**Notes:** On modern Fedora system (like Fedora 37) SeLinux is enforced by default and is blocking the build system. You would get error like “can’t create transaction lock on /…/rpm/.rpm.lock (Permission denied)”. You can set SeLinux to permissive mode with
.. code:: bash
.. code:: console
sudo setenforce 0
In ``dom0``, install the Fedora 36 (or 37) template if you don’t already have it.
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-template-fedora-36
@ -40,17 +40,17 @@ Once you’ve built the development AppVM, open a Terminal window to it and inst
Get the necessary keys to verify the sources (run these and other commands below as a regular user, not root):
.. code:: bash
.. code:: console
wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
gpg --import qubes-master-signing-key.asc
gpg --edit-key 36879494
fpr
# Verify fingerprint! See Note below!
# Once verified, set trust to *ultimate*
# (Typical sequence is trust, 5, Y, q)
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
$ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
$ gpg --import qubes-master-signing-key.asc
$ gpg --edit-key 36879494
$ fpr
$ # Verify fingerprint! See Note below!
$ # Once verified, set trust to *ultimate*
$ # (Typical sequence is trust, 5, Y, q)
$ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
$ gpg --import qubes-developers-keys.asc
@ -58,7 +58,7 @@ Get the necessary keys to verify the sources (run these and other commands below
Now let’s bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:
.. code:: bash
.. code:: console
git clone https://github.com/QubesOS/qubes-builder.git
cd qubes-builder
@ -76,37 +76,37 @@ Build using setup script
Let’s configure the builder first (see :ref:`procedure <developer/building/qubes-iso-building:build using manual steps>` at bottom if you would prefer to manually configure):
.. code:: bash
.. code:: console
cd ~/qubes-builder
./setup
# Select Yes to add Qubes Master Signing Key
# Select Yes to add Qubes OS Signing Key
# Select 4.1 for version
# Stable
# Select Yes for fast Git cloning
# Select Current (if you want the option to use pre-built packages)
# Select No (we want a full build)
# Select fc36 and bullseye (for the currently shipping templates)
# Select builder-rpm, builder-debian, template-whonix, mgmt-salt
# Select Yes to add adrelanos's third party key
# Select Yes (to download)
$ cd ~/qubes-builder
$ ./setup
$ # Select Yes to add Qubes Master Signing Key
$ # Select Yes to add Qubes OS Signing Key
$ # Select 4.1 for version
$ # Stable
$ # Select Yes for fast Git cloning
$ # Select Current (if you want the option to use pre-built packages)
$ # Select No (we want a full build)
$ # Select fc36 and bullseye (for the currently shipping templates)
$ # Select builder-rpm, builder-debian, template-whonix, mgmt-salt
$ # Select Yes to add adrelanos's third party key
$ # Select Yes (to download)
Once it completes downloading, re-run ``setup`` to add the Whonix templates:
.. code:: bash
.. code:: console
./setup
# Choose the same options as above, except at templates select:
# fc36, bullseye, whonix-gateway-16, whonix-workstation-16
$ ./setup
$ # Choose the same options as above, except at templates select:
$ # fc36, bullseye, whonix-gateway-16, whonix-workstation-16
Continue the build process with:
.. code:: bash
.. code:: console
make install-deps
make get-sources
@ -119,7 +119,7 @@ You may also want to add ``COMPONENTS := $(filter-out gcc,$(COMPONENTS))`` to by
Finally, if you are making a test build, use:
.. code:: bash
.. code:: console
make qubes
make iso
@ -128,7 +128,7 @@ Finally, if you are making a test build, use:
Or for a fully signed build (this requires setting ``SIGN_KEY`` in ``builder.conf``):
.. code:: bash
.. code:: console
make qubes
make sign-all
@ -146,7 +146,7 @@ Instead of using ``./setup``, you can manually configure the build. The script t
If you will be building Whonix templates:
.. code:: bash
.. code:: console
cd ~
gpg --keyserver pgp.mit.edu --recv-keys 916B8D99C38EAF5E8ADC7A2A8D66066A2EEACCDA
@ -156,7 +156,7 @@ If you will be building Whonix templates:
**Note:** It’s very important to check the fingerprint displayed against multiple sources such as the `Whonix web site <https://www.whonix.org/wiki/Whonix_Signing_Key>`__, etc. It should look something like this:
.. code:: bash
.. code:: text
pub rsa4096 2014-01-16 [SC] [expires: 2026-01-23]
Key fingerprint = 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA
@ -171,7 +171,7 @@ If you will be building Whonix templates:
Next, prepare the Git keyring directory and copy them in:
.. code:: bash
.. code:: console
export GNUPGHOME=~/qubes-builder/keyrings/git
mkdir --parents "$GNUPGHOME"
@ -183,7 +183,7 @@ Next, prepare the Git keyring directory and copy them in:
Copy one of the example configurations:
.. code:: bash
.. code:: console
cd ~/qubes-builder
cp example-configs/qubes-os-master.conf builder.conf
@ -194,7 +194,7 @@ Edit ``builder.conf``, referring to ``doc/Configuration.md`` for a description o
Continue the build process with:
.. code:: bash
.. code:: console
make install-deps
make get-sources
@ -206,7 +206,7 @@ When building the Whonix templates, you will often need to add/update the ``WHON
Finally, if you are making a test build, use:
.. code:: bash
.. code:: console
make qubes
make iso
@ -215,7 +215,7 @@ Finally, if you are making a test build, use:
Or for a fully signed build (this requires setting ``SIGN_KEY`` in ``builder.conf``):
.. code:: bash
.. code:: console
make qubes
make sign-all

34
developer/code/code-signing.rst
View file

@ -19,26 +19,26 @@ Alex Cabal has written an excellent `guide <https://alexcabal.com/creating-the-p
gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
gpg: directory '/home/user/.gnupg' created
gpg: keybox '/home/user/.gnupg/pubring.kbx' created
**Note:** Use "gpg --full-generate-key" for a full featured key generation dialog.
GnuPG needs to construct a user ID to identify your key.
Real name: Bilbo Baggins
Email address: bilbo@shire.org
You selected this USER-ID:
"Bilbo Baggins <bilbo@shire.org>"
Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
<type your passphrase>
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
@ -48,7 +48,7 @@ Alex Cabal has written an excellent `guide <https://alexcabal.com/creating-the-p
gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/87975838063F97A968D503266E2F4E7AF50A5827.rev'
public and secret key created and signed.
pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
87975838063F97A968D503266E2F4E7AF50A5827
uid Bilbo Baggins <bilbo@shire.org>
@ -68,7 +68,7 @@ In the example below, we will use ``keyserver.ubuntu.com``.
Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID** which is the last 16 hex digits of the long number in the second line of the output above:
.. code:: bash
.. code:: text
pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
87975838063F97A968D503266E2F4E7AF50A5827
@ -89,7 +89,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
1. Set up Git to use your key:
.. code:: bash
.. code:: console
git config --global user.signingkey <KEYID>
@ -97,14 +97,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
2. Set up Git to sign your commits with your key:
.. code:: bash
.. code:: console
git config --global commit.gpgsign true
Alternatively, manually specify when a commit is to be signed:
.. code:: bash
.. code:: console
git commit -S
@ -113,14 +113,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check.
This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history.
.. code:: bash
.. code:: console
git tag -s <tag_name> -m "<tag_message>"
You can also create an alias to make this easier. Edit your ``~/.gitconfig`` file. In the ``[alias]`` section, add ``stag`` to create signed tags and ``spush`` to create signed tags and push them.
.. code:: bash
.. code:: ini
[alias]
stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'"
@ -129,7 +129,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
You may also find it convenient to have an alias for verifying the tag on the latest commit:
.. code:: bash
.. code:: console
vtag = !git tag -v `git describe`
@ -169,14 +169,14 @@ In this case, you have several options to sign the commit:
1. Amend the commit and replace it with a signed commit. You can use this command to create a new signed commit:
.. code:: bash
.. code:: console
git commit --amend -S
This also rewrites the commit so you need to push it forcefully:
.. code:: bash
.. code:: console
git push -f
@ -184,7 +184,7 @@ In this case, you have several options to sign the commit:
2. Create a signed tag for the unsigned commit. If the commit is back in history and you do not want to change it, you can create a signed tag for this commit and push the signature. You can use the alias from above:
.. code:: bash
.. code:: console
git checkout <commit>
git spush

8
developer/code/source-code.rst
View file

@ -19,7 +19,7 @@ All of our repositories are available under the `QubesOS GitHub account <https:/
To clone a repository:
.. code:: bash
.. code:: console
git clone https://github.com/QubesOS/qubes-<repo_name>.git <repo_name>
@ -27,7 +27,7 @@ To clone a repository:
e.g.:
.. code:: bash
.. code:: console
git clone https://github.com/QubesOS/qubes-core-admin.git core-admin
@ -37,7 +37,7 @@ To build Qubes you do not need to download all these repositories. If you use :d
If you really do want to clone **all** of the repositories, you can use these commands:
.. code:: bash
.. code:: console
curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone
curl "https://api.github.com/orgs/QubesOS/repos?page=2&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone
@ -46,7 +46,7 @@ If you really do want to clone **all** of the repositories, you can use these co
To update (git fetch) **all** of these repositories :
.. code:: bash
.. code:: console
find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \;

26
developer/debugging/automated-tests.rst
View file

@ -46,11 +46,11 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information:
[--do-not-clean] [--do-clean] [--loglevel LEVEL]
[--logfile FILE] [--syslog] [--no-syslog] [--kmsg] [--no-kmsg]
[TESTNAME [TESTNAME ...]]
positional arguments:
TESTNAME list of tests to run named like in description
(default: run all tests)
optional arguments:
-h, --help show this help message and exit
--verbose, -v increase console verbosity level
@ -74,7 +74,7 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information:
allow running in parallel with qubesd; this is
DANGEROUS and WILL RESULT IN INCONSISTENT SYSTEM STATE
--break-to-repl break to REPL after tests
When running only specific tests, write their names like in log, in format:
MODULE+"/"+CLASS+"/"+FUNCTION. MODULE should omit initial "qubes.tests.".
Example: basic/TC_00_Basic/test_000_create
@ -117,7 +117,7 @@ Example test run:
Tests are also compatible with nose2 test runner, so you can use this instead:
.. code:: bash
.. code:: console
sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd
@ -138,7 +138,7 @@ The below example however will assume that you set up a build environment as des
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:
.. code:: bash
.. code:: console
cd ~
sudo dnf install python3-pip lvm2 python35 python3-virtualenv
@ -213,37 +213,37 @@ When testing (Py)QT applications, it’s useful to create a separate QApplicatio
import quamash
import unittest
import gc
class SomeTestCase(unittest.TestCase):
def setUp(self):
[...]
# force "cleanlooks" style, the default one on Xfce (GtkStyle) use
# static variable internally and caches pointers to later destroyed
# objects (result: SEGV)
self.qtapp = QtGui.QApplication(["test", "-style", "cleanlooks"])
# construct event loop even if this particular test doesn't use it,
# otherwise events with qtapp references will be queued there anyway and the
# first test that actually use event loop will try to dereference (already
# destroyed) objects, resulting in SEGV
self.loop = quamash.QEventLoop(self.qtapp)
def tearDown(self):
[...]
# process any pending events before destroying the object
self.qtapp.processEvents()
# queue destroying the QApplication object, do that for any other QT
# related objects here too
self.qtapp.deleteLater()
# process any pending events (other than just queued destroy), just in case
self.qtapp.processEvents()
# execute main loop, which will process all events, _including just queued destroy_
self.loop.run_until_complete(asyncio.sleep(0))
# at this point it QT objects are destroyed, cleanup all remaining references;
# del other QT object here too
self.loop.close()

2
developer/debugging/safe-remote-ttys.rst
View file

@ -68,7 +68,7 @@ A note on serial consoles
If your machine has a serial console, you may with to use that, but note that a similar split-I/O model should be used to ensure Dom0 integrity. If you use the serial console as normal (via e.g. getty on ttyX, and logging in as normal), then the machine at the end of the serial cable could compromise your machine! Ideally, you would take input from your trusted keyboard, and only send the output over the serial cable via e.g. disabling getty and using:
.. code:: bash
.. code:: console
script -f /dev/ttyS0

70
developer/debugging/test-bench.rst
View file

@ -38,15 +38,15 @@ Internet access is intentionally disabled by default in dom0. But to ease the de
.. code:: bash
#!/bin/sh
# adjust this for your NIC (run lspci)
BDF=0000:02:00.0
# adjust this for your network driver
DRIVER=e1000e
prog=$(basename $0)
pciunbind() {
local path
path=/sys/bus/pci/devices/${1}/driver/unbind
@ -56,7 +56,7 @@ Internet access is intentionally disabled by default in dom0. But to ease the de
fi
echo -n ${1} >${path}
}
pcibind() {
local path
path=/sys/bus/pci/drivers/${2}/bind
@ -66,10 +66,10 @@ Internet access is intentionally disabled by default in dom0. But to ease the de
fi
echo ${1} >${path}
}
pciunbind ${BDF}
pcibind ${BDF} ${DRIVER}
sleep 1
dhclient
@ -78,15 +78,15 @@ Internet access is intentionally disabled by default in dom0. But to ease the de
6. You’ll need to run the above script on every startup. To automate this save the following systemd service ``/etc/systemd/system/dom0-network-direct.service``
.. code:: bash
.. code:: systemd
[Unit]
Description=Connect network to dom0
[Service]
Type=oneshot
ExecStart=/home/user/bin/dom0_network.sh
[Install]
WantedBy=multi-user.target
@ -94,11 +94,11 @@ Internet access is intentionally disabled by default in dom0. But to ease the de
7. Then, enable and start the SSH Server and the script on boot:
.. code:: bash
.. code:: console
sudo systemctl enable sshd
sudo systemctl start sshd
sudo systemctl enable dom0-network-direct
sudo systemctl start dom0-network-direct
@ -117,20 +117,20 @@ Because of the above reason, some additional configurations need to be done to y
The following commands should work for you, but do keep in mind that the provisioning scripts are designed for the `openQA environment <https://openqa.qubes-os.org/>`__ and not your specific local testing system. Run the following in ``dom0``:
.. code:: bash
.. code:: console
# For future reference the following commands are an adaptation of
# https://github.com/marmarek/openqa-tests-qubesos/blob/master/tests/update.pm
# Install git
sudo qubes-dom0-update git || sudo dnf --setopt=reposdir=/etc/yum.repos.d install git
# Download the openQA automated testing environment Salt configuration
git clone https://github.com/marmarek/openqa-tests-qubesos/
cd openqa-tests-qubesos/extra-files
sudo cp -a system-tests/ /srv/salt/
sudo qubesctl top.enable system-tests
# Install the same configuration as the one in openQA
QUBES_VERSION=4.1
PILLAR_DIR=/srv/pillar/base/update
@ -138,7 +138,7 @@ The following commands should work for you, but do keep in mind that the provisi
printf 'update:\n qubes_ver: '$QUBES_VERSION'\n' | sudo tee $PILLAR_DIR/init.sls
printf "base:\n '*':\n - update\n" | sudo tee $PILLAR_DIR/init.top
sudo qubesctl top.enable update pillar=True
# Apply states to dom0 and VMs
# NOTE: These commands can take several minutes (if not more) without showing output
sudo qubesctl --show-output state.highstate
@ -155,7 +155,7 @@ SSH
Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Generate SSH key in ``qubes-dev``:
.. code:: bash
.. code:: console
ssh-keygen -t ecdsa -b 521
@ -163,7 +163,7 @@ Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Gene
Add the following section in ``.ssh/config`` in ``qubes-dev``:
.. code:: bash
.. code:: text
Host testbench
# substitute username in testbench
@ -190,7 +190,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$
.. code:: bash
#!/bin/sh
ssh testbench python -m qubes.tests.run
@ -199,19 +199,19 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$
.. code:: bash
#!/bin/sh
TMPDIR=/tmp/qtb-rpms
if [ $# -eq 0 ]; then
echo "usage: $(basename $0) <rpmfile> ..."
exit 2
fi
set -e
ssh testbench mkdir -p "${TMPDIR}"
scp "${@}" testbench:"${TMPDIR}" || echo "check if you have 'scp' installed on your testbench"
while [ $# -gt 0 ]; do
ssh testbench sudo rpm -i --replacepkgs --replacefiles "${TMPDIR}/$(basename ${1})"
shift
@ -220,19 +220,19 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$
``qtb-iterate``:
.. code:: bash
.. code:: console
#!/bin/sh
set -e
# substitute path to your builder installation
pushd ${HOME}/builder >/dev/null
# the following are needed only if you have sources outside builder
#rm -rf qubes-src/core-admin
#qb -c core-admin package fetch
qb -c core-admin -d host-fc41 prep build
# update your dom0 fedora distribution as appropriate
qtb-install qubes-src/core-admin/rpm/x86_64/qubes-core-dom0-*.rpm
@ -247,20 +247,20 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked
``core-admin/.git/hooks/pre-commit``: (you may retain also the default hook, here omitted for readability)
.. code:: bash
.. code:: console
#!/bin/sh
set -e
python -c "import sys, qubes.tests.run; sys.exit(not qubes.tests.run.main())"
``core-admin/.git/hooks/pre-push``:
.. code:: bash
.. code:: console
#!/bin/sh
exec qtb-iterate

10
developer/debugging/windows-debugging.rst
View file

@ -45,9 +45,9 @@ You will need to create a custom libvirt config for the target VM. See `the docu
.. code:: bash
.. code:: xml+jinja
{% extends 'libvirt/xen.xml' %}
{% block network %}
<interface type='ethernet'>
@ -58,7 +58,7 @@ You will need to create a custom libvirt config for the target VM. See `the docu
<model type='e1000' />
</interface>
{% endblock %}
@ -98,7 +98,7 @@ Host and target preparation
- ``kdnet`` should show that the NIC is supported, note the busparams:
.. code:: bash
.. code:: text
Network debugging is supported on the following NICs:
busparams=0.6.0, Intel(R) PRO/1000 MT Network Connection, KDNET is running on this NIC.
@ -117,7 +117,7 @@ Host and target preparation
- Reboot ``target-vm``, debugging should start:
.. code:: bash
.. code:: text
Waiting to reconnect...
Connected to target 10.137.0.19 on port 50000 on local IP 10.137.0.20.

10
developer/general/developing-gui-applications.rst
View file

@ -20,19 +20,19 @@ For example, the following code can be used to run the ``qui-domains`` tool usin
# qapp = qubesadmin.Qubes()
# dispatcher = qubesadmin.events.EventsDispatcher(qapp)
# stats_dispatcher = qubesadmin.events.EventsDispatcher(qapp, api_method='admin.vm.Stats')
import qubesadmin.tests.mock_app as mock_app
qapp = mock_app.MockQubesComplete()
dispatcher = mock_app.MockDispatcher(qapp)
stats_dispatcher = mock_app.MockDispatcher(
qapp, api_method='admin.vm.Stats')
# continue as normal
To run a mocked program without installing it in a qube, remember to extend PYTHONPATH appropriately, for example:
.. code:: bash
.. code:: console
~/qubes-sources/manager $ PYTHONPATH=../core-admin-client:. python3 qui/tray/domains.py
@ -103,7 +103,7 @@ The same mock Qubes can also be used to write tests. You can use the wrappers ab
# this is an excerpt from tests for Qubes Global Config tool
clockvm_combo.set_active_id('test-blue')
mock_qapp.expected_calls[('dom0', 'admin.property.Set',
'clockvm', b'test-blue')] = b'0\x00'
basics_handler.save()
@ -114,4 +114,4 @@ If the call is made correctly, the test will continue successfully; if an unexpe
Caution: the mock Qubes object does not react to changes like a normal Qubes object does. Further queries to the test object will continue to return initial values.
.. |Qubes Manager running MockQubesComplete| image:: /attachment/doc/doc-mock-app-ex1.png

44
developer/general/gsoc.rst
View file

@ -49,34 +49,34 @@ A project proposal is what you will be judged upon. Write a clear proposal on wh
Below is the application template:
.. code:: bash
.. code:: markdown
# Introduction
Every software project should solve a problem. Before offering the solution (your Google Summer of Code project), you should first define the problem. What’s the current state of things? What’s the issue you wish to solve and why? Then you should conclude with a sentence or two about your solution. Include links to discussions, features, or bugs that describe the problem further if necessary.
# Project goals
Be short and to the point, and perhaps format it as a list. Propose a clear list of deliverables, explaining exactly what you promise to do and what you do not plan to do. “Future developments” can be mentioned, but your promise for the Google Summer of Code term is what counts.
# Implementation
Be detailed. Describe what you plan to do as a solution for the problem you defined above. Include technical details, showing that you understand the technology. Illustrate key technical elements of your proposed solution in reasonable detail.
# Timeline
Show that you understand the problem, have a solution, have also broken it down into manageable parts, and that you have a realistic plan on how to accomplish your goal. Here you set expectations, so don’t make promises you can’t keep. A modest, realistic and detailed timeline is better than promising the impossible.
If you have other commitments during GSoC, such as a job, vacation, exams, internship, seminars, or papers to write, disclose them here. GSoC should be treated like a full-time job, and we will expect approximately 40 hours of work per week. If you have conflicts, explain how you will work around them. If you are found to have conflicts which you did not disclose, you may be failed.
Open and clear communication is of utmost importance. Include your plans for communication in your proposal; daily if possible. You will need to initiate weekly formal communications such as a detailed email to the qubes-devel mailing list. Lack of communication will result in you being failed.
# About me
Provide your contact information and write a few sentences about you and why you think you are the best for this job. Prior contributions to Qubes are helpful; list your commits. Name people (other developers, students, professors) who can act as a reference for you. Mention your field of study if necessary. Now is the time to join the relevant mailing lists. We want you to be a part of our community, not just contribute your code.
Tell us if you are submitting proposals to other organizations, and whether or not you would choose Qubes if given the choice.
Other things to think about:
* Are you comfortable working independently under a supervisor or mentor who is several thousand miles away, and perhaps 12 time zones away? How will you work with your mentor to track your work? Have you worked in this style before?
* If your native language is not English, are you comfortable working closely with a supervisor whose native language is English? What is your native language, as that may help us find a mentor who has the same native language?
@ -90,23 +90,23 @@ Project Ideas
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` and associated GitHub issue to learn more about the idea.
.. code::
.. code:: markdown
### Adding a Proposal
**Project**: Something that you're totally excited about
**Brief explanation**: What is the project, where does the code live?
**Expected results**: What is the expected result in the timeframe given
**Difficulty**: easy / medium / hard
**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed?
If applicable, links to more information or discussions
**Size of the project**: either 175 hours (medium) or 350 hours (large)
**Mentor**: Name and email address.

6
developer/general/usability-ux.rst
View file

@ -153,7 +153,7 @@ By using the same term throughout an interface, a user can create a mental model
It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as:
.. code:: bash
.. code:: text
Menu
- Domain: work
@ -168,7 +168,7 @@ The repeated use of the word ``Domain`` requires a user to read it for each item
It is more efficient to group things under headings instead as this allows the eye to easily scan the uniqueness of the items. (As per our previous example:)
.. code:: bash
.. code:: text
Domains
- Work
@ -304,4 +304,4 @@ Learning to make well designing intuitive interfaces and software is specialized
.. |checkmark| image:: /attachment/doc/checkmark.png
.. |redx| image:: /attachment/doc/red_x.png
.. |redx| image:: /attachment/doc/red_x.png

4
developer/releases/1_0/release-notes.rst
View file

@ -17,7 +17,7 @@ Known issues
- On systems with more than 8GB of RAM there is problem with DisposableVM. To fix it, limit maximum memory allocation for DispVM to 3GB
.. code:: bash
.. code:: console
qvm-prefs -s fedora-17-x64-dvm maxmem 3072
qvm-create-default-dvm --default-template --default-script
@ -56,7 +56,7 @@ From Qubes 1.0 Beta 3
If you have Qubes Beta 3 currently installed on your system, you must reinstall from scratch, as we offer no direct upgrade option in the installer (sorry). However, we do offer tools for smooth migration of your AppVMs. In order to do that, please backup your AppVMs using the ``qvm-backup`` tool :doc:`as usual </user/how-to-guides/how-to-back-up-restore-and-migrate>`. Then, after you install Qubes 1.0 rc1, you can restore them using ``qvm-backup-restore`` tool. However, because we have changed the default template in RC1, you should tell qvm-back-restore about that by passing ``--replace-template`` option:
.. code:: bash
.. code:: console
qvm-backup-restore <backup_dir> --replace-template=fedora-15-x64:fedora-17-x64

8
developer/releases/4_0/release-notes.rst
View file

@ -64,7 +64,7 @@ Security Notes
3. In the window that opens, enter this command:
.. code:: bash
.. code:: console
sudo nano /etc/yum.repos.d/qubes-dom0.repo
@ -85,10 +85,10 @@ Security Notes
3. In the window that opens, enter the command for your version:
.. code:: bash
.. code:: console
[Qubes 3.2] sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] sudo gedit /etc/yum.repos.d/qubes-r4.repo
[Qubes 3.2] $ sudo gedit /etc/yum.repos.d/qubes-r3.repo
[Qubes 4.0] $ sudo gedit /etc/yum.repos.d/qubes-r4.repo

10
developer/releases/4_2/release-notes.rst
View file

@ -91,7 +91,7 @@ Notes
- Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change ``*`` in the argument column to ``+`` (i.e., change “any argument” to “only empty”). To use the more restrictive behavior globally, add the following “deny” rule before all other relevant rules:
.. code:: bash
.. code:: text
qubes.Filecopy +allow-all-names @anyvm @anyvm deny
@ -124,13 +124,13 @@ Upgrading
Please see :doc:`how to upgrade to Qubes 4.2 </user/downloading-installing-upgrading/upgrade/4_2>`.
.. |Screenshot of the Qubes OS Update tool| image:: /attachment/site/4-2_update.png
.. |Screenshot of the Qubes OS Global Config tool| image:: /attachment/site/4-2_global-config_1.png
.. |image1| image:: /attachment/site/4-2_global-config_2.png
.. |Screenshot of the Qubes OS Policy Editor tool| image:: /attachment/site/4-2_policy-editor.png

10
developer/services/qrexec-internals.rst
View file

@ -142,7 +142,7 @@ dom0: request execution of ``cmd`` in domX
- **dom0**: ``qrexec-client`` is invoked in **dom0** as follows:
.. code:: bash
.. code:: console
qrexec-client -d domX [-l local_program] user:cmd
@ -189,7 +189,7 @@ domX: request execution of service ``admin.Service`` in dom0
- **domX**: ``qrexec-client-vm`` is invoked as follows:
.. code:: bash
.. code:: console
qrexec-client-vm dom0 admin.Service [local_program] [params]
@ -215,7 +215,7 @@ domX: request execution of service ``admin.Service`` in dom0
- **dom0**: If the RPC is allowed, ``qrexec-policy`` will launch a ``qrexec-client`` with the right command:
.. code:: bash
.. code:: console
qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0"
@ -258,7 +258,7 @@ domX: invoke execution of qubes service ``qubes.Service`` in domY
- **domX**: ``qrexec-client-vm`` is invoked as follows:
.. code:: bash
.. code:: console
qrexec-client-vm domY qubes.Service [local_program] [params]
@ -276,7 +276,7 @@ domX: invoke execution of qubes service ``qubes.Service`` in domY
- **dom0**: If the RPC is allowed, ``qrexec-policy`` will launch a ``qrexec-client`` with the right command:
.. code:: bash
.. code:: console
qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX"

62
developer/services/qrexec-socket-services.rst
View file

@ -15,7 +15,7 @@ When a Qubes RPC service is invoked, qrexec searches for a file that handles it
Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after ``QUBESRPC``. When running in a VM, this is:
.. code:: bash
.. code:: text
<service_name> <source>\0
@ -23,7 +23,7 @@ Before passing user input, the socket service will receive a null-terminated ser
When running in dom0, it is:
.. code:: bash
.. code:: text
<service_name> <source> <target_type> <target>\0
@ -81,18 +81,18 @@ Systemd unit files
**/lib/systemd/user/qubes-qrexec-policy-agent.service**: This is the service configuration.
.. code:: bash
.. code:: systemd
[Unit]
Description=Qubes remote exec policy agent
ConditionUser=!root
ConditionGroup=qubes
Requires=qubes-qrexec-policy-agent.socket
[Service]
Type=simple
ExecStart=/usr/bin/qrexec-policy-agent
[Install]
WantedBy=default.target
@ -100,17 +100,17 @@ Systemd unit files
**/lib/systemd/user/qubes-qrexec-policy-agent.socket**: This is the socket file that will activate the service.
.. code:: bash
.. code:: systemd
[Unit]
Description=Qubes remote exec policy agent socket
ConditionUser=!root
ConditionGroup=qubes
PartOf=qubes-qrexec-policy-agent.service
[Socket]
ListenStream=/var/run/qubes/policy-agent.sock
[Install]
WantedBy=sockets.target
@ -120,7 +120,7 @@ Note the ``ConditionUser`` and ``ConditionGroup`` that ensure that the socket an
Start the socket using ``systemctl --user start``. Enable it using ``systemctl --user enable``, so that it starts automatically.
.. code:: bash
.. code:: console
systemctl --user start qubes-qrexec-policy-agent.socket
systemctl --user enable qubes-qrexec-policy-agent.socket
@ -129,7 +129,7 @@ Start the socket using ``systemctl --user start``. Enable it using ``systemctl -
Alternatively, you can enable the service by creating a symlink:
.. code:: bash
.. code:: console
sudo ln -s /lib/systemd/user/qubes-qrexec-policy-agent.socket /lib/systemd/user/sockets.target.wants/
@ -141,7 +141,7 @@ Link in qubes-rpc
``qrexec-policy-agent`` will handle a Qubes RPC service called ``policy.Ask``, so we add a link:
.. code:: bash
.. code:: console
sudo ln -s /var/run/qubes/policy-agent.sock /etc/qubes-rpc/policy.Ask
@ -155,7 +155,7 @@ Socket activation in systemd works by starting our program with the socket file
Install the Python systemd library:
.. code:: bash
.. code:: console
sudo dnf install python3-systemd
@ -168,20 +168,20 @@ Here is the server code:
import os
import asyncio
import socket
from systemd.daemon import listen_fds
class SocketService:
def __init__(self, socket_path, socket_activated=False):
self._socket_path = socket_path
self._socket_activated = socket_activated
async def run(self):
server = await self.start()
async with server:
await server.serve_forever()
async def start(self):
if self._socket_activated:
fds = listen_fds()
@ -191,41 +191,41 @@ Here is the server code:
sock = socket.socket(fileno=fds[0])
return await asyncio.start_unix_server(self._client_connected,
sock=sock)
if os.path.exists(self._socket_path):
os.unlink(self._socket_path)
return await asyncio.start_unix_server(self._client_connected,
path=self._socket_path)
async def _client_connected(self, reader, writer):
try:
data = await reader.read()
assert b'\0' in data, data
service_descriptor, data = data.split(b'\0', 1)
response = await self.handle_request(service_descriptor, data)
writer.write(response)
await writer.drain()
finally:
writer.close()
await writer.wait_closed()
async def handle_request(self, service_descriptor, data):
# process params, return response
return response
def main():
socket_path = '/var/run/qubes/policy-agent.sock'
service = SocketService(socket_path)
loop = asyncio.get_event_loop()
loop.run_until_complete(service.run())
if __name__ == '__main__':
main()
@ -238,7 +238,7 @@ Using the service
The service is invoked in the same way as a standard Qubes RPC service:
.. code:: bash
.. code:: console
echo <input_data> | qrexec-client -d domX 'DEFAULT:QUBESRPC policy.Ask'
@ -246,7 +246,7 @@ The service is invoked in the same way as a standard Qubes RPC service:
You can also connect to it locally, but remember to include the service descriptor:
.. code:: bash
.. code:: console
echo -e 'policy.Ask dom0\0<input data>' | nc -U /etc/qubes-rpc/policy.Ask

16
developer/services/qrexec.rst
View file

@ -67,7 +67,7 @@ Policy files
Policies are defined in lines with the following format:
.. code:: bash
.. code:: text
service-name|* +argument|* source destination action [options]
@ -131,7 +131,7 @@ There are severals methods for specifying source/target VMs in RPC policies.
Target VM can be also specified as ``@default``, which matches the case when calling VM didn’t specified any particular target (either by using ``@default`` target, or empty target). For DisposableVMs, ``@dispvm:DISP_VM`` is very similar to ``@dispvm`` but forces using a particular VM (``DISP_VM``) as a base VM to be started as DisposableVM. For example:
.. code:: bash
.. code:: text
* * anon-whonix @dispvm:anon-whonix-dvm allow
@ -139,7 +139,7 @@ Target VM can be also specified as ``@default``, which matches the case when cal
Adding such policy itself will not force usage of this particular ``DISP_VM`` - it will only allow it when specified by the caller. But ``@dispvm:DISP_VM`` can also be used as target in request redirection, so *it is possible* to force particular ``DISP_VM`` usage, when caller didn’t specify it:
.. code:: bash
.. code:: text
* * anon-whonix @dispvm allow target=@dispvm:anon-whonix-dvm
@ -149,7 +149,7 @@ Note that without redirection, this rule would allow using default Disposable VM
The policy confirmation dialog (``ask`` action) allows the user to specify target VM. User can choose from VMs that, according to policy, would lead to ``ask`` or ``allow`` actions. It is not possible to select VM that policy would deny. By default no VM is selected, even if the caller provided some, but policy can specify default value using ``default_target=`` parameter. For example:
.. code:: bash
.. code:: text
* * work-mail work-archive allow
* * work-mail @tag:work ask default_target=work-files
@ -193,7 +193,7 @@ For this reason it is possible to specify a service argument, which will be subj
The argument is specified in the second column of the policy line, as +ARGUMENT. If the policy uses “*” as an argument, then it will match any argument (including no argument). As rules are processed in order, any lines with a specific argument below the line with the wildcard argument will be ignored. So for instance, we might have policies which are different depending on the argument:
.. code:: bash
.. code:: text
Device +device1 * * allow
Device +device2 * * deny
@ -245,7 +245,7 @@ Our server will be anotherVM at ``/usr/bin/our_test_add_server``. The code for t
We’ll need to create a service called ``test.Add`` with its own definition and policy file in dom0. Now we need to define what the service does. In this case, it should call our addition script. We define the service with a symlink at ``/etc/qubes-rpc/test.Add`` pointing to our server script (the script can be also placed directly in ``/etc/qubes-rpc/test.Add`` - make sure the file has executable bit set!):
.. code:: bash
.. code:: console
ln -s /usr/bin/our_test_add_server /etc/qubes-rpc/test.Add
@ -253,7 +253,7 @@ We’ll need to create a service called ``test.Add`` with its own definition and
The administrative domain will direct traffic based on the current RPC policies. In dom0, create a file at ``/etc/qubes/policy.d/30-test.policy`` containing the following:
.. code:: bash
.. code:: text
test.Add * * * ask
@ -299,7 +299,7 @@ Make sure the file is executable! (The service argument is already sanitized by
Now we create the policy file in dom0, at ``/etc/qubes/policy.d/30-test.policy``. The contents of the file are below. Replace “source_vm1” and others with the names of your own chosen domains.
.. code:: bash
.. code:: text
test.File +testfile1 source_vm1 target_vm allow
test.File +testfile2 source_vm2 target_vm allow

14
developer/services/qrexec2.rst
View file

@ -54,7 +54,7 @@ Besides each VM needing to provide explicit programs to serve each supported ser
In dom0, there is a bunch of files in ``/etc/qubes-rpc/policy/`` directory, whose names describe the available RPC actions; their content is the RPC access policy database. Some example of the default services in Qubes are:
.. code:: bash
.. code:: text
qubes.Filecopy
qubes.OpenInVM
@ -70,7 +70,7 @@ In dom0, there is a bunch of files in ``/etc/qubes-rpc/policy/`` directory, whos
These files contain lines with the following format:
.. code:: bash
.. code:: text
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
@ -88,7 +88,7 @@ Requesting VM-VM (and VM-Dom0) services execution
In a src VM, one should invoke the qrexec client via the following command:
.. code:: bash
.. code:: console
/usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]
@ -112,7 +112,7 @@ Qubes RPC policy supports an “ask” action, that will prompt the user whether
In order to remove such authorization, issue this command from a Dom0 terminal (example below for ``qubes.Filecopy`` service):
.. code:: bash
.. code:: console
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
@ -147,14 +147,14 @@ We will show the necessary files to create a simple RPC call that adds two integ
- Policy file in dom0 (``/etc/qubes-rpc/policy/test.Add``)
.. code::
.. code:: text
$anyvm $anyvm ask
- Server path definition on target VM (``/etc/qubes-rpc/test.Add``)
.. code:: bash
.. code:: text
/usr/bin/our_test_add_server
@ -162,7 +162,7 @@ We will show the necessary files to create a simple RPC call that adds two integ
- To test this service, run the following in the source VM:
.. code:: bash
.. code:: console
/usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2

16
developer/system/networking.rst
View file

@ -17,8 +17,8 @@ Routing tables examples
VM routing table is simple:
.. list-table::
:widths: 4 4 4 4 4 4 4 4
.. list-table::
:widths: 4 4 4 4 4 4 4 4
:align: center
:header-rows: 1
@ -38,12 +38,12 @@ VM routing table is simple:
- 0
- 0
- eth0
Network driver domain routing table is a bit longer:
.. list-table::
:widths: 1 1 1 1 1 1 1 1
.. list-table::
:widths: 1 1 1 1 1 1 1 1
:align: center
:header-rows: 1
@ -111,7 +111,7 @@ Network driver domain routing table is a bit longer:
- 0
- 0
- eth0
IPv6
----
@ -119,7 +119,7 @@ IPv6
Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to the IPv4, traffic is routed and NAT is applied at each network gateway. This way we avoid reconfiguring every connected qube whenever uplink connection is changed, and even telling the qube what that uplink is - which may be complex when VPN or other tunneling services are employed. The feature can be enabled on any network-providing qube, and will be propagated down the network tree, so every qube connected to it will also have IPv6 enabled. To enable the ``ipv6`` feature use ``qvm-features`` tool and set the value to ``1``. For example to enable it on ``sys-net``, execute in dom0:
.. code:: bash
.. code:: console
qvm-features sys-net ipv6 1
@ -127,7 +127,7 @@ Starting with Qubes 4.0, there is opt-in support for IPv6 forwarding. Similar to
It is also possible to explicitly disable IPv6 support for some qubes, even if it is connected to IPv6-providing one. This can be done by setting ``ipv6`` feature to empty value:
.. code:: bash
.. code:: console
qvm-features ipv4-only-qube ipv6 ''

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

@ -247,7 +247,7 @@ Input
Both calls accept the following format from standard input:
.. code:: bash
.. code:: text
arg1
arg2

6
developer/system/vm-sudo.rst
View file

@ -9,11 +9,11 @@ This page sets out the configuration changes made, with (not necessary complete)
1. sudo (``/etc/sudoers.d/qubes``):
.. code:: bash
.. code:: text
Defaults !requiretty
%qubes ALL=(ALL) ROLE=unconfined_r TYPE=unconfined_t NOPASSWD: ALL
(...)
@ -26,7 +26,7 @@ This page sets out the configuration changes made, with (not necessary complete)
2. PolicyKit (``/etc/polkit-1/rules.d/00-qubes-allow-all.rules``):
.. code:: bash
.. code:: text
//allow any action, detailed reasoning in sudoers.d/qubes
polkit.addRule(function(action,subject) { if (subject.isInGroup("qubes")) return polkit.Result.YES; });