diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst index 9a7c61d6..5dbffc41 100644 --- a/developer/building/development-workflow.rst +++ b/developer/building/development-workflow.rst @@ -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 @@ -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 572f430e..1fc607a5 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/developer/building/qubes-builder-v2.rst @@ -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 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 e4b9cbe9..a4c96cd8 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 @@ -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 ` 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 `__, 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 diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst index abf896fc..348ff1b6 100644 --- a/developer/code/code-signing.rst +++ b/developer/code/code-signing.rst @@ -19,26 +19,26 @@ Alex Cabal has written an excellent `guide " - + 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,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 @@ -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 8a4cfabd..2e9ed06c 100644 --- a/developer/debugging/automated-tests.rst +++ b/developer/debugging/automated-tests.rst @@ -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() diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst index f2da265e..4ef4918f 100644 --- a/developer/debugging/safe-remote-ttys.rst +++ b/developer/debugging/safe-remote-ttys.rst @@ -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 236e3dec..ff0c1b3c 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -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 diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst index fbefc5a7..c6961b2c 100644 --- a/developer/services/qrexec2.rst +++ b/developer/services/qrexec2.rst @@ -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:: + .. 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 65dcd406..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` @@ -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 d0d3c7cc..48577c54 100644 --- a/project-security/security-pack.rst +++ b/project-security/security-pack.rst @@ -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 @@ -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 0a140d7e..bdc88028 100644 --- a/project-security/verifying-signatures.rst +++ b/project-security/verifying-signatures.rst @@ -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 @@ -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 @@ -321,18 +321,18 @@ In addition to the ``.DIGESTS`` files on the `downloads ` To create one that has no PCI devices attached, such as for ``sys-firewall``: -.. code:: bash +.. code:: console qvm-create -C DispVM -l green qvm-prefs autostart true @@ -109,7 +109,7 @@ To create one with a PCI device attached such as for ``sys-net`` or ``sys-usb``, **Note:** You can use ``qvm-pci`` to :ref:`determine ` the ````. Also, you will often need to include the ``-o no-strict-reset=True`` :ref:`option ` with USB controllers. -.. code:: bash +.. code:: console qvm-create -C DispVM -l red qvm-prefs virt_mode hvm @@ -123,7 +123,7 @@ To create one with a PCI device attached such as for ``sys-net`` or ``sys-usb``, Optionally, if this disposable will also provide network access to other qubes: -.. code:: bash +.. code:: console qvm-prefs provides_network true @@ -131,7 +131,7 @@ Optionally, if this disposable will also provide network access to other qubes: Next, set the old service qube’s autostart to false, and update any references to the old one, e.g.: -.. code:: bash +.. code:: console qvm-prefs sys-firewall netvm @@ -141,7 +141,7 @@ Also make sure to update any :doc:`RPC policies `` option. Example commands: -.. code:: bash +.. code:: console sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing @@ -152,7 +152,7 @@ Example (Note that the following example enables the unstable repo.) -.. code:: bash +.. code:: console sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm @@ -166,7 +166,7 @@ EFI Replace the example version numbers with the one you are upgrading to. -.. code:: bash +.. code:: console sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64 @@ -176,7 +176,7 @@ Grub2 ^^^^^ -.. code:: bash +.. code:: console sudo grub2-mkconfig -o /boot/grub2/grub.cfg @@ -192,7 +192,7 @@ Changing default kernel This section describes changing the default kernel in dom0. It is sometimes needed if you have upgraded to a newer kernel and are having problems booting, for example. On the next kernel update, the default will revert to the newest. -.. code:: bash +.. code:: console sudo nano /etc/default/grub [update the following two lines, add if needed] @@ -213,8 +213,6 @@ Requires installed `Whonix `__. Go to Qubes VM Manager -> System -> Global Settings. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix. -.. code:: bash - - Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix +:menusettings:`Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix` diff --git a/user/advanced-topics/installing-contributed-packages.rst b/user/advanced-topics/installing-contributed-packages.rst index c60143b1..09b9f211 100644 --- a/user/advanced-topics/installing-contributed-packages.rst +++ b/user/advanced-topics/installing-contributed-packages.rst @@ -20,7 +20,7 @@ In dom0, use ``qubes-dom0-update``: -.. code:: bash +.. code:: console sudo qubes-dom0-update qubes-repo-contrib @@ -29,7 +29,7 @@ In a Fedora-based template, use ``dnf``: -.. code:: bash +.. code:: console sudo dnf install qubes-repo-contrib @@ -38,14 +38,14 @@ In a Debian-based template, use ``apt``: -.. code:: bash +.. code:: console sudo apt update && sudo apt install qubes-repo-contrib The new repository definition will be in the usual location for your distro, and it will follow the naming pattern ``qubes-contrib-*``, depending on your Qubes release and whether it is in dom0 or a template. For example, in a Fedora template on Qubes 4.0, the new repository definition would be: -.. code:: bash +.. code:: text /etc/yum.repos.d/qubes-contrib-vm-r4.0.repo @@ -63,7 +63,7 @@ For example, to install ``qvm-screenshot-tool`` in dom0: -.. code:: bash +.. code:: console sudo qubes-dom0-update --clean qvm-screenshot-tool diff --git a/user/advanced-topics/kde.rst b/user/advanced-topics/kde.rst index 133ab912..d2f13cbb 100644 --- a/user/advanced-topics/kde.rst +++ b/user/advanced-topics/kde.rst @@ -26,7 +26,7 @@ KDE is very customisable, and there is a range of widgets to use. If you want to .. code:: bash #!/usr/bin/sh - + # Use Qubes provided menu instead of default XFCE one if [ "$XDG_SESSION_DESKTOP" = "KDE" ]; then XDG_MENU_PREFIX="kf5-" @@ -47,7 +47,7 @@ You can also change your default login manager (lightdm) to the new KDE default: - first you need to edit the ``/etc/sddm.conf`` to make sure if the custom X parameter is set according to Qubes needs: - .. code:: bash + .. code:: kconfig [XDisplay] ServerArguments=-nolisten tcp -background none @@ -82,14 +82,14 @@ Window Management You can set each window’s position and size like this: -.. code:: python +.. code:: text Right click title bar --> More actions --> Special window settings... - + Window matching tab Window class (application): Exact Match: Window title: Substring Match: - + Size & Position tab [x] Position: Apply Initially: x,y [x] Size: Apply Initially: x,y @@ -97,7 +97,7 @@ You can set each window’s position and size like this: You can also use ``kstart`` to control virtual desktop placement like this: -.. code:: bash +.. code:: console kstart --desktop 3 --windowclass -q --tray -a '' @@ -115,7 +115,7 @@ If you decide to remove KDE do **not** use ``dnf remove @kde-desktop-qubes``. Yo The safest way to remove (most of) KDE is: -.. code:: bash +.. code:: console sudo dnf remove kdelibs plasma-workspace diff --git a/user/advanced-topics/managing-vm-kernels.rst b/user/advanced-topics/managing-vm-kernels.rst index 086c71fa..55731ef9 100644 --- a/user/advanced-topics/managing-vm-kernels.rst +++ b/user/advanced-topics/managing-vm-kernels.rst @@ -108,7 +108,7 @@ Installing a new version from ``qubes-dom0-unstable`` repository: Loaded plugins: langpacks, post-transaction-actions, yum-qubes-hooks Resolving Dependencies (...) - + =========================================================================================== Package Arch Version Repository Size =========================================================================================== @@ -116,12 +116,12 @@ Installing a new version from ``qubes-dom0-unstable`` repository: kernel-qubes-vm x86_64 1000:4.1.12-6.pvops.qubes qubes-dom0-cached 40 M Removing: kernel-qubes-vm x86_64 1000:3.18.10-2.pvops.qubes @anaconda/R3.0 134 M - + Transaction Summary =========================================================================================== Install 1 Package Remove 1 Package - + Total download size: 40 M Is this ok [y/d/N]: y Downloading packages: @@ -136,13 +136,13 @@ Installing a new version from ``qubes-dom0-unstable`` repository: Error in PREUN scriptlet in rpm package 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64 Verifying : 1000:kernel-qubes-vm-4.1.12-6.pvops.qubes.x86_64 1/2 Verifying : 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64 2/2 - + Installed: kernel-qubes-vm.x86_64 1000:4.1.12-6.pvops.qubes - + Failed: kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes - + Complete! [user@dom0 ~]$ @@ -174,17 +174,17 @@ To prepare such a VM kernel, you need to install the ``qubes-kernel-vm-support`` Package 1000:kernel-devel-4.1.9-6.pvops.qubes.x86_64 already installed and latest version Resolving Dependencies (...) - + ================================================================================ Package Arch Version Repository Size ================================================================================ Installing: qubes-kernel-vm-support x86_64 3.1.2-1.fc20 qubes-dom0-cached 9.2 k - + Transaction Summary ================================================================================ Install 1 Package - + Total download size: 9.2 k Installed size: 13 k Is this ok [y/d/N]: y @@ -194,16 +194,16 @@ To prepare such a VM kernel, you need to install the ``qubes-kernel-vm-support`` Transaction test succeeded Running transaction (shutdown inhibited) Installing : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1 - + Creating symlink /var/lib/dkms/u2mfn/3.1.2/source -> /usr/src/u2mfn-3.1.2 - + DKMS: add completed. Verifying : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1 - + Installed: qubes-kernel-vm-support.x86_64 0:3.1.2-1.fc20 - + Complete! @@ -244,7 +244,7 @@ Using kernel installed in the VM Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then: -.. code:: bash +.. code:: console qvm-prefs virt_mode hvm qvm-prefs kernel '' @@ -261,7 +261,7 @@ Install whatever kernel you want. You need to also ensure you have the ``kernel- If you are using a distribution kernel package (``kernel`` package), the initramfs and kernel modules may be handled automatically. If you are using a manually built kernel, you need to handle this on your own. Take a look at the ``dkms`` documentation, especially the ``dkms autoinstall`` command may be useful. If you did not see the ``kernel`` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself. Replace the version numbers in the example below with the ones appropriate to the kernel you are installing: -.. code:: bash +.. code:: console sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64 @@ -269,7 +269,7 @@ If you are using a distribution kernel package (``kernel`` package), the initram Once the kernel is installed, you need to setup ``grub2`` by running: -.. code:: bash +.. code:: console sudo grub2-install /dev/xvda @@ -277,7 +277,7 @@ Once the kernel is installed, you need to setup ``grub2`` by running: Finally, you need to create a GRUB configuration. You may want to adjust some settings in ``/etc/default/grub``; for example, lower ``GRUB_TIMEOUT`` to speed up VM startup. Then, you need to generate the actual configuration. In Fedora it can be done using the ``grub2-mkconfig`` tool: -.. code:: bash +.. code:: console sudo grub2-mkconfig -o /boot/grub2/grub.cfg @@ -285,7 +285,7 @@ Finally, you need to create a GRUB configuration. You may want to adjust some se You can safely ignore this error message: -.. code:: bash +.. code:: console grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map @@ -319,7 +319,7 @@ Using a distribution kernel package the initramfs and kernel modules should be h Install distribution kernel image, kernel headers and the grub. -.. code:: bash +.. code:: console sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support @@ -327,7 +327,7 @@ Install distribution kernel image, kernel headers and the grub. If you are doing that on a qube based on “Debian Minimal” template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select ``/dev/xvda`` (check the box using the space bar, and validate your choice with “Enter”.) If this popup does not appear during the installation, you must manually setup ``grub2`` by running: -.. code:: bash +.. code:: console sudo grub-install /dev/xvda @@ -381,7 +381,7 @@ Run DKMS. Replace this with actual kernel version. -.. code:: bash +.. code:: console sudo dkms autoinstall -k @@ -390,7 +390,7 @@ For example. -.. code:: bash +.. code:: console sudo dkms autoinstall -k 4.19.0-6-amd64 @@ -399,7 +399,7 @@ Update initramfs. -.. code:: bash +.. code:: console sudo update-initramfs -u @@ -409,16 +409,16 @@ The output should look like this: .. code:: console $ sudo dkms autoinstall -k 3.16.0-4-amd64 - + u2mfn: Running module version sanity check. - Original module - No original module exists within this kernel - Installation - Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/ - + depmod.... - + DKMS: install completed. $ sudo update-initramfs -u update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64 diff --git a/user/advanced-topics/mount-from-other-os.rst b/user/advanced-topics/mount-from-other-os.rst index db9f8d13..8855ab9e 100644 --- a/user/advanced-topics/mount-from-other-os.rst +++ b/user/advanced-topics/mount-from-other-os.rst @@ -26,7 +26,7 @@ Decrypting the Disk 1. Open a Linux terminal in either dom0 or the app qube the disk was passed through to and enter ``lsblk``, which will result in an output similar to the following. In this example, the currently booted Qubes system is installed on ``sda`` and the qubes system to be accessed is on ``nvme0n1p2``. - .. code:: bash + .. code:: text sda 8:0 0 111.8G 0 disk ├─sda1 8:1 0 200M 0 part /boot/efi @@ -90,8 +90,8 @@ Mounting the disk -.. list-table:: - :widths: 28 28 28 +.. list-table:: + :widths: 28 28 28 :align: center :header-rows: 1 @@ -110,7 +110,7 @@ Mounting the disk * - other_install/pool00_tmeta - LVM Metadata - The metadata LV of this disk. - + 6. Mount the disk using the command ``mount /dev/other_install/ ``. *Note:* Any compromised data which exists in the volume to be mounted will be accessible here. Do not mount untrusted partitions in dom0. diff --git a/user/advanced-topics/qubes-service.rst b/user/advanced-topics/qubes-service.rst index 6bfa1d1d..1a5ba7e8 100644 --- a/user/advanced-topics/qubes-service.rst +++ b/user/advanced-topics/qubes-service.rst @@ -12,7 +12,7 @@ Under the hood, an enabled service in a VM is signaled by a file in ``/var/run/q Adding support for systemd services is pretty simple. In the VM, create the following file (and directory, if needed): ``/etc/systemd/system/.service.d/30_qubes.conf``. It should contain the following: -.. code:: bash +.. code:: systemd [Unit] ConditionPathExists=/var/run/qubes-service/ diff --git a/user/advanced-topics/resize-disk-image.rst b/user/advanced-topics/resize-disk-image.rst index eac25a82..9d87b527 100644 --- a/user/advanced-topics/resize-disk-image.rst +++ b/user/advanced-topics/resize-disk-image.rst @@ -40,7 +40,7 @@ Increasing the size of Disk Images Use either GUI tool Qube Settings (``qubes-vm-settings``) or the CLI tool ``qvm-volume``. Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you need more, use ``qvm-volume``: -.. code:: bash +.. code:: console qvm-volume extend :root @@ -48,7 +48,7 @@ Use either GUI tool Qube Settings (``qubes-vm-settings``) or the CLI tool ``qvm- OR -.. code:: bash +.. code:: console qvm-volume extend :private @@ -90,7 +90,7 @@ FreeBSD ^^^^^^^ -.. code:: bash +.. code:: console gpart recover ada0 sysctl kern.geom.debugflags=0x10 @@ -115,7 +115,7 @@ You can create a new qube, copy your files in to the new qube, and delete the ol Or you can take the risk of reducing the size of the disk. For example, to reduce the private storage of qube1 to 1GiB: Open a terminal in dom0: -.. code:: bash +.. code:: console qvm-shutdown qube1 sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private diff --git a/user/advanced-topics/salt.rst b/user/advanced-topics/salt.rst index a8f3bc1e..0f546013 100644 --- a/user/advanced-topics/salt.rst +++ b/user/advanced-topics/salt.rst @@ -50,7 +50,7 @@ States The smallest unit of configuration is a state. A state is written in YAML and looks like this: -.. code:: bash +.. code:: yaml stateid: cmd.run: #this is the execution module. in this case it will execute a command on the shell @@ -74,7 +74,7 @@ With these three states you can define most of the configuration of a VM. You can also `order the execution `__ of your states: -.. code:: bash +.. code:: yaml D: cmd.run: @@ -111,7 +111,7 @@ Top Files After you have several state files, you need something to assign them to a qube. This is done by ``*.top`` files (`official documentation `__). Their structure looks like this: -.. code:: bash +.. code:: yaml environment: target_matching_clause: @@ -122,7 +122,7 @@ After you have several state files, you need something to assign them to a qube. In most cases, the environment will be called ``base``. The ``target_matching_clause`` will be used to select your minions (Templates or qubes). It can be either the name of a qube or a regular expression. If you are using a regular expressions, you need to give Salt a hint you are doing so: -.. code:: bash +.. code:: yaml environment: ^app-(work|(?!mail).*)$: @@ -193,15 +193,15 @@ Configuring a qube's System from Dom0 Salt can be used to configure qubes from dom0. Simply set the qube name as the target minion name in the top file. You can also use the ``qubes`` pillar module to select qubes with a particular property (see below). If you do so, then you need to pass additional arguments to the ``qubesctl`` tool: -.. code:: bash +.. code:: text usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0] [--targets TARGETS | --templates | --app | --all] ... - + positional arguments: command Salt command to execute (e.g., state.apply) - + optional arguments: -h, --help show this help message and exit --show-output Show output of management commands @@ -233,7 +233,7 @@ Writing Your Own Configurations Let’s start with a quick example: -.. code:: bash +.. code:: yaml my new and shiny VM: qvm.present: @@ -267,7 +267,7 @@ As you will notice, the options are the same (or very similar) to those used in This should be put in ``/srv/salt/my-new-vm.sls`` or another ``.sls`` file. A separate ``*.top`` file should be also written: -.. code:: bash +.. code:: yaml base: dom0: @@ -299,7 +299,7 @@ Example of Configuring Templates from Dom0 Lets make sure that the ``mc`` package is installed in all templates. Similar to the previous example, you need to create a state file (``/srv/salt/mc-everywhere.sls``): -.. code:: bash +.. code:: yaml mc: pkg.installed: [] @@ -308,7 +308,7 @@ Lets make sure that the ``mc`` package is installed in all templates. Similar to Then the appropriate top file (``/srv/salt/mc-everywhere.top``): -.. code:: bash +.. code:: yaml base: qubes:type:template: @@ -349,7 +349,7 @@ As in the example above, it creates a qube and sets its properties. You can set properties of an existing qube: -.. code:: bash +.. code:: yaml my preferences: qvm.prefs: @@ -364,7 +364,7 @@ You can set properties of an existing qube: ^^^^^^^^^^^^^^^ -.. code:: bash +.. code:: yaml services in my qube: qvm.service: @@ -388,7 +388,7 @@ This enables, disables, or sets to default, services as in ``qvm-service``. Ensures the specified qube is running: -.. code:: bash +.. code:: yaml qube is running: qvm.running: @@ -402,7 +402,7 @@ Virtual Machine Formulae You can use these formulae to download, install, and configure qubes in Qubes. These formulae use pillar data to define default qube names and configuration details. The default settings can be overridden in the pillar data located in: -.. code:: bash +.. code:: yaml /srv/pillar/base/qvm/init.sls @@ -681,7 +681,7 @@ Disk Quota Exceeded (When Installing Templates) If you install multiple templates you may encounter this error. The solution is to shut down the updateVM between each install: -.. code:: bash +.. code:: yaml install template and shutdown updateVM: cmd.run: diff --git a/user/advanced-topics/secondary-storage.rst b/user/advanced-topics/secondary-storage.rst index a1357ecd..8c4c4382 100644 --- a/user/advanced-topics/secondary-storage.rst +++ b/user/advanced-topics/secondary-storage.rst @@ -20,14 +20,14 @@ Qubes 4.0 is more flexible than earlier versions about placing different VMs on You can query qvm-pool to list available storage drivers: -.. code:: bash +.. code:: console qvm-pool --help-drivers qvm-pool driver explanation: -.. code:: bash +.. code:: text refers to using a simple file for image storage and lacks a few features. refers to storing images on a filesystem supporting copy on write. @@ -48,7 +48,7 @@ These steps assume you have already created a separate `volume group is a freely chosen pool name # is LVM volume group name @@ -73,7 +73,7 @@ Theses steps assume you have already created a separate Btrfs filesystem for you It is possible to use an existing Btrfs storage if it is configured. In dom0, available Btrfs storage can be displayed using: -.. code:: bash +.. code:: console mount -t btrfs btrfs show filesystem @@ -81,7 +81,7 @@ It is possible to use an existing Btrfs storage if it is configured. In dom0, av To register the storage to qubes: -.. code:: bash +.. code:: console # is a freely chosen pool name # is the mounted path to the second btrfs storage @@ -94,14 +94,14 @@ Using the new pool Now, you can create qubes in that pool: -.. code:: bash +.. code:: console qvm-create -P --label red It isn’t possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one: -.. code:: bash +.. code:: console qvm-clone -P qvm-remove @@ -109,7 +109,7 @@ It isn’t possible to directly migrate an existing qube to the new pool, but yo If that was a template, or other qube referenced elsewhere (netVM or such), you will need to adjust those references manually after moving. For example: -.. code:: bash +.. code:: console qvm-prefs template @@ -120,7 +120,7 @@ Example setup of second drive. Assuming the secondary hard disk is at /dev/sdb , you can encrypt the drive as follows. Note that the drive contents will be completely erased, In a dom0 terminal run this command - use the same passphrase as the main Qubes disk to avoid a second password prompt at boot: -.. code:: bash +.. code:: console sudo cryptsetup luksFormat --sector-size=512 /dev/sdb sudo blkid /dev/sdb @@ -131,7 +131,7 @@ Assuming the secondary hard disk is at /dev/sdb , you can encrypt the drive as f Note the device’s UUID (in this example “b209…”), we will use it as its luks name for auto-mounting at boot, by editing ``/etc/crypttab``, and adding this line to crypttab (replacing both “b209…” entries with your device’s UUID taken from blkid) : -.. code:: bash +.. code:: text luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none @@ -144,28 +144,28 @@ For LVM First create the physical volume: -.. code:: bash +.. code:: console sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde Then create the LVM volume group, we will use for example “qubes” as the : -.. code:: bash +.. code:: console sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde And then use “poolhd0” as the (LVM thin pool name): -.. code:: bash +.. code:: console sudo lvcreate -T -n poolhd0 -l +100%FREE qubes Finally we will tell Qubes to add a new pool on the just created thin pool: -.. code:: bash +.. code:: console qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2 @@ -176,7 +176,7 @@ For Btrfs First create the physical volume: -.. code:: bash +.. code:: console # ` in a package that is in a testing repository, please reference the appropriate issue in `updates-status `__. .. |thumbsup| image:: /attachment/doc/like.png -.. |thumbsdown| image:: /attachment/doc/dislike.png \ No newline at end of file +.. |thumbsdown| image:: /attachment/doc/dislike.png diff --git a/user/downloading-installing-upgrading/upgrade/2.rst b/user/downloading-installing-upgrading/upgrade/2.rst index 1101248c..2fd2ffb6 100644 --- a/user/downloading-installing-upgrading/upgrade/2.rst +++ b/user/downloading-installing-upgrading/upgrade/2.rst @@ -31,7 +31,7 @@ Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous 2. Install all the updates for Dom0: - .. code:: bash + .. code:: console sudo qubes-dom0-update @@ -49,7 +49,7 @@ After this step you should have ``qubes-release-2-5`` in your Dom0. Important: i **Note:** be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest Qubes packages, specifically ``qubes-core-vm-2.1.33`` or later. This doesn’t imply that the VM must already be upgraded to fc20 – for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there. -.. code:: bash +.. code:: console sudo qubes-dom0-update qubes-dom0-dist-upgrade sudo qubes-dom0-update @@ -64,7 +64,7 @@ After this step you should have ``qubes-release-2-5`` in your Dom0. Important: i 4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing: -.. code:: bash +.. code:: console sudo qubes-dom0-update qubes-template-fedora-20-x64 diff --git a/user/downloading-installing-upgrading/upgrade/2b1.rst b/user/downloading-installing-upgrading/upgrade/2b1.rst index 3d6258c9..2ee31af0 100644 --- a/user/downloading-installing-upgrading/upgrade/2b1.rst +++ b/user/downloading-installing-upgrading/upgrade/2b1.rst @@ -19,7 +19,7 @@ By default, in Qubes R1, there is only one template, however users are free to c 2. Install ``qubes-upgrade-vm`` package (this package brings in R2 repo definitions and R2 keys) - .. code:: bash + .. code:: console sudo yum install qubes-upgrade-vm @@ -27,14 +27,14 @@ By default, in Qubes R1, there is only one template, however users are free to c 3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs): - .. code:: bash + .. code:: console sudo yum update The installer (yum) will prompt to accept the new Qubes R2 signing key: - .. code:: bash + .. code:: text Importing GPG key 0x0A40E458: Userid : "Qubes OS Release 2 Signing Key" @@ -70,7 +70,7 @@ Be sure to do steps described in this section after *all* your template and stan 2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys: - .. code:: bash + .. code:: console sudo qubes-dom0-update qubes-release @@ -79,7 +79,7 @@ Be sure to do steps described in this section after *all* your template and stan 3. Install R2 packages: - .. code:: bash + .. code:: console sudo qubes-dom0-update --releasever=2 diff --git a/user/downloading-installing-upgrading/upgrade/2b2.rst b/user/downloading-installing-upgrading/upgrade/2b2.rst index 271a81f4..69315f65 100644 --- a/user/downloading-installing-upgrading/upgrade/2b2.rst +++ b/user/downloading-installing-upgrading/upgrade/2b2.rst @@ -17,7 +17,7 @@ By default, in Qubes R1, there is only one template, however users are free to c 2. Install ``qubes-upgrade-vm`` package (this package brings in R2 repo definitions and R2 keys) - .. code:: bash + .. code:: console sudo yum install qubes-upgrade-vm @@ -25,14 +25,14 @@ By default, in Qubes R1, there is only one template, however users are free to c 3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs): - .. code:: bash + .. code:: console sudo yum update The installer (yum) will prompt to accept the new Qubes R2 signing key: - .. code:: bash + .. code:: text Importing GPG key 0x0A40E458: Userid : "Qubes OS Release 2 Signing Key" @@ -86,7 +86,7 @@ Be sure to do steps described in this section after *all* your template and stan 2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys: - .. code:: bash + .. code:: console sudo qubes-dom0-update qubes-release @@ -95,7 +95,7 @@ Be sure to do steps described in this section after *all* your template and stan 3. Install R2 upgrade package: - .. code:: bash + .. code:: console sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade @@ -103,7 +103,7 @@ Be sure to do steps described in this section after *all* your template and stan 4. Start upgrade process: - .. code:: bash + .. code:: console sudo qubes-dist-upgrade @@ -115,7 +115,7 @@ Be sure to do steps described in this section after *all* your template and stan 7. When system starts up, login and start start - .. code:: bash + .. code:: console sudo qubes-dist-upgrade diff --git a/user/downloading-installing-upgrading/upgrade/2b3.rst b/user/downloading-installing-upgrading/upgrade/2b3.rst index a58969f6..93959b00 100644 --- a/user/downloading-installing-upgrading/upgrade/2b3.rst +++ b/user/downloading-installing-upgrading/upgrade/2b3.rst @@ -21,7 +21,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe 2. Proceed with normal update in the template: - .. code:: bash + .. code:: console sudo yum update @@ -29,7 +29,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe 3. Ensure that you’ve got qubes-core-vm package version 2.1.13-3.fc18: - .. code:: bash + .. code:: console rpm -q qubes-core-vm @@ -37,7 +37,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe 4. Update the system to R2 beta3 packages: - .. code:: bash + .. code:: console sudo yum --enablerepo=qubes-vm-r2b3-current update @@ -57,7 +57,7 @@ Be sure to do steps described in this section after *all* your template and stan 2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys: - .. code:: bash + .. code:: console sudo qubes-dom0-update qubes-release @@ -66,7 +66,7 @@ Be sure to do steps described in this section after *all* your template and stan 3. Upgrade dom0 to R2 beta3: - .. code:: bash + .. code:: console sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current @@ -76,7 +76,7 @@ Be sure to do steps described in this section after *all* your template and stan 5. Now is the time to shutdown all the VMs: - .. code:: bash + .. code:: console qvm-shutdown --all --wait diff --git a/user/downloading-installing-upgrading/upgrade/3_0.rst b/user/downloading-installing-upgrading/upgrade/3_0.rst index afa024d4..e757d58d 100644 --- a/user/downloading-installing-upgrading/upgrade/3_0.rst +++ b/user/downloading-installing-upgrading/upgrade/3_0.rst @@ -27,7 +27,7 @@ Upgrade Fedora template: 2. Install ``qubes-upgrade-vm`` package: - .. code:: bash + .. code:: console sudo yum install qubes-upgrade-vm @@ -35,7 +35,7 @@ Upgrade Fedora template: 3. Proceed with normal update in the template: - .. code:: bash + .. code:: console sudo yum update @@ -54,7 +54,7 @@ Upgrade Debian template: 2. Update repository definition: - .. code:: bash + .. code:: console sudo cp /etc/apt/sources.list.d/qubes-r2.list /etc/apt/sources.list.d/qubes-r3-upgrade.list @@ -64,7 +64,7 @@ Upgrade Debian template: 3. Proceed with normal update in the template: - .. code:: bash + .. code:: console sudo apt-get update sudo apt-get dist-upgrade @@ -86,7 +86,7 @@ Be sure to do steps described in this section after *all* your template and stan 2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys: - .. code:: bash + .. code:: console sudo qubes-dom0-update qubes-release @@ -95,7 +95,7 @@ Be sure to do steps described in this section after *all* your template and stan 3. Upgrade dom0 to R3.0: - .. code:: bash + .. code:: console sudo qubes-dom0-update --releasever=3.0 @@ -106,7 +106,7 @@ Be sure to do steps described in this section after *all* your template and stan 5. Enable Xen services: - .. code:: bash + .. code:: console sudo systemctl enable xenconsoled.service xenstored.service @@ -124,7 +124,7 @@ Please note that if you use Anti Evil Maid, then it won’t be able to unseal th Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template: -.. code:: bash +.. code:: console sudo qubes-dom0-update qubes-template-fedora-21 @@ -161,7 +161,7 @@ Because of above limitations, you will need to configure some of those manually. 2. Start the VM from command line: - .. code:: + .. code:: console [user@dom0 ~]$ qvm-start custom-template --> Loading the VM (type = template)... @@ -177,14 +177,14 @@ Because of above limitations, you will need to configure some of those manually. 3. Access VM console: - .. code:: + .. code:: console [user@dom0 ~]$ virsh -c xen:/// console custom-template 4. Configure network according to parameters retrieved in first step: - .. code:: bash + .. code:: console ip addr add 10.137.1.53/32 dev eth0 ip route add 10.137.1.1/32 dev eth0 diff --git a/user/downloading-installing-upgrading/upgrade/3_1.rst b/user/downloading-installing-upgrading/upgrade/3_1.rst index 01d6dcd8..6a6bd34c 100644 --- a/user/downloading-installing-upgrading/upgrade/3_1.rst +++ b/user/downloading-installing-upgrading/upgrade/3_1.rst @@ -21,7 +21,7 @@ Upgrade Fedora templates: 2. Install the ``qubes-upgrade-vm`` package: - .. code:: bash + .. code:: console sudo yum install qubes-upgrade-vm @@ -29,7 +29,7 @@ Upgrade Fedora templates: 3. Proceed with a normal upgrade in the template: - .. code:: bash + .. code:: console sudo yum upgrade @@ -47,7 +47,7 @@ Upgrade Debian (and Whonix) templates: 2. Update repository definition: - .. code:: bash + .. code:: console sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list @@ -56,7 +56,7 @@ Upgrade Debian (and Whonix) templates: 3. Proceed with a normal update in the template: - .. code:: bash + .. code:: console sudo apt-get update sudo apt-get dist-upgrade @@ -65,7 +65,7 @@ Upgrade Debian (and Whonix) templates: 4. Remove unnecessary now file: - .. code:: bash + .. code:: console sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list @@ -85,7 +85,7 @@ Upgrading dom0 2. Upgrade dom0 to R3.1: - .. code:: bash + .. code:: console sudo qubes-dom0-update --releasever=3.1 @@ -108,7 +108,7 @@ If you use USB VM, you may encounter problem with starting it on updated Xen ver Once you have upgraded dom0, you can install new templates from Qubes R3.1 repositories, in particular the new default Fedora 23 template: -.. code:: bash +.. code:: console sudo qubes-dom0-update qubes-template-fedora-23 diff --git a/user/downloading-installing-upgrading/upgrade/3_2.rst b/user/downloading-installing-upgrading/upgrade/3_2.rst index eec92438..041352c6 100644 --- a/user/downloading-installing-upgrading/upgrade/3_2.rst +++ b/user/downloading-installing-upgrading/upgrade/3_2.rst @@ -17,7 +17,7 @@ Upgrading dom0 3. Install ``qubes-release`` package carrying R3.2 repository information. - .. code:: bash + .. code:: console sudo qubes-dom0-update --releasever=3.2 qubes-release @@ -29,7 +29,7 @@ Upgrading dom0 - .. code:: bash + .. code:: console sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2 (...) @@ -37,7 +37,7 @@ Upgrading dom0 =============================================================== Install 16 Packages (+ 31 Dependent packages) Upgrade 4 Packages (+200 Dependent packages) - + Total download size: 173 M Is this ok [y/d/N]: n Exiting on user command @@ -48,7 +48,7 @@ Upgrading dom0 4. Upgrade dom0 to R3.2: - .. code:: bash + .. code:: console sudo qubes-dom0-update @@ -66,7 +66,7 @@ Upgrading dom0 - .. code:: bash + .. code:: text warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew @@ -76,7 +76,7 @@ Upgrading dom0 - .. code:: bash + .. code:: console rm -f /etc/group.rpmnew rm -f /etc/shadow.rpmnew @@ -116,7 +116,7 @@ Upgrade Fedora templates: 2. Install the ``qubes-upgrade-vm`` package: - .. code:: bash + .. code:: console sudo dnf install --refresh qubes-upgrade-vm @@ -124,7 +124,7 @@ Upgrade Fedora templates: 3. Proceed with a normal upgrade in the template: - .. code:: bash + .. code:: console sudo dnf upgrade --refresh @@ -132,7 +132,7 @@ Upgrade Fedora templates: 4. Add new packages (only needed in default template): - .. code:: bash + .. code:: console sudo dnf install qubes-mgmt-salt-vm-connector @@ -150,7 +150,7 @@ Upgrade Debian (and Whonix) templates: 2. Update repository definition: - .. code:: bash + .. code:: console sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list @@ -159,7 +159,7 @@ Upgrade Debian (and Whonix) templates: 3. Proceed with a normal update in the template: - .. code:: bash + .. code:: console sudo apt-get update sudo apt-get dist-upgrade @@ -168,7 +168,7 @@ Upgrade Debian (and Whonix) templates: 4. Add new packages (only needed in default template): - .. code:: bash + .. code:: console sudo apt-get install qubes-mgmt-salt-vm-connector @@ -176,7 +176,7 @@ Upgrade Debian (and Whonix) templates: 5. Remove unnecessary now file: - .. code:: bash + .. code:: console sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list diff --git a/user/downloading-installing-upgrading/upgrade/4_0.rst b/user/downloading-installing-upgrading/upgrade/4_0.rst index c2c5f0af..16b1e438 100644 --- a/user/downloading-installing-upgrading/upgrade/4_0.rst +++ b/user/downloading-installing-upgrading/upgrade/4_0.rst @@ -63,7 +63,7 @@ Restore from your backup 2. Since patches may have been released since your installation image was created, update Qubes R4.0 by going to the dom0 command line (**Qubes menu -> Terminal Emulator**) then running: - .. code:: bash + .. code:: console sudo qubes-dom0-update diff --git a/user/downloading-installing-upgrading/upgrade/4_1.rst b/user/downloading-installing-upgrading/upgrade/4_1.rst index 7f34240d..1bc5177f 100644 --- a/user/downloading-installing-upgrading/upgrade/4_1.rst +++ b/user/downloading-installing-upgrading/upgrade/4_1.rst @@ -37,7 +37,7 @@ The upgrade may take several hours, and will download several gigabytes of data. In place upgrade is a complex operation. For this reason, we provide a ``qubes-dist-upgrade`` tool to handle all the necessary steps automatically. You can install it with the following command in the dom0 terminal: -.. code:: bash +.. code:: console sudo qubes-dom0-update -y qubes-dist-upgrade @@ -47,12 +47,12 @@ The upgrade consists of seven stages — six before restarting the system — la Full list of options can be obtained with ``qubes-dist-upgrade --help``: -.. code:: bash +.. code:: text Usage: qubes-dist-upgrade [OPTIONS]... - + This script is used for updating current QubesOS R4.0 to R4.1. - + Options: --double-metadata-size, -d (STAGE 0) Double current LVM thin pool metadata size. --update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM. @@ -61,7 +61,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``: --dist-upgrade, -s (STAGE 4) Upgrade to Qubes R4.1 and Fedora 32 repositories. --setup-efi-grub, -g (STAGE 5) Setup EFI Grub. --all, -a Execute all the above stages in one call. - + --assumeyes, -y Automatically answer yes for all questions. --usbvm, -u Current UsbVM defined (default 'sys-usb'). --netvm, -n Current NetVM defined (default 'sys-net'). @@ -74,7 +74,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``: Can be useful if multiple updates proxy VMs are configured. --max-concurrency How many TemplateVM/StandaloneVM to update in parallel in STAGE 1 (default 4). - + --resync-appmenus-features Resync applications and features. To be ran individually after reboot. @@ -82,7 +82,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``: After installing the tool, upgrade can be performed all at once with: -.. code:: bash +.. code:: console sudo qubes-dist-upgrade --all @@ -94,7 +94,7 @@ Alternatively, each upgrade stage can be started separately (see the list of opt After completing “STAGE 0” through “STAGE 5”, restart the system. Then perform the final step: -.. code:: bash +.. code:: console sudo qubes-dist-upgrade --resync-appmenus-features diff --git a/user/downloading-installing-upgrading/upgrade/4_2.rst b/user/downloading-installing-upgrading/upgrade/4_2.rst index 3802df12..9115094e 100644 --- a/user/downloading-installing-upgrading/upgrade/4_2.rst +++ b/user/downloading-installing-upgrading/upgrade/4_2.rst @@ -21,7 +21,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla 2. Install the ``qubes-dist-upgrade`` tool. This is the inplace upgrade tool, which is not what we’re doing. However it will be needed in order to prepare the templates for the 4.2 version. You install it with the following command in the dom0 terminal: - .. code:: bash + .. code:: console sudo qubes-dom0-update -y qubes-dist-upgrade @@ -29,7 +29,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla 3. Change your templates to use the 4.2 repositories instead of the 4.1 ones. You do this with the following command in the dom0 terminal: - .. code:: bash + .. code:: console qubes-dist-upgrade --template-standalone-upgrade @@ -56,7 +56,7 @@ The upgrade may take several hours, and will download several gigabytes of data. In place upgrade is a complex operation. For this reason, we provide a ``qubes-dist-upgrade`` tool to handle all the necessary steps automatically. You can install it with the following command in the dom0 terminal: -.. code:: bash +.. code:: console sudo qubes-dom0-update -y qubes-dist-upgrade @@ -66,12 +66,12 @@ The upgrade consists of six stages — three before restarting the system — la Full list of options can be obtained with ``qubes-dist-upgrade --help``: -.. code:: bash +.. code:: text Usage: qubes-dist-upgrade [OPTIONS]... - + This script is used for updating current QubesOS R4.1 to R4.2. - + Options: --update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM. --release-upgrade, -r (STAGE 2) Update 'qubes-release' for Qubes R4.2. @@ -84,7 +84,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``: to the new format in /etc/qubes/policy.d. --all-pre-reboot Execute stages 1 to 3 --all-post-reboot Execute stages 4 to 6 - + --assumeyes, -y Automatically answer yes for all questions. --usbvm, -u Current UsbVM defined (default 'sys-usb'). --netvm, -n Current NetVM defined (default 'sys-net'). @@ -102,7 +102,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``: After installing the tool, before-reboot stages can be performed at once with: -.. code:: bash +.. code:: console sudo qubes-dist-upgrade --all-pre-reboot @@ -114,7 +114,7 @@ Alternatively, each upgrade stage can be started separately (see the list of opt After completing “STAGE 1” through “STAGE 3”, restart the system. Then perform the final steps: -.. code:: bash +.. code:: console sudo qubes-dist-upgrade --all-post-reboot diff --git a/user/how-to-guides/backup-emergency-restore-v2.rst b/user/how-to-guides/backup-emergency-restore-v2.rst index ba3cc102..ece6ab12 100644 --- a/user/how-to-guides/backup-emergency-restore-v2.rst +++ b/user/how-to-guides/backup-emergency-restore-v2.rst @@ -71,7 +71,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi **Note:** For multi-part files, a loop can be used: -.. code:: bash +.. code:: console find -name 'private.img.*' | sort -V | while read f; do openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in $f -out diff --git a/user/how-to-guides/how-to-copy-and-move-files.rst b/user/how-to-guides/how-to-copy-and-move-files.rst index 2fb13885..3f5e3a57 100644 --- a/user/how-to-guides/how-to-copy-and-move-files.rst +++ b/user/how-to-guides/how-to-copy-and-move-files.rst @@ -15,7 +15,7 @@ For simplicity, these instructions will refer to copying/moving a single file, b 3. If the target qube is not already running, it will be started automatically, and the file will be copied there. It will show up in this directory (which will automatically be created if it does not already exist): - .. code:: bash + .. code:: text /home/user/QubesIncoming// @@ -28,13 +28,13 @@ For simplicity, these instructions will refer to copying/moving a single file, b The same operations are also available via these command-line tools: -.. code:: bash +.. code:: console qvm-copy [--without-progress] file [file]+ -.. code:: bash +.. code:: console qvm-move [--without-progress] file [file]+ diff --git a/user/how-to-guides/how-to-copy-and-paste-text.rst b/user/how-to-guides/how-to-copy-and-paste-text.rst index 56148bf4..d3b7f500 100644 --- a/user/how-to-guides/how-to-copy-and-paste-text.rst +++ b/user/how-to-guides/how-to-copy-and-paste-text.rst @@ -43,7 +43,7 @@ Clipboard automatic policy enforcement The Qubes clipboard :doc:`RPC policy ` is configurable in: -.. code:: bash +.. code:: console /etc/qubes-rpc/policy/qubes.ClipboardPaste @@ -51,7 +51,7 @@ The Qubes clipboard :doc:`RPC policy ` is conf You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your “vault” app qube (and it is highly recommended that you do not), then you should edit the policy as follows: -.. code:: bash +.. code:: text @anyvm vault deny @anyvm @anyvm ask @@ -66,7 +66,7 @@ By default data pasted into a qube will remain there until user copies something To enable automatic wiping of the clipboard after a minute use ``qvm-service``: -.. code:: bash +.. code:: console qvm-service --enable VMNAME gui-agent-clipboard-wipe @@ -78,7 +78,7 @@ Shortcut configuration The copy/paste shortcuts are configurable via ``qvm-features``, e.g. -.. code:: bash +.. code:: console qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c' qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v' diff --git a/user/how-to-guides/how-to-copy-from-dom0.rst b/user/how-to-guides/how-to-copy-from-dom0.rst index fcf15e80..fd60d31b 100644 --- a/user/how-to-guides/how-to-copy-from-dom0.rst +++ b/user/how-to-guides/how-to-copy-from-dom0.rst @@ -15,7 +15,7 @@ Copying files from dom0 To copy a file from dom0 to a VM, simply use ``qvm-copy-to-vm``: -.. code:: bash +.. code:: console qvm-copy-to-vm @@ -71,7 +71,7 @@ There should normally be few reasons for the user to want to copy anything from If you are determined to copy some files to dom0 anyway, you can use the following method. (If you want to copy text, first save it into a text file.) Run this command in a dom0 terminal: -.. code:: bash +.. code:: console qvm-run --pass-io 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0 @@ -79,7 +79,7 @@ If you are determined to copy some files to dom0 anyway, you can use the followi Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don’t want to use ``qvm-copy-to-vm``): -.. code:: bash +.. code:: console cat /path/to/file_in_dom0 | qvm-run --pass-io 'cat > /path/to/file_name_in_appvm' diff --git a/user/how-to-guides/how-to-enter-fullscreen-mode.rst b/user/how-to-guides/how-to-enter-fullscreen-mode.rst index e531a325..718c1608 100644 --- a/user/how-to-guides/how-to-enter-fullscreen-mode.rst +++ b/user/how-to-guides/how-to-enter-fullscreen-mode.rst @@ -31,7 +31,7 @@ You can always put a window into fullscreen mode in Xfce4 using the trusted wind As an alternative to the Xfce4 method, you can enable fullscreen mode for select VMs by creating the following entry in the ``/etc/qubes/guid.conf`` file in dom0: -.. code:: bash +.. code:: console VM: { personal: { @@ -47,7 +47,7 @@ The string ‘personal’ above is an example only and should be replaced by the One can also enable this functionality for all the VMs globally in the same file, by modifying the ‘global’ section: -.. code:: bash +.. code:: text global: { # default values diff --git a/user/how-to-guides/how-to-install-software.rst b/user/how-to-guides/how-to-install-software.rst index d85bb5ab..2e5f1763 100644 --- a/user/how-to-guides/how-to-install-software.rst +++ b/user/how-to-guides/how-to-install-software.rst @@ -36,7 +36,7 @@ Installing software from default repositories .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png :alt: `The Applications tab in Qube Settings `__ - + Installing software from other sources -------------------------------------- @@ -91,7 +91,7 @@ This method assumes that you are trying to follow instructions to install some p .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png :alt: `The Applications tab in Qube Settings `__ - + Troubleshooting --------------- @@ -155,7 +155,7 @@ There are three Qubes VM testing repositories (where ``*`` denotes the Release): To temporarily enable any of these repos, use the ``--enablerepo=`` option. Example commands: -.. code:: bash +.. code:: console sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing @@ -193,7 +193,7 @@ RPMFusion for Fedora templates If you would like to enable the `RPM Fusion `__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion `__ for details): -.. code:: bash +.. code:: console sudo dnf config-manager setopt rpmfusion-free.enabled=1 sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1 @@ -229,7 +229,7 @@ Root revert 2. In a dom0 terminal: - .. code:: bash + .. code:: console qvm-volume revert