diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst index 64e546d8..5dbffc41 100644 --- a/developer/building/development-workflow.rst +++ b/developer/building/development-workflow.rst @@ -17,7 +17,7 @@ The best way to write and contribute code is to create a git repo somewhere (e.g **Example:** -.. code:: bash +.. code:: console $ cd qubes-builder/artifacts/sources/qubes-manager $ git remote add abel git@GitHub.com:abeluck/qubes-manager.git @@ -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-/linux-: -.. 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 @@ -290,7 +285,7 @@ You will also need to setup qrexec policy in dom0 (``/etc/qubes-rpc/policy/local Usage: -.. code:: bash +.. code:: console [user@source core-agent-linux]$ git remote add testbuilder "ext::git-qrexec testbuilder 3 core-agent-linux" [user@source core-agent-linux]$ git push testbuilder master @@ -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 `__ 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 `__ re In target VM, setup actual yum repository (also based on `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 "; 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 diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst index c9a23de7..1fc607a5 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/developer/building/qubes-builder-v2.rst @@ -31,7 +31,7 @@ This is a simple setup using a docker executor. This is a good default choice; i - .. code:: bash + .. code:: console $ sudo dnf install $(cat dependencies-fedora.txt) $ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split @@ -43,7 +43,7 @@ This is a simple setup using a docker executor. This is a good default choice; i - .. code:: bash + .. code:: console $ sudo apt install $(cat dependencies-debian.txt) $ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split @@ -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/ @@ -60,7 +60,7 @@ This is a simple setup using a docker executor. This is a good default choice; i 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: - .. code:: bash + .. code:: console $ sudo usermod -aG docker user @@ -68,7 +68,7 @@ This is a simple setup using a docker executor. This is a good default choice; i 5. Finally, you need to generate a docker image: - .. code:: bash + .. code:: console $ tools/generate-container-image.sh docker @@ -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 @@ -124,7 +124,7 @@ Using Builder v2 To fetch sources - in this example, for the ``core-admin-client`` package, you can use the following command: -.. code:: bash +.. code:: console $ ./qb -c core-admin-client package fetch @@ -133,21 +133,21 @@ This will fetch the sources for the listed package and place them in ``artifacts To build a package (from sources in the ``artifacts/sources`` directory), use: -.. code:: bash +.. code:: console $ ./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: -.. code:: bash +.. code:: console $ ./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: -.. code:: bash +.. code:: console $ ./qb package fetch diff --git a/developer/building/qubes-builder.rst b/developer/building/qubes-builder.rst index 02d815dc..336bb304 100644 --- a/developer/building/qubes-builder.rst +++ b/developer/building/qubes-builder.rst @@ -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 `__ . This can be used for building Qubes R4.2 and later, and all related components. **Note: See** :doc:`ISO building instructions ` **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 diff --git a/developer/building/qubes-iso-building.rst b/developer/building/qubes-iso-building.rst index d733d3ab..f14523e4 100644 --- a/developer/building/qubes-iso-building.rst +++ b/developer/building/qubes-iso-building.rst @@ -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 `__ . 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 @@ -32,7 +32,7 @@ Create a standalone AppVM from the Fedora template. Set private storage to at le Once you’ve built the development AppVM, open a Terminal window to it and install the necessary dependencies (see :doc:`QubesBuilder ` for more info): -.. code:: bash +.. code:: console $ sudo dnf install git createrepo rpm-build rpm-sign make python3-sh rpmdevtools rpm-sign dialog perl-open python3-pyyaml perl-Digest-MD5 perl-Digest-SHA @@ -40,17 +40,23 @@ 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 + +.. code:: output - 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 + +.. code:: console + + $ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc + $ gpg --import qubes-developers-keys.asc @@ -58,7 +64,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,10 +82,13 @@ Build using setup script Let’s configure the builder first (see :ref:`procedure ` at bottom if you would prefer to manually configure): -.. code:: bash +.. code:: console + + $ cd ~/qubes-builder + $ ./setup + +.. code:: output - 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 @@ -96,9 +105,12 @@ Let’s configure the builder first (see :ref:`procedure `__, etc. It should look something like this: -.. code:: bash +.. code:: output pub rsa4096 2014-01-16 [SC] [expires: 2026-01-23] Key fingerprint = 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA @@ -171,7 +183,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 +195,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 +206,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 +218,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 +227,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 diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst index b27d91d9..0c585214 100644 --- a/developer/code/code-signing.rst +++ b/developer/code/code-signing.rst @@ -13,32 +13,32 @@ Generating a Key Alex Cabal has written an excellent `guide `__ on creating a PGP keypair. Below, we reproduce just the minimum steps in generating a keypair using GnuPG. Please read Cabal’s full guide for further important details. -.. code:: bash +.. code:: console $ gpg --gen-key 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 " - + 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. - + - + 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 @@ -68,14 +68,14 @@ 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:: output pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30] 87975838063F97A968D503266E2F4E7AF50A5827 -.. code:: bash +.. code:: console $ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827 gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com @@ -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 @@ -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 -m "" 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 git spush diff --git a/developer/code/source-code.rst b/developer/code/source-code.rst index 7765a2fc..34db1952 100644 --- a/developer/code/source-code.rst +++ b/developer/code/source-code.rst @@ -19,7 +19,7 @@ All of our repositories are available under the `QubesOS GitHub account .git @@ -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 \; diff --git a/developer/debugging/automated-tests.rst b/developer/debugging/automated-tests.rst index 3240fca9..2e9ed06c 100644 --- a/developer/debugging/automated-tests.rst +++ b/developer/debugging/automated-tests.rst @@ -39,18 +39,18 @@ Our test runner runs mostly the same as the standard one, but it has some nice a You can use ``python3 -m qubes.tests.run -h`` to get usage information: -.. code:: bash +.. code:: console [user@dom0 ~]$ python3 -m qubes.tests.run -h usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] [--do-not-clean] [--do-clean] [--loglevel LEVEL] [--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 @@ -82,7 +82,7 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information: For instance, to run only the tests for the fedora-21 template, you can use the ``-l`` option, then filter the list: -.. code:: bash +.. code:: console [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 network/VmNetworking_fedora-21/test_000_simple_networking @@ -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() diff --git a/developer/debugging/mount-lvm-image.rst b/developer/debugging/mount-lvm-image.rst index 5b90ba3d..dbc19b61 100644 --- a/developer/debugging/mount-lvm-image.rst +++ b/developer/debugging/mount-lvm-image.rst @@ -7,7 +7,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 1: make the image available for qubesdb. From dom0 terminal: -.. code:: bash +.. code:: console # Example: /dev/qubes_dom0/vm-debian-9-tmp-root [user@dom0]$ dev=$(basename $(readlink /dev/YOUR_LVM_VG/YOUR_LVM_IMAGE)) @@ -16,7 +16,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 2: Create a new disposable VM -.. code:: bash +.. code:: console [user@dom0]$ qvm-run -v --dispvm=YOUR_DVM_TEMPLATE --service qubes.StartApp+xterm & @@ -25,28 +25,28 @@ You want to read your LVM image (e.g., there is a problem where you can’t star From the GUI, or from the command line: -.. code:: bash +.. code:: console [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev 4: Mount the partition you want to, and do what you want with it -.. code:: bash +.. code:: console [user@dispXXXX]$ mount /dev/xvdiX /mnt/ 5: Umount and kill the VM -.. code:: bash +.. code:: console [user@dispXXXX]$ umount /mnt/ 6: Remove the image from qubesdb -.. code:: bash +.. code:: console [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst index a5afedff..4ef4918f 100644 --- a/developer/debugging/safe-remote-ttys.rst +++ b/developer/debugging/safe-remote-ttys.rst @@ -17,7 +17,7 @@ To a different VM As an example of forwarding terminal output to another VM on the same machine: -.. code:: bash +.. code:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' /dev/null 2>&1 & @@ -31,7 +31,7 @@ To a different machine In this case over SSH (from a network-connected VM): -.. code:: bash +.. code:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm \ @@ -55,7 +55,7 @@ Terminal size It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs). Depending on your shell, the size of your local (blind) terminal is likely stored in the ``$LINES`` and ``$COLUMNS`` variables. -.. code:: bash +.. code:: console $ echo $COLUMNS $LINES 80 24 @@ -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 diff --git a/developer/debugging/test-bench.rst b/developer/debugging/test-bench.rst index 18f71adb..d71ea117 100644 --- a/developer/debugging/test-bench.rst +++ b/developer/debugging/test-bench.rst @@ -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 `__ 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) ..." 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 diff --git a/developer/debugging/windows-debugging.rst b/developer/debugging/windows-debugging.rst index dc6b474f..ce219540 100644 --- a/developer/debugging/windows-debugging.rst +++ b/developer/debugging/windows-debugging.rst @@ -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 %} @@ -58,7 +58,7 @@ You will need to create a custom libvirt config for the target VM. See `the docu {% 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. diff --git a/developer/general/developing-gui-applications.rst b/developer/general/developing-gui-applications.rst index 81a7e256..4eb42d60 100644 --- a/developer/general/developing-gui-applications.rst +++ b/developer/general/developing-gui-applications.rst @@ -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 - + diff --git a/developer/general/gsoc.rst b/developer/general/gsoc.rst index c1b0a866..a74ee666 100644 --- a/developer/general/gsoc.rst +++ b/developer/general/gsoc.rst @@ -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 ` 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. diff --git a/developer/general/usability-ux.rst b/developer/general/usability-ux.rst index da9baacf..593de59b 100644 --- a/developer/general/usability-ux.rst +++ b/developer/general/usability-ux.rst @@ -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 \ No newline at end of file +.. |redx| image:: /attachment/doc/red_x.png diff --git a/developer/releases/1_0/release-notes.rst b/developer/releases/1_0/release-notes.rst index 91510ff9..ec040aca 100644 --- a/developer/releases/1_0/release-notes.rst +++ b/developer/releases/1_0/release-notes.rst @@ -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 `. 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 --replace-template=fedora-15-x64:fedora-17-x64 diff --git a/developer/releases/4_0/release-notes.rst b/developer/releases/4_0/release-notes.rst index 95e82452..dbedb6d7 100644 --- a/developer/releases/4_0/release-notes.rst +++ b/developer/releases/4_0/release-notes.rst @@ -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 diff --git a/developer/releases/4_2/release-notes.rst b/developer/releases/4_2/release-notes.rst index 982d7944..bb2dfe6c 100644 --- a/developer/releases/4_2/release-notes.rst +++ b/developer/releases/4_2/release-notes.rst @@ -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 `. .. |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 - + diff --git a/developer/services/qrexec-internals.rst b/developer/services/qrexec-internals.rst index 2cd58588..4bc4bf46 100644 --- a/developer/services/qrexec-internals.rst +++ b/developer/services/qrexec-internals.rst @@ -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" diff --git a/developer/services/qrexec-socket-services.rst b/developer/services/qrexec-socket-services.rst index 3af3d6b4..772b03b8 100644 --- a/developer/services/qrexec-socket-services.rst +++ b/developer/services/qrexec-socket-services.rst @@ -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 \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 \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 | 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' | nc -U /etc/qubes-rpc/policy.Ask diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst index 0ae67f06..ff0c1b3c 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -20,7 +20,7 @@ Qrexec is built on top of *vchan*, a Xen library providing data links between VM The ``qrexec-client`` command is used to make connections to VMs from dom0. For example, the following command creates an empty file called ``hello-world.txt`` in the home folder of ``someVM``: -.. code:: bash +.. code:: console $ qrexec-client -e -d someVM user:'touch hello-world.txt' @@ -28,7 +28,7 @@ The ``qrexec-client`` command is used to make connections to VMs from dom0. For The string before the colon specifies which user will run the command. The ``-e`` flag tells ``qrexec-client`` to exit immediately after sending the execution request and receiving a status code from ``qrexec-agent`` (if the process creation succeeded). With this option, no further data is passed between the domains. The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell): -.. code:: bash +.. code:: console $ qrexec-client -d someVM user:bash @@ -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] @@ -85,7 +85,7 @@ Making an RPC call From outside of dom0, RPC calls take the following form: -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME rpc_client_path client arguments @@ -93,7 +93,7 @@ From outside of dom0, RPC calls take the following form: For example: -.. code:: bash +.. code:: console $ qrexec-client-vm work qubes.StartApp+firefox @@ -103,7 +103,7 @@ Note that only stdin/stdout is passed between RPC server and client – notably, It is also possible to call service without specific client program – in which case server stdin/out will be connected with the terminal: -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME @@ -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 @@ -167,7 +167,7 @@ Be very careful when coding and adding a new RPC service. Unless the offered fun For example, this command will run the ``firefox`` command in a DisposableVM based on ``work``: -.. code:: bash +.. code:: console $ qvm-run --dispvm=work firefox @@ -175,7 +175,7 @@ For example, this command will run the ``firefox`` command in a DisposableVM bas By contrast, consider this command: -.. code:: bash +.. code:: console $ qvm-run --dispvm=work --service qubes.StartApp+firefox @@ -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 @@ -203,7 +203,7 @@ The argument is specified in the second column of the policy line, as +ARGUMENT. When calling a service that takes an argument, just add the argument to the service name separated with ``+``. -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME+ARGUMENT @@ -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 @@ -263,7 +263,7 @@ This will allow our client and server to communicate. Before we make the call, ensure that the client and server scripts have executable permissions. Finally, invoke the RPC service. -.. code:: bash +.. code:: console $ qrexec-client-vm anotherVM test.Add /usr/bin/our_test_add_client 1 2 @@ -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 @@ -309,7 +309,7 @@ Now we create the policy file in dom0, at ``/etc/qubes/policy.d/30-test.policy`` With this done, we can run some tests. Invoke RPC from ``source_vm1`` via -.. code:: bash +.. code:: console [user@source_vm1] $ qrexec-client-vm target_vm test.File+testfile1 @@ -317,7 +317,7 @@ With this done, we can run some tests. Invoke RPC from ``source_vm1`` via We should get the contents of ``/home/user/testfile1`` printed to the terminal. Invoking the service from ``source_vm2`` should result in a denial, but ``testfile2`` should work. -.. code:: bash +.. code:: console [user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile1 Request refused diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst index 3ebc66e2..c6961b2c 100644 --- a/developer/services/qrexec2.rst +++ b/developer/services/qrexec2.rst @@ -17,7 +17,7 @@ Typically, the first thing that a ``qrexec-client`` instance does is to send a r E.g., to start a primitive shell in a VM type the following in Dom0 console: -.. code:: bash +.. code:: console [user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d user:bash @@ -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 [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:: bash + .. 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 test.Add /usr/bin/our_test_add_client 1 2 diff --git a/developer/system/networking.rst b/developer/system/networking.rst index 3e66b332..f8bee84b 100644 --- a/developer/system/networking.rst +++ b/developer/system/networking.rst @@ -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 '' diff --git a/developer/system/template-manager.rst b/developer/system/template-manager.rst index 45b731fb..aad21181 100644 --- a/developer/system/template-manager.rst +++ b/developer/system/template-manager.rst @@ -247,7 +247,7 @@ Input Both calls accept the following format from standard input: -.. code:: bash +.. code:: text arg1 arg2 diff --git a/developer/system/vm-sudo.rst b/developer/system/vm-sudo.rst index 023612a9..e8a41289 100644 --- a/developer/system/vm-sudo.rst +++ b/developer/system/vm-sudo.rst @@ -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; }); diff --git a/introduction/faq.rst b/introduction/faq.rst index 2bb0ca44..c304b1d4 100644 --- a/introduction/faq.rst +++ b/introduction/faq.rst @@ -231,8 +231,8 @@ Which virtualization modes do VMs use? Here is an overview of the VM virtualization modes: -.. list-table:: - :widths: 42 42 +.. list-table:: + :widths: 42 42 :align: center :header-rows: 1 @@ -248,7 +248,7 @@ Here is an overview of the VM virtualization modes: - PV * - Stub domains - HVMs - PV - + What's so special about Qubes' GUI virtualization? @@ -543,7 +543,7 @@ or - Go to the sysfs (``/sys/bus/pci``), find the right device, detach it from the pciback driver and attach back to the original driver. Replace ```` with your device, for example ``00:1c.2``: - .. code:: bash + .. code:: console echo 0000: > /sys/bus/pci/drivers/pciback/unbind MODALIAS=`cat /sys/bus/pci/devices/0000:/modalias` @@ -570,7 +570,7 @@ For Debian: - .. code:: bash + .. code:: console $ sudo apt install vlc @@ -589,7 +589,7 @@ For Fedora: - .. code:: bash + .. code:: console $ sudo dnf install vlc @@ -672,7 +672,7 @@ I see a screen popup with SeaBios and 4 lines, last one being ``Probing EDD (edd From a ``dom0`` prompt, enter: -.. code:: bash +.. code:: console qvm-prefs kernel "" @@ -696,7 +696,7 @@ I see a "Failed to start Load Kernel Modules" message on boot The full message looks like: -.. code:: bash +.. code:: text [FAILED] Failed to start Load Kernel Modules. See 'systemctl status systemd-modules-load.service' for details. @@ -834,4 +834,4 @@ Is there a way to automate tasks for continuous integration or DevOps? Yes, Qubes natively supports automation via :doc:`Salt (SaltStack) `. There is also the unofficial `ansible-qubes toolkit `__. (**Warning:** Since this is an external project that has not been reviewed or endorsed by the Qubes team, `allowing it to manage dom0 may be a security risk `__.) .. |checkmark| image:: /attachment/doc/checkmark.png -.. |redx| image:: /attachment/doc/red_x.png \ No newline at end of file +.. |redx| image:: /attachment/doc/red_x.png diff --git a/introduction/issue-tracking.rst b/introduction/issue-tracking.rst index b5be6ff8..026f25c3 100644 --- a/introduction/issue-tracking.rst +++ b/introduction/issue-tracking.rst @@ -207,13 +207,13 @@ Use collapsible sections for long, nonessential content On GitHub, create collapsible sections in Markdown like so: -.. code:: bash +.. code:: html
Summary goes here. This line is optional. - + Long, nonessential content goes here. You can put a code block here, but make sure to leave empty lines before and after the fence lines (```). - +
diff --git a/introduction/statistics.rst b/introduction/statistics.rst index e95bcd55..867ea855 100644 --- a/introduction/statistics.rst +++ b/introduction/statistics.rst @@ -36,7 +36,7 @@ How are Tor users counted? We estimate the number of Tor users as a proportion of the total number of *requests* from Tor exit nodes on the assumption that the proportion of users to requests is roughly the same for both clearnet and Tor users. To be precise, the formula is: -.. code:: bash +.. code:: text tor_users = tor_requests * (plain_users / plain_requests) diff --git a/project-security/security-pack.rst b/project-security/security-pack.rst index d62a86e6..48577c54 100644 --- a/project-security/security-pack.rst +++ b/project-security/security-pack.rst @@ -79,7 +79,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 4. Verify signed Git tags. - .. code:: bash + .. code:: console $ cd qubes-secpack/ $ git tag -v `git describe` @@ -87,7 +87,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and type commit tag joanna_sec_2bb7f0b9 tagger Joanna Rutkowska 1468335706 +0000 - + Tag for commit 2bb7f0b966593d8ed74e140a04d60c68b96b164e gpg: Signature made 2016-07-12T08:01:46 PDT gpg: using RSA key 0x4E6829BC92C7B3DC @@ -97,7 +97,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 5. Verify detached PGP signatures. - .. code:: bash + .. code:: console $ cd canaries/ $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt @@ -129,91 +129,91 @@ History and rationale On 2013-01-05, Joanna Rutkowska announced the qubes-secpack and explained its rationale in an `email `__ to the Qubes mailing lists: -.. code:: bash +.. code:: console Hello, - + A new Qubes Security Bulletin has been just released and is available here: - + https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-013-2015.txt - + As per the previous discussions about recent problems with verifying digital signatures on messages sent to Google Groups (thanks to automatic footer addition by Google), we have decided to change the way we publish Qubes Security Bulletins, as well as other security-related info pertinent to the Qubes Project. - + Starting today, we will be maintain a Git repository -- "Qubes Security Pack" -- which will contain all the QSBs released so far, all the keys, warrant canaries [1], and potentially some additional info or announcements (e.g. key revocations). The whole repo can be found here: - + https://github.com/QubesOS/qubes-secpack - + Note that all the keys distributed there should be signed by Qubes Master Key. The Master Key is also attached in the repo, but should really be obtained/verified using a different channel. - + Additionally, most of the files are signed by core Qubes developers (currently by Marek and myself) via detached signatures as well as git tag signatures. - + The are several advantages of using Git to distribute all these information: - + 1) Git repo is a collection of files, some of which can be detached GPG signatures for other files and we can ensure all these files are distributed together. - + 2) Git makes it easy for people to clone and redistribute these collection of files, as well as to easily host them and view on the Web. - + 3) Git provides for signed tags mechanisms which is another mean we utilize to ensure integrity of the distributed files. - + A few words about the Warrant Canary which we've just introduced today, and which can be seen here: - + https://github.com/QubesOS/qubes-secpack/blob/master/canaries/canary-001-2015.txt - + Even though we're not providing any kind of services (such as e.g. email hosting), that could be searched or tapped by authorities, there are other possibilities that worry us [2], in the light of various recent law "developments", such as those that might be coercing people to hand over their private keys to authorities. - + Until we fully decentralize the root of trust for Qubes, something that requires the move to deterministic builds [3], and so won't happen very soon, the possibility of having to disclose any of the Qubes signing keys to anybody might have pretty serious consequences for those who decided to entrust Qubes with anything serious. And we would like to somehow minimize these consequences with this canary thing. - + Additionally the canary is a nice way of ensuring "freshness" of our messaging to the community. - + Of course the canary doesn't solve all the problems. E.g. if my signing keys were somehow stolen without our knowledge, it wouldn't help. Neither it could help in case me being or becoming a miscreant. And probably it doesn't address many other potential problems, which could only be solved one day with a multi-signature scheme. But anyway, until that time, this is the best we can do, I think. - + And congrats to Jann for the very interesting clipboard attack (even though mostly theoretical, still very cool)! - + Thanks, joanna. - + -- The Qubes Security Team https://www.qubes-os.org/doc/SecurityPage - - + + [1] http://en.wikipedia.org/wiki/Warrant_canary - + [2] Especially myself, because I'm currently the Root Of Trust for all Qubes binaries :/ - + [3] Deterministic builds are required because it's the only way we can implement multiple signature scheme for distributed binaries. diff --git a/project-security/security.rst b/project-security/security.rst index 4d6b65df..ae2e6d98 100644 --- a/project-security/security.rst +++ b/project-security/security.rst @@ -26,12 +26,12 @@ Reporting security issues in Qubes OS .. warning:: - + **Please note:** The Qubes security team email address is intended for **responsible disclosure** by security researchers and others who discover legitimate security vulnerabilities. It is **not** intended for everyone who suspects they’ve been hacked. Please do not attempt to contact the Qubes security team unless you can **demonstrate** an actual security vulnerability or unless the team will be able to take reasonable steps to verify your claims. If you’ve discovered a security issue affecting Qubes OS, either directly or indirectly (e.g., the issue affects Xen in a configuration that is used in Qubes OS), then we would be more than happy to hear from you! We promise to take all reported issues seriously. If our investigation confirms that an issue affects Qubes, we will patch it within a reasonable time and release a public `Qubes security bulletin (QSB) `__ that describes the issue, discusses the potential impact of the vulnerability, references applicable patches or workarounds, and credits the discoverer. Please use the `Qubes security team PGP key `__ to encrypt your email to this address: -.. code:: bash +.. code:: console security at qubes-os dot org diff --git a/project-security/verifying-signatures.rst b/project-security/verifying-signatures.rst index 49bfd49d..bdc88028 100644 --- a/project-security/verifying-signatures.rst +++ b/project-security/verifying-signatures.rst @@ -51,14 +51,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to - If you’re on Qubes OS, it’s available in every qube (`except dom0 `__): - .. code:: bash + .. code:: console $ gpg2 --import /usr/share/qubes/qubes-master-key.asc - If you’re on Fedora, you can get it in the `distribution-gpg-keys `__ package: - .. code:: bash + .. code:: console $ dnf install distribution-gpg-keys $ gpg2 --import /usr/share/distribution-gpg-keys/qubes/* @@ -68,14 +68,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to - Fetch it with GPG: - .. code:: bash + .. code:: console $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc - Get it from a public `keyserver `__ (specified on first use with ``--keyserver `` along with keyserver options to include key signatures), e.g.: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://keyserver.ubuntu.com --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 @@ -94,7 +94,7 @@ Once you have appropriate OpenPGP software installed, there are several ways to Once you have the key as a file, import it: - .. code:: bash + .. code:: console $ gpg2 --import //qubes-master-signing-key.asc @@ -107,7 +107,7 @@ So, what *should* you do? One option is to use the PGP `Web of Trust fpr pub 4096R/36879494 2010-04-01 Qubes Master Signing Key Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 - + gpg> trust pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC trust: unknown validity: unknown [ unknown] (1). Qubes Master Signing Key - + Please decide how far you trust this user to correctly verify other users' keys (by looking at passports, checking fingerprints from different sources, etc.) - + 1 = I don't know or won't say 2 = I do NOT trust 3 = I trust marginally 4 = I trust fully 5 = I trust ultimately m = back to the main menu - + Your decision? 5 Do you really want to set this key to ultimate trust? (y/N) y - + pub 4096R/36879494 created: 2010-04-01 expires: never usage: SC trust: ultimate validity: unknown [ unknown] (1). Qubes Master Signing Key Please note that the shown key validity is not necessarily correct unless you restart the program. - + gpg> q @@ -213,7 +213,7 @@ Now, when you import any of the release signing keys and many Qubes team member As a final sanity check, make sure the QMSK is in your keyring with the correct trust level. -.. code:: bash +.. code:: console $ gpg2 -k "Qubes Master Signing Key" pub rsa4096 2010-04-01 [SC] @@ -242,21 +242,21 @@ After you have completed these two prerequisite steps, the next step is to obtai - If you have access to an existing Qubes installation, the release keys are available in dom0 in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. These can be :ref:`copied ` into other qubes for further use. In addition, every other qube contains the release key corresponding to that installation’s release in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. If you wish to use one of these keys, make sure to import it into your keyring, e.g.: - .. code:: bash + .. code:: console $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-* - Fetch it with GPG: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc - Download it as a file. You can find the RSK for your Qubes release on the `downloads `__ page. You can also download all the currently used developers’ signing keys, RSKs, and the Qubes Master Signing Key from the :doc:`Qubes security pack ` and the `Qubes keyserver `__. Once you’ve downloaded your RSK, import it with GPG: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc @@ -265,7 +265,7 @@ After you have completed these two prerequisite steps, the next step is to obtai Now that you have the correct RSK, you simply need to verify that it is signed by the QMSK: -.. code:: bash +.. code:: console $ gpg2 --check-signatures "Qubes OS Release X Signing Key" pub rsa4096 YYYY-MM-DD [SC] @@ -273,7 +273,7 @@ Now that you have the correct RSK, you simply need to verify that it is signed b uid [ full ] Qubes OS Release X Signing Key sig!3 XXXXXXXXXXXXXXXX YYYY-MM-DD Qubes OS Release X Signing Key sig! DDFA1A3E36879494 YYYY-MM-DD Qubes Master Signing Key - + gpg: 2 good signatures @@ -281,7 +281,7 @@ This is just an example, so the output you receive may not look exactly the same As a final sanity check, make sure the RSK is in your keyring with the correct trust level: -.. code:: bash +.. code:: console $ gpg2 -k "Qubes OS Release X Signing Key" pub rsa4096 YYYY-MM-DD [SC] @@ -321,18 +321,18 @@ In addition to the ``.DIGESTS`` files on the `downloads `__.) In order to do this, we have to know the exact size, in bytes, of the original ISO. There are two ways to get this information: from the ISO itself and from the Qubes website. Here’s an example of the first way: -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count=$(stat -c %s /path/to/iso) iflag=count_bytes | sha256sum @@ -458,7 +458,7 @@ Now, our goal is to perform the same verification steps as we did with the origi This command reads exactly the number of bytes of your Qubes ISO (obtained with ``stat -c %s /path/to/iso``) from the USB drive and pipes them into ``sha256sum``. The output should look something like this: -.. code:: bash +.. code:: console 0e68dd3347b68618d9e5f3ddb580bf7ecdd2166747630859b3582803f1ca8801 - 5523+0 records in @@ -472,7 +472,7 @@ Now, reading the number of bytes directly from the ISO is fine, but you may be c Therefore, in order to make things a bit more difficult for your hypothetical adversary, you may instead wish to perform the re-verification in an environment that has never seen the original ISO, e.g., a separate offline computer or a fresh VM the storage space of which is too small to hold the ISO. (**Note:** If you’re doing this in Qubes, you can attach the block device from sys-usb to a separate new qube. You don’t have to perform the re-verification directly in sys-usb.) In that case, you’ll have to obtain the size of the ISO in bytes and enter it into the above command manually. You can, of course, obtain the size by simply using the ``stat -c %s /path/to/iso`` command from above on the machine that has the ISO. You can also obtain it from the Qubes website by hovering over any ISO download button on the `downloads page `__. (You can also view these values directly in the downloads page’s `source data `__.) Once you have the exact size of the ISO in bytes, simply insert it into the same command, for example: -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count=5791285248 iflag=count_bytes | sha256sum @@ -481,7 +481,7 @@ If you wish to compute the values of other hash functions, you can replace ``sha In addition to checking hash values, you can also use GnuPG to verify the detached PGP signature directly against the data on the USB drive. (This assumes you’re already familiar with `how to verify detached PGP signatures on Qubes ISOs <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__.) -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count= iflag=count_bytes | gpg -v --verify Qubes-RX-x86_64.iso.asc - gpg: Signature made ` you may clone the AwesomeWM repository as follows: -.. code:: bash +.. code:: console $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome diff --git a/user/advanced-topics/bind-dirs.rst b/user/advanced-topics/bind-dirs.rst index b0fe1ef0..c318fc18 100644 --- a/user/advanced-topics/bind-dirs.rst +++ b/user/advanced-topics/bind-dirs.rst @@ -28,7 +28,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f 1. Make sure the directory ``/rw/config/qubes-bind-dirs.d`` exists. - .. code:: bash + .. code:: console sudo mkdir -p /rw/config/qubes-bind-dirs.d @@ -36,7 +36,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f 2. Create the file ``/rw/config/qubes-bind-dirs.d/50_user.conf`` with root permissions, if it doesn’t already exist. - .. code:: bash + .. code:: console sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf @@ -54,7 +54,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f 5. If the directory you wish to make persistent doesn’t exist in the template on which the app qube is based, you’ll need to create the directory (with its full path) under ``/rw/bind-dirs`` in the app qube. For example, if ``/var/lib/tor`` didn’t exist in the template, then you would execute the following command in your app qube: - .. code:: bash + .. code:: console sudo mkdir -p /rw/bind-dirs/var/lib/tor @@ -155,7 +155,7 @@ Bind dirs are obviously still supported but this must be configured either in th To use this feature, first, enable it: -.. code:: bash +.. code:: console qvm-service -e my-app-vm custom-persist @@ -163,7 +163,7 @@ To use this feature, first, enable it: Then, configure a persistent directory with ``qvm-features``: -.. code:: bash +.. code:: console qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir @@ -171,7 +171,7 @@ Then, configure a persistent directory with ``qvm-features``: To re-enable ``/home`` and ``/usr/local`` persistence, just add them to the list: -.. code:: bash +.. code:: console qvm-features my-app-vm custom-persist.home /home qvm-features my-app-vm custom-persist.usrlocal /usr/local @@ -182,7 +182,7 @@ When starting the VM, declared custom-persist bind dirs are automatically added A user may want their bind-dirs to be automatically pre-created in ``/rw/bind-dirs``. Custom persist can do this for you by providing the type of the resource to create (file or dir), owner, group and mode. For example: -.. code:: bash +.. code:: console qvm-features my-app-vm custom-persist.downloads dir:user:user:0755:/home/user/Downloads qvm-features my-app-vm custom-persist.my_ssh_known_hosts_file file:user:user:0600:/home/user/.ssh/known_hosts diff --git a/user/advanced-topics/config-files.rst b/user/advanced-topics/config-files.rst index 19c9f904..7f41ede6 100644 --- a/user/advanced-topics/config-files.rst +++ b/user/advanced-topics/config-files.rst @@ -37,7 +37,7 @@ These files are placed in ``/rw``, which survives a VM restart. That way, they c - 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. Good place to write custom firewall rules. - .. code:: bash + .. code:: text /etc/qubes/qubes-firewall.d /rw/config/qubes-firewall.d @@ -52,12 +52,12 @@ These files are placed in ``/rw``, which survives a VM restart. That way, they c .. code:: bash #!/bin/bash - + command="$1" vif="$2" vif_type="$3" ip="$4" - + if [ "$ip" == '10.137.0.100' ]; then case "$command" in online) @@ -84,11 +84,11 @@ GUI and audio configuration in dom0 The GUI configuration file ``/etc/qubes/guid.conf`` in one of a few not managed by ``qubes-prefs`` or the Qubes Manager tool. Sample config (included in default installation): -.. code:: bash +.. code:: # Sample configuration file for Qubes GUI daemon # For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html - + global: { # default values #allow_fullscreen = false; @@ -102,9 +102,9 @@ The GUI configuration file ``/etc/qubes/guid.conf`` in one of a few not managed #trayicon_mode = "border1"; #startup_timeout = 45; }; - + # most of setting can be set per-VM basis - + VM: { work: { allow_utf8_titles = true; diff --git a/user/advanced-topics/disposable-customization.rst b/user/advanced-topics/disposable-customization.rst index f3559700..41360de0 100644 --- a/user/advanced-topics/disposable-customization.rst +++ b/user/advanced-topics/disposable-customization.rst @@ -12,14 +12,14 @@ Introduction A :doc:`disposable ` can be based on any :ref:`app qube `. You can also choose to use different :ref:`disposable templates ` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property: -.. code:: bash +.. code:: console [user@dom0 ~]$ qvm-prefs template_for_dispvms True Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the ``appmenus-dispvm`` feature: -.. code:: bash +.. code:: console [user@dom0 ~]$ qvm-features appmenus-dispvm 1 @@ -38,7 +38,7 @@ Creating a new disposable template In Qubes 4.0, you’re no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template: -.. code:: bash +.. code:: console [user@dom0 ~]$ qvm-create --template