From b53776e1ebc4ea1dd0a30c55ac0773c4aa6bdb54 Mon Sep 17 00:00:00 2001
From: parulin <161326115+parulin@users.noreply.github.com>
Date: Sun, 27 Jul 2025 02:03:08 -0400
Subject: [PATCH 1/4] Use console lexer instead of bash with a prompt
---
developer/building/development-workflow.rst | 4 +-
developer/building/qubes-builder-v2.rst | 16 +++----
developer/building/qubes-iso-building.rst | 2 +-
developer/code/code-signing.rst | 4 +-
developer/debugging/automated-tests.rst | 4 +-
developer/debugging/mount-lvm-image.rst | 12 ++---
developer/debugging/safe-remote-ttys.rst | 6 +--
developer/services/qrexec.rst | 22 +++++-----
developer/services/qrexec2.rst | 4 +-
introduction/faq.rst | 4 +-
project-security/security-pack.rst | 4 +-
project-security/verifying-signatures.rst | 44 +++++++++----------
user/advanced-topics/awesomewm.rst | 4 +-
.../disposable-customization.rst | 18 ++++----
.../how-to-install-software-in-dom0.rst | 2 +-
user/advanced-topics/i3.rst | 14 +++---
user/advanced-topics/kde.rst | 6 +--
user/advanced-topics/managing-vm-kernels.rst | 18 ++++----
user/advanced-topics/rpc-policy.rst | 2 +-
user/advanced-topics/salt.rst | 24 +++++-----
user/advanced-topics/standalones-and-hvms.rst | 6 +--
.../installation-guide-4.1.rst | 2 +-
.../installation-guide.rst | 2 +-
.../upgrade/2b2.rst | 2 +-
.../upgrade/3_0.rst | 2 +-
.../backup-emergency-restore-v2.rst | 14 +++---
.../backup-emergency-restore-v3.rst | 20 ++++-----
.../backup-emergency-restore-v4.rst | 32 +++++++-------
.../how-to-back-up-restore-and-migrate.rst | 2 +-
.../how-to-guides/how-to-install-software.rst | 14 +++---
user/how-to-guides/how-to-update.rst | 6 +--
user/security-in-qubes/ctap-proxy.rst | 6 +--
user/security-in-qubes/firewall.rst | 18 ++++----
user/security-in-qubes/firewall_4.1.rst | 12 ++---
user/security-in-qubes/split-gpg.rst | 24 +++++-----
user/templates/debian/debian-upgrade.rst | 22 +++++-----
user/templates/debian/debian.rst | 2 +-
user/templates/fedora/fedora-upgrade.rst | 26 +++++------
user/templates/fedora/fedora.rst | 2 +-
user/templates/minimal-templates.rst | 12 ++---
user/templates/templates.rst | 8 ++--
.../windows/qubes-windows-tools-4-0.rst | 4 +-
.../windows/qubes-windows-tools-4-1.rst | 14 +++---
user/templates/xfce-templates.rst | 8 ++--
.../app-menu-shortcut-troubleshooting.rst | 12 ++---
user/troubleshooting/disk-troubleshooting.rst | 2 +-
.../installation-troubleshooting.rst | 2 +-
.../resume-suspend-troubleshooting.rst | 14 +++---
user/troubleshooting/vm-troubleshooting.rst | 8 ++--
49 files changed, 256 insertions(+), 256 deletions(-)
diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst
index 64e546d8..9a7c61d6 100644
--- a/developer/building/development-workflow.rst
+++ b/developer/building/development-workflow.rst
@@ -17,7 +17,7 @@ The best way to write and contribute code is to create a git repo somewhere (e.g
**Example:**
-.. code:: bash
+.. code:: console
$ cd qubes-builder/artifacts/sources/qubes-manager
$ git remote add abel git@GitHub.com:abeluck/qubes-manager.git
@@ -290,7 +290,7 @@ You will also need to setup qrexec policy in dom0 (``/etc/qubes-rpc/policy/local
Usage:
-.. code:: bash
+.. code:: console
[user@source core-agent-linux]$ git remote add testbuilder "ext::git-qrexec testbuilder 3 core-agent-linux"
[user@source core-agent-linux]$ git push testbuilder master
diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst
index c9a23de7..572f430e 100644
--- a/developer/building/qubes-builder-v2.rst
+++ b/developer/building/qubes-builder-v2.rst
@@ -31,7 +31,7 @@ This is a simple setup using a docker executor. This is a good default choice; i
- .. code:: bash
+ .. code:: console
$ sudo dnf install $(cat dependencies-fedora.txt)
$ test -f /usr/share/qubes/marker-vm && sudo dnf install qubes-gpg-split
@@ -43,7 +43,7 @@ This is a simple setup using a docker executor. This is a good default choice; i
- .. code:: bash
+ .. code:: console
$ sudo apt install $(cat dependencies-debian.txt)
$ test -f /usr/share/qubes/marker-vm && sudo apt install qubes-gpg-split
@@ -60,7 +60,7 @@ This is a simple setup using a docker executor. This is a good default choice; i
4. If you haven’t previously used docker in the current qube, you need to set up some permissions. In particular, the user has to be added to the ``docker`` group:
- .. code:: bash
+ .. code:: console
$ sudo usermod -aG docker user
@@ -68,7 +68,7 @@ This is a simple setup using a docker executor. This is a good default choice; i
5. Finally, you need to generate a docker image:
- .. code:: bash
+ .. code:: console
$ tools/generate-container-image.sh docker
@@ -124,7 +124,7 @@ Using Builder v2
To fetch sources - in this example, for the ``core-admin-client`` package, you can use the following command:
-.. code:: bash
+.. code:: console
$ ./qb -c core-admin-client package fetch
@@ -133,21 +133,21 @@ This will fetch the sources for the listed package and place them in ``artifacts
To build a package (from sources in the ``artifacts/sources`` directory), use:
-.. code:: bash
+.. code:: console
$ ./qb -c core-admin-client package fetch prep build
or, if you want to build for a specific target (``host-fc37`` is a ``dom0`` using Fedora 37, ``vm-fc40`` would be a qube using Fedora 40 etc.), use:
-.. code:: bash
+.. code:: console
$ ./qb -c core-admin-client -d host-fc37 package fetch prep build
If you want to fetch the entire Qubes OS source use the following:
-.. code:: bash
+.. code:: console
$ ./qb package fetch
diff --git a/developer/building/qubes-iso-building.rst b/developer/building/qubes-iso-building.rst
index d733d3ab..e4b9cbe9 100644
--- a/developer/building/qubes-iso-building.rst
+++ b/developer/building/qubes-iso-building.rst
@@ -32,7 +32,7 @@ Create a standalone AppVM from the Fedora template. Set private storage to at le
Once you’ve built the development AppVM, open a Terminal window to it and install the necessary dependencies (see :doc:`QubesBuilder ` for more info):
-.. code:: bash
+.. code:: console
$ sudo dnf install git createrepo rpm-build rpm-sign make python3-sh rpmdevtools rpm-sign dialog perl-open python3-pyyaml perl-Digest-MD5 perl-Digest-SHA
diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst
index b27d91d9..abf896fc 100644
--- a/developer/code/code-signing.rst
+++ b/developer/code/code-signing.rst
@@ -13,7 +13,7 @@ Generating a Key
Alex Cabal has written an excellent `guide `__ on creating a PGP keypair. Below, we reproduce just the minimum steps in generating a keypair using GnuPG. Please read Cabal’s full guide for further important details.
-.. code:: bash
+.. code:: console
$ gpg --gen-key
gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
@@ -75,7 +75,7 @@ Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID** which i
-.. code:: bash
+.. code:: console
$ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827
gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com
diff --git a/developer/debugging/automated-tests.rst b/developer/debugging/automated-tests.rst
index 3240fca9..8a4cfabd 100644
--- a/developer/debugging/automated-tests.rst
+++ b/developer/debugging/automated-tests.rst
@@ -39,7 +39,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a
You can use ``python3 -m qubes.tests.run -h`` to get usage information:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ python3 -m qubes.tests.run -h
usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast]
@@ -82,7 +82,7 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information:
For instance, to run only the tests for the fedora-21 template, you can use the ``-l`` option, then filter the list:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21
network/VmNetworking_fedora-21/test_000_simple_networking
diff --git a/developer/debugging/mount-lvm-image.rst b/developer/debugging/mount-lvm-image.rst
index 5b90ba3d..dbc19b61 100644
--- a/developer/debugging/mount-lvm-image.rst
+++ b/developer/debugging/mount-lvm-image.rst
@@ -7,7 +7,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star
1: make the image available for qubesdb. From dom0 terminal:
-.. code:: bash
+.. code:: console
# Example: /dev/qubes_dom0/vm-debian-9-tmp-root
[user@dom0]$ dev=$(basename $(readlink /dev/YOUR_LVM_VG/YOUR_LVM_IMAGE))
@@ -16,7 +16,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star
2: Create a new disposable VM
-.. code:: bash
+.. code:: console
[user@dom0]$ qvm-run -v --dispvm=YOUR_DVM_TEMPLATE --service qubes.StartApp+xterm &
@@ -25,28 +25,28 @@ You want to read your LVM image (e.g., there is a problem where you can’t star
From the GUI, or from the command line:
-.. code:: bash
+.. code:: console
[user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev
4: Mount the partition you want to, and do what you want with it
-.. code:: bash
+.. code:: console
[user@dispXXXX]$ mount /dev/xvdiX /mnt/
5: Umount and kill the VM
-.. code:: bash
+.. code:: console
[user@dispXXXX]$ umount /mnt/
6: Remove the image from qubesdb
-.. code:: bash
+.. code:: console
[user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/
diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst
index a5afedff..f2da265e 100644
--- a/developer/debugging/safe-remote-ttys.rst
+++ b/developer/debugging/safe-remote-ttys.rst
@@ -17,7 +17,7 @@ To a different VM
As an example of forwarding terminal output to another VM on the same machine:
-.. code:: bash
+.. code:: console
$ mkfifo /tmp/foo
$ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' /dev/null 2>&1 &
@@ -31,7 +31,7 @@ To a different machine
In this case over SSH (from a network-connected VM):
-.. code:: bash
+.. code:: console
$ mkfifo /tmp/foo
$ qvm-run -p some-vm \
@@ -55,7 +55,7 @@ Terminal size
It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs). Depending on your shell, the size of your local (blind) terminal is likely stored in the ``$LINES`` and ``$COLUMNS`` variables.
-.. code:: bash
+.. code:: console
$ echo $COLUMNS $LINES
80 24
diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst
index 0ae67f06..236e3dec 100644
--- a/developer/services/qrexec.rst
+++ b/developer/services/qrexec.rst
@@ -20,7 +20,7 @@ Qrexec is built on top of *vchan*, a Xen library providing data links between VM
The ``qrexec-client`` command is used to make connections to VMs from dom0. For example, the following command creates an empty file called ``hello-world.txt`` in the home folder of ``someVM``:
-.. code:: bash
+.. code:: console
$ qrexec-client -e -d someVM user:'touch hello-world.txt'
@@ -28,7 +28,7 @@ The ``qrexec-client`` command is used to make connections to VMs from dom0. For
The string before the colon specifies which user will run the command. The ``-e`` flag tells ``qrexec-client`` to exit immediately after sending the execution request and receiving a status code from ``qrexec-agent`` (if the process creation succeeded). With this option, no further data is passed between the domains. The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
-.. code:: bash
+.. code:: console
$ qrexec-client -d someVM user:bash
@@ -85,7 +85,7 @@ Making an RPC call
From outside of dom0, RPC calls take the following form:
-.. code:: bash
+.. code:: console
$ qrexec-client-vm target_vm_name RPC_ACTION_NAME rpc_client_path client arguments
@@ -93,7 +93,7 @@ From outside of dom0, RPC calls take the following form:
For example:
-.. code:: bash
+.. code:: console
$ qrexec-client-vm work qubes.StartApp+firefox
@@ -103,7 +103,7 @@ Note that only stdin/stdout is passed between RPC server and client – notably,
It is also possible to call service without specific client program – in which case server stdin/out will be connected with the terminal:
-.. code:: bash
+.. code:: console
$ qrexec-client-vm target_vm_name RPC_ACTION_NAME
@@ -167,7 +167,7 @@ Be very careful when coding and adding a new RPC service. Unless the offered fun
For example, this command will run the ``firefox`` command in a DisposableVM based on ``work``:
-.. code:: bash
+.. code:: console
$ qvm-run --dispvm=work firefox
@@ -175,7 +175,7 @@ For example, this command will run the ``firefox`` command in a DisposableVM bas
By contrast, consider this command:
-.. code:: bash
+.. code:: console
$ qvm-run --dispvm=work --service qubes.StartApp+firefox
@@ -203,7 +203,7 @@ The argument is specified in the second column of the policy line, as +ARGUMENT.
When calling a service that takes an argument, just add the argument to the service name separated with ``+``.
-.. code:: bash
+.. code:: console
$ qrexec-client-vm target_vm_name RPC_ACTION_NAME+ARGUMENT
@@ -263,7 +263,7 @@ This will allow our client and server to communicate.
Before we make the call, ensure that the client and server scripts have executable permissions. Finally, invoke the RPC service.
-.. code:: bash
+.. code:: console
$ qrexec-client-vm anotherVM test.Add /usr/bin/our_test_add_client 1 2
@@ -309,7 +309,7 @@ Now we create the policy file in dom0, at ``/etc/qubes/policy.d/30-test.policy``
With this done, we can run some tests. Invoke RPC from ``source_vm1`` via
-.. code:: bash
+.. code:: console
[user@source_vm1] $ qrexec-client-vm target_vm test.File+testfile1
@@ -317,7 +317,7 @@ With this done, we can run some tests. Invoke RPC from ``source_vm1`` via
We should get the contents of ``/home/user/testfile1`` printed to the terminal. Invoking the service from ``source_vm2`` should result in a denial, but ``testfile2`` should work.
-.. code:: bash
+.. code:: console
[user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile1
Request refused
diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst
index 3ebc66e2..fbefc5a7 100644
--- a/developer/services/qrexec2.rst
+++ b/developer/services/qrexec2.rst
@@ -17,7 +17,7 @@ Typically, the first thing that a ``qrexec-client`` instance does is to send a r
E.g., to start a primitive shell in a VM type the following in Dom0 console:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d user:bash
@@ -147,7 +147,7 @@ We will show the necessary files to create a simple RPC call that adds two integ
- Policy file in dom0 (``/etc/qubes-rpc/policy/test.Add``)
- .. code:: bash
+ .. code::
$anyvm $anyvm ask
diff --git a/introduction/faq.rst b/introduction/faq.rst
index 2bb0ca44..65dcd406 100644
--- a/introduction/faq.rst
+++ b/introduction/faq.rst
@@ -570,7 +570,7 @@ For Debian:
- .. code:: bash
+ .. code:: console
$ sudo apt install vlc
@@ -589,7 +589,7 @@ For Fedora:
- .. code:: bash
+ .. code:: console
$ sudo dnf install vlc
diff --git a/project-security/security-pack.rst b/project-security/security-pack.rst
index d62a86e6..d0d3c7cc 100644
--- a/project-security/security-pack.rst
+++ b/project-security/security-pack.rst
@@ -79,7 +79,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and
4. Verify signed Git tags.
- .. code:: bash
+ .. code:: console
$ cd qubes-secpack/
$ git tag -v `git describe`
@@ -97,7 +97,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and
5. Verify detached PGP signatures.
- .. code:: bash
+ .. code:: console
$ cd canaries/
$ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt
diff --git a/project-security/verifying-signatures.rst b/project-security/verifying-signatures.rst
index 49bfd49d..0a140d7e 100644
--- a/project-security/verifying-signatures.rst
+++ b/project-security/verifying-signatures.rst
@@ -51,14 +51,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to
- If you’re on Qubes OS, it’s available in every qube (`except dom0 `__):
- .. code:: bash
+ .. code:: console
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc
- If you’re on Fedora, you can get it in the `distribution-gpg-keys `__ package:
- .. code:: bash
+ .. code:: console
$ dnf install distribution-gpg-keys
$ gpg2 --import /usr/share/distribution-gpg-keys/qubes/*
@@ -68,14 +68,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to
- Fetch it with GPG:
- .. code:: bash
+ .. code:: console
$ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
- Get it from a public `keyserver `__ (specified on first use with ``--keyserver `` along with keyserver options to include key signatures), e.g.:
- .. code:: bash
+ .. code:: console
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://keyserver.ubuntu.com --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
@@ -94,7 +94,7 @@ Once you have appropriate OpenPGP software installed, there are several ways to
Once you have the key as a file, import it:
- .. code:: bash
+ .. code:: console
$ gpg2 --import //qubes-master-signing-key.asc
@@ -213,7 +213,7 @@ Now, when you import any of the release signing keys and many Qubes team member
As a final sanity check, make sure the QMSK is in your keyring with the correct trust level.
-.. code:: bash
+.. code:: console
$ gpg2 -k "Qubes Master Signing Key"
pub rsa4096 2010-04-01 [SC]
@@ -242,21 +242,21 @@ After you have completed these two prerequisite steps, the next step is to obtai
- If you have access to an existing Qubes installation, the release keys are available in dom0 in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. These can be :ref:`copied ` into other qubes for further use. In addition, every other qube contains the release key corresponding to that installation’s release in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
- .. code:: bash
+ .. code:: console
$ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
- Fetch it with GPG:
- .. code:: bash
+ .. code:: console
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc
- Download it as a file. You can find the RSK for your Qubes release on the `downloads `__ page. You can also download all the currently used developers’ signing keys, RSKs, and the Qubes Master Signing Key from the :doc:`Qubes security pack ` and the `Qubes keyserver `__. Once you’ve downloaded your RSK, import it with GPG:
- .. code:: bash
+ .. code:: console
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc
@@ -265,7 +265,7 @@ After you have completed these two prerequisite steps, the next step is to obtai
Now that you have the correct RSK, you simply need to verify that it is signed by the QMSK:
-.. code:: bash
+.. code:: console
$ gpg2 --check-signatures "Qubes OS Release X Signing Key"
pub rsa4096 YYYY-MM-DD [SC]
@@ -281,7 +281,7 @@ This is just an example, so the output you receive may not look exactly the same
As a final sanity check, make sure the RSK is in your keyring with the correct trust level:
-.. code:: bash
+.. code:: console
$ gpg2 -k "Qubes OS Release X Signing Key"
pub rsa4096 YYYY-MM-DD [SC]
@@ -351,7 +351,7 @@ If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the dig
Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA-1, SHA-256, and SHA-512. One way to verify that the ISO you downloaded matches any of these hash values is by using the respective ``*sum`` command:
-.. code:: bash
+.. code:: console
$ md5sum -c Qubes-RX-x86_64.iso.DIGESTS
Qubes-RX-x86_64.iso: OK
@@ -371,7 +371,7 @@ The ``OK`` response tells us that the hash value for that particular hash functi
Another way is to use ``openssl`` to compute each hash value, then compare them to the contents of the digest file:
-.. code:: bash
+.. code:: console
$ openssl dgst -md5 Qubes-RX-x86_64.iso
MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82
@@ -387,7 +387,7 @@ Another way is to use ``openssl`` to compute each hash value, then compare them
However, it is possible that an attacker replaced ``Qubes-RX-x86_64.iso`` with a malicious ISO, computed the hash values for that malicious ISO, and replaced the values in ``Qubes-RX-x86_64.iso.DIGESTS`` with his own set of values. Therefore, we should also verify the authenticity of the listed hash values. Since ``Qubes-RX-x86_64.iso.DIGESTS`` is a clearsigned PGP file, we can use GPG to verify the signature in the digest file:
-.. code:: bash
+.. code:: console
$ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS
gpg: armor header: Hash: SHA256
@@ -423,7 +423,7 @@ Every Qubes ISO is released with a **detached PGP signature** file, which you ca
Download both the ISO and its signature file. Put both of them in the same directory, then navigate to that directory. Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
-.. code:: bash
+.. code:: console
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: armor header: Version: GnuPG v1
@@ -449,7 +449,7 @@ This section will walk through an example of re-verifying the installer on such
Now, our goal is to perform the same verification steps as we did with the original ISO, except, this time, we’ll be reading the installer data directly from the write-protected USB drive instead of from the original ISO file. First, let’s compute the SHA-256 hash value of the data on the drive. (This assumes you’re already familiar with `how to verify the cryptographic hash values of Qubes ISOs <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__.) In order to do this, we have to know the exact size, in bytes, of the original ISO. There are two ways to get this information: from the ISO itself and from the Qubes website. Here’s an example of the first way:
-.. code:: bash
+.. code:: console
$ dd if=/dev/sdX bs=1M count=$(stat -c %s /path/to/iso) iflag=count_bytes | sha256sum
@@ -472,7 +472,7 @@ Now, reading the number of bytes directly from the ISO is fine, but you may be c
Therefore, in order to make things a bit more difficult for your hypothetical adversary, you may instead wish to perform the re-verification in an environment that has never seen the original ISO, e.g., a separate offline computer or a fresh VM the storage space of which is too small to hold the ISO. (**Note:** If you’re doing this in Qubes, you can attach the block device from sys-usb to a separate new qube. You don’t have to perform the re-verification directly in sys-usb.) In that case, you’ll have to obtain the size of the ISO in bytes and enter it into the above command manually. You can, of course, obtain the size by simply using the ``stat -c %s /path/to/iso`` command from above on the machine that has the ISO. You can also obtain it from the Qubes website by hovering over any ISO download button on the `downloads page `__. (You can also view these values directly in the downloads page’s `source data `__.) Once you have the exact size of the ISO in bytes, simply insert it into the same command, for example:
-.. code:: bash
+.. code:: console
$ dd if=/dev/sdX bs=1M count=5791285248 iflag=count_bytes | sha256sum
@@ -481,7 +481,7 @@ If you wish to compute the values of other hash functions, you can replace ``sha
In addition to checking hash values, you can also use GnuPG to verify the detached PGP signature directly against the data on the USB drive. (This assumes you’re already familiar with `how to verify detached PGP signatures on Qubes ISOs <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__.)
-.. code:: bash
+.. code:: console
$ dd if=/dev/sdX bs=1M count= iflag=count_bytes | gpg -v --verify Qubes-RX-x86_64.iso.asc -
gpg: Signature made ` can be based on any :ref:`app qube `. You can also choose to use different :ref:`disposable templates ` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-prefs template_for_dispvms True
Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the ``appmenus-dispvm`` feature:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-features appmenus-dispvm 1
@@ -38,7 +38,7 @@ Creating a new disposable template
In Qubes 4.0, you’re no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-create --template --label red
[user@dom0 ~]$ qvm-prefs template_for_dispvms True
@@ -47,7 +47,7 @@ In Qubes 4.0, you’re no longer restricted to a single disposable template. Ins
Optionally, set it as the default disposable template:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qubes-prefs default_dispvm
@@ -66,7 +66,7 @@ It is possible to change the settings for each new disposable. This can be done
1. Start a terminal in the ```` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable ``appmenus-dispvm`` feature (as explained at the top), applications menu for this VM (````) will be “Disposable: ” (instead of “Domain: ”) and entries there will start new disposable based on that VM (````). Not in that VM (````) itself).
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-run -a gnome-terminal
@@ -173,7 +173,7 @@ Deleting disposables
While working in a disposable, you may want to open a document in another disposable. For this reason, the property ``default_dispvm`` may be set to the name of your disposable in a number of qubes:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-prefs | grep default_dispvm
default_dispvm -
@@ -181,14 +181,14 @@ While working in a disposable, you may want to open a document in another dispos
This will prevent the deletion of the disposable template. In order to fix this, you need to unset the ``default_dispvm`` property:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-prefs default_dispvm ""
You can then delete the disposable template:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-remove
This will completely remove the selected VM(s)
@@ -197,7 +197,7 @@ You can then delete the disposable template:
If you still encounter a problem, you may have forgotten to clean an entry. Looking at the system logs will help you:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ journalctl | tail
diff --git a/user/advanced-topics/how-to-install-software-in-dom0.rst b/user/advanced-topics/how-to-install-software-in-dom0.rst
index 8b5cb9c6..9da1995d 100644
--- a/user/advanced-topics/how-to-install-software-in-dom0.rst
+++ b/user/advanced-topics/how-to-install-software-in-dom0.rst
@@ -30,7 +30,7 @@ How to install a specific package
To install additional packages in dom0 (usually not recommended):
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update anti-evil-maid
diff --git a/user/advanced-topics/i3.rst b/user/advanced-topics/i3.rst
index 60e245bd..010dd203 100644
--- a/user/advanced-topics/i3.rst
+++ b/user/advanced-topics/i3.rst
@@ -8,7 +8,7 @@ i3 (window manager)
i3 is part of the stable repository (as of Qubes R3.1) and can be installed by using the :doc:`dom0 update mechanism `. To install the i3 window manager and the its Qubes specific configuration:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update i3 i3-settings-qubes
@@ -47,7 +47,7 @@ Getting the code
Clone the i3-qubes repository here:
-.. code:: bash
+.. code:: console
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
@@ -62,14 +62,14 @@ Building
You’ll need to install the build dependencies, which are listed in build-deps.list. You can verify them and then install them with:
-.. code:: bash
+.. code:: console
$ sudo dnf install -y $(cat build-deps.list)
This used to be more complicated, but I finally redid this and use the same buildsystem that’s used by Qubes OS for XFCE. It’s just a Makefile that helps you get the sources and start off the build:
-.. code:: bash
+.. code:: console
$ make get-sources
$ make verify-sources
@@ -86,14 +86,14 @@ You should now have your i3 rpm in ``./rpm/x86_64/i3-4.8-3.fc20.x86_64.rpm``. Pr
Now in dom0, copy in the rpm:
-.. code:: bash
+.. code:: console
$ qvm-run --pass-io 'cat ' > i3.rpm
Now that the rpm is in dom0 we can proceed with installing it. i3 has some dependencies that we can easily install with:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
@@ -102,7 +102,7 @@ Now that the rpm is in dom0 we can proceed with installing it. i3 has some depen
After that you can just install the generated rpm like any other local package:
-.. code:: bash
+.. code:: console
$ sudo yum localinstall i3.rpm
diff --git a/user/advanced-topics/kde.rst b/user/advanced-topics/kde.rst
index 8142f6e9..133ab912 100644
--- a/user/advanced-topics/kde.rst
+++ b/user/advanced-topics/kde.rst
@@ -12,7 +12,7 @@ Installation
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with R3.2, however, :doc:`XFCE is the new default desktop environment `. Nonetheless, it is still possible to install KDE by issuing this command in dom0:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update kde-settings-qubes
@@ -56,7 +56,7 @@ You can also change your default login manager (lightdm) to the new KDE default:
- disable the lightdm service:
- .. code:: bash
+ .. code:: console
$ sudo systemctl disable lightdm
@@ -64,7 +64,7 @@ You can also change your default login manager (lightdm) to the new KDE default:
- enable the sddm service:
- .. code:: bash
+ .. code:: console
$ sudo systemctl enable sddm
diff --git a/user/advanced-topics/managing-vm-kernels.rst b/user/advanced-topics/managing-vm-kernels.rst
index e1f83b51..086c71fa 100644
--- a/user/advanced-topics/managing-vm-kernels.rst
+++ b/user/advanced-topics/managing-vm-kernels.rst
@@ -22,7 +22,7 @@ By default, VMs kernels are provided by dom0. (See :ref:`here Building files for 4.1.9-6.pvops.qubes.x86_64 in /var/lib/qubes/vm-kernels/4.1.qubes
@@ -406,7 +406,7 @@ Update initramfs.
The output should look like this:
-.. code:: bash
+.. code:: console
$ sudo dkms autoinstall -k 3.16.0-4-amd64
diff --git a/user/advanced-topics/rpc-policy.rst b/user/advanced-topics/rpc-policy.rst
index 720ad929..1906cda7 100644
--- a/user/advanced-topics/rpc-policy.rst
+++ b/user/advanced-topics/rpc-policy.rst
@@ -12,7 +12,7 @@ This document explains the basics of RPC policies in Qubes. For more information
Here’s an example of an RPC policy file in dom0:
-.. code:: bash
+.. code:: console
[user@dom0 user ~]$ cat /etc/qubes-rpc/policy/qubes.FileCopy
(...)
diff --git a/user/advanced-topics/salt.rst b/user/advanced-topics/salt.rst
index 27baac14..a8f3bc1e 100644
--- a/user/advanced-topics/salt.rst
+++ b/user/advanced-topics/salt.rst
@@ -139,7 +139,7 @@ Enabling Top Files and Applying the States
Now, because we use custom extensions to manage top files (instead of just enabling them all), to enable a particular top file you should issue command:
-.. code:: bash
+.. code:: console
$ qubesctl top.enable my-new-vm
@@ -147,7 +147,7 @@ Now, because we use custom extensions to manage top files (instead of just enabl
To list all enabled top files:
-.. code:: bash
+.. code:: console
$ qubesctl top.enabled
@@ -155,7 +155,7 @@ To list all enabled top files:
And to disable one:
-.. code:: bash
+.. code:: console
$ qubesctl top.disable my-new-vm
@@ -163,7 +163,7 @@ And to disable one:
To apply the states to dom0 and all VMs:
-.. code:: bash
+.. code:: console
$ qubesctl --all state.apply
@@ -279,7 +279,7 @@ This should be put in ``/srv/salt/my-new-vm.sls`` or another ``.sls`` file. A se
To enable the particular top file you should issue the command:
-.. code:: bash
+.. code:: console
$ qubesctl top.enable my-new-vm
@@ -287,7 +287,7 @@ To enable the particular top file you should issue the command:
To apply the state:
-.. code:: bash
+.. code:: console
$ qubesctl state.apply
@@ -319,7 +319,7 @@ Then the appropriate top file (``/srv/salt/mc-everywhere.top``):
Now you need to enable the top file:
-.. code:: bash
+.. code:: console
$ qubesctl top.enable mc-everywhere
@@ -327,7 +327,7 @@ Now you need to enable the top file:
And apply the configuration:
-.. code:: bash
+.. code:: console
$ qubesctl --all state.apply
@@ -540,7 +540,7 @@ Whonix Workstation template
Updates dom0. Example (executed in dom0):
-.. code:: bash
+.. code:: console
$ sudo qubesctl --show-output state.sls update.qubes-dom0
@@ -552,7 +552,7 @@ Updates dom0. Example (executed in dom0):
Updates domUs. Example to update all templates (executed in dom0):
-.. code:: bash
+.. code:: console
$ sudo qubesctl --show-output --skip-dom0 --templates state.sls update.qubes-vm
@@ -644,7 +644,7 @@ If the log does not contain useful information:
-.. code:: bash
+.. code:: console
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command
@@ -668,7 +668,7 @@ Using fedora-24-minimal
The fedora-24-minimal package is missing the ``sudo`` package. You can install it via:
-.. code:: bash
+.. code:: console
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
diff --git a/user/advanced-topics/standalones-and-hvms.rst b/user/advanced-topics/standalones-and-hvms.rst
index e79c7578..3ebbfdab 100644
--- a/user/advanced-topics/standalones-and-hvms.rst
+++ b/user/advanced-topics/standalones-and-hvms.rst
@@ -223,7 +223,7 @@ Just like normal app qubes, HVMs can also be cloned either using the command ``q
The cloned qube will get identical root and private images and will essentially be identical to the original qube, except that it will get a different MAC address for the networking interface:
-.. code:: bash
+.. code:: console
[joanna@dom0 ~]$ qvm-prefs my-new-vm
autostart D False
@@ -313,7 +313,7 @@ The cloned qube will get identical root and private images and will essentially
Note that the MAC addresses differ between those two otherwise identical qubes. The IP addresses assigned by Qubes will also be different, of course, to allow networking to function properly:
-.. code:: bash
+.. code:: console
[joanna@dom0 ~]$ qvm-ls -n
@@ -325,7 +325,7 @@ Note that the MAC addresses differ between those two otherwise identical qubes.
If, for any reason, you would like to make sure that the two qubes have the same MAC address, you can use ``qvm-prefs`` to set a fixed MAC address:
-.. code:: bash
+.. code:: console
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
diff --git a/user/downloading-installing-upgrading/installation-guide-4.1.rst b/user/downloading-installing-upgrading/installation-guide-4.1.rst
index c21d9f6f..6bf9d1ee 100644
--- a/user/downloading-installing-upgrading/installation-guide-4.1.rst
+++ b/user/downloading-installing-upgrading/installation-guide-4.1.rst
@@ -51,7 +51,7 @@ Linux ISO to USB
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using ``dd``:
-.. code:: bash
+.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync
diff --git a/user/downloading-installing-upgrading/installation-guide.rst b/user/downloading-installing-upgrading/installation-guide.rst
index c3b6061a..97a2e148 100644
--- a/user/downloading-installing-upgrading/installation-guide.rst
+++ b/user/downloading-installing-upgrading/installation-guide.rst
@@ -51,7 +51,7 @@ Linux ISO to USB
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using ``dd``:
-.. code:: bash
+.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync
diff --git a/user/downloading-installing-upgrading/upgrade/2b2.rst b/user/downloading-installing-upgrading/upgrade/2b2.rst
index 1643876f..271a81f4 100644
--- a/user/downloading-installing-upgrading/upgrade/2b2.rst
+++ b/user/downloading-installing-upgrading/upgrade/2b2.rst
@@ -64,7 +64,7 @@ Installing new template
Qubes R2 Beta2 brings new fedora-18-x64 template (based on Fedora 18). You can install it from Qubes installation DVD. Insert installation DVD into your drive and issue following commands:
-.. code:: bash
+.. code:: console
$ sudo -s
# mkdir -p /mnt/cdrom
diff --git a/user/downloading-installing-upgrading/upgrade/3_0.rst b/user/downloading-installing-upgrading/upgrade/3_0.rst
index 01b0881f..afa024d4 100644
--- a/user/downloading-installing-upgrading/upgrade/3_0.rst
+++ b/user/downloading-installing-upgrading/upgrade/3_0.rst
@@ -150,7 +150,7 @@ Because of above limitations, you will need to configure some of those manually.
1. Check the VM network parameters, you will need them later:
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-ls -n custom-template
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
diff --git a/user/how-to-guides/backup-emergency-restore-v2.rst b/user/how-to-guides/backup-emergency-restore-v2.rst
index 3f1e17d6..ba3cc102 100644
--- a/user/how-to-guides/backup-emergency-restore-v2.rst
+++ b/user/how-to-guides/backup-emergency-restore-v2.rst
@@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
@@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ read -r backup_pass
@@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``private.img`` file which houses your data.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@@ -59,7 +59,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Decrypt the ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
@@ -84,7 +84,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Decompress the decrypted ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
@@ -99,7 +99,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Untar the decrypted and decompressed ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
@@ -126,7 +126,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Mount the private.img file and access your data.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
diff --git a/user/how-to-guides/backup-emergency-restore-v3.rst b/user/how-to-guides/backup-emergency-restore-v3.rst
index b5dd0b7e..07972158 100644
--- a/user/how-to-guides/backup-emergency-restore-v3.rst
+++ b/user/how-to-guides/backup-emergency-restore-v3.rst
@@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
@@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ read -r backup_pass
@@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``backup-header`` file, which contains basic information about your backup.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ openssl dgst -sha512 -hmac "$backup_pass" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
@@ -58,7 +58,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Read the ``backup-header``. You’ll need some of this information later. The file will look similar to this:
- .. code:: bash
+ .. code:: console
[user@restore ~]$ cat backup-header
version=3
@@ -73,7 +73,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Verify the integrity of the ``private.img`` file which houses your data.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@@ -91,7 +91,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Decrypt the ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -out private.img.dec
@@ -100,7 +100,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Decompress the decrypted ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ zforce private.img.dec
private.img.dec -- replaced with private.img.dec.gz
@@ -109,7 +109,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
**Note:** If your backup was compressed with a program other than ``gzip``, you must substitute the correct compression program. This information is contained in the ``backup-header`` file (see step 4). For example, if you used ``bzip2``, then you should do this:
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
@@ -118,7 +118,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
8. Untar the decrypted and decompressed ``private.img`` file.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
@@ -127,7 +127,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
9. Mount the private.img file and access your data.
- .. code:: bash
+ .. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/
diff --git a/user/how-to-guides/backup-emergency-restore-v4.rst b/user/how-to-guides/backup-emergency-restore-v4.rst
index f92d1318..7c5e7a80 100644
--- a/user/how-to-guides/backup-emergency-restore-v4.rst
+++ b/user/how-to-guides/backup-emergency-restore-v4.rst
@@ -19,7 +19,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
1. If you’re not on Qubes 4.X, :ref:`import and authenticate the Release 4 Signing Key `.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
@@ -27,14 +27,14 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
2. Download the ``scrypt`` RPM.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ dnf download scrypt
Or, if that doesn’t work:
- .. code:: bash
+ .. code:: console
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
@@ -42,7 +42,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
3. Verify the signature on the ``scrypt`` RPM.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
@@ -52,7 +52,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
4. Install ``rpmdevtools``.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ sudo dnf install rpmdevtools
@@ -60,7 +60,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
5. Extract the ``scrypt`` binary from the RPM and make it conveniently available.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
@@ -77,7 +77,7 @@ Emergency recovery instructions
1. Untar the backup metadata from the main backup file.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
backup-header backup-header.hmac qubes.xml.000.enc
@@ -89,7 +89,7 @@ Emergency recovery instructions
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ read -r backup_pass
@@ -98,7 +98,7 @@ Emergency recovery instructions
3. Verify the integrity of ``backup-header`` using ``backup-header.hmac`` (an encrypted *and integrity protected* version of ``backup-header``).
- .. code:: bash
+ .. code:: console
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
@@ -117,7 +117,7 @@ Emergency recovery instructions
4. Read ``backup-header``.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ cat backup-header
version=4
@@ -131,7 +131,7 @@ Emergency recovery instructions
5. Set ``backup_id`` to the value in the last line of ``backup-header``. (Note that there is a hyphen in ``backup-id`` in the file, whereas there is an underscore in ``backup_id`` in the variable you’re setting.)
- .. code:: bash
+ .. code:: console
[user@restore ~]$ backup_id=20230405T123455-1234
@@ -139,7 +139,7 @@ Emergency recovery instructions
6. Verify and decrypt, decompress, and extract the ``qubes.xml`` file.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
@@ -155,7 +155,7 @@ Emergency recovery instructions
7. Search inside of the ``qubes.xml`` file for the ``backup-path`` of the qube whose data you wish to restore. If you install the ``xmlstarlet`` package, the following command will convert ``qubes.xml`` to a friendlier listing for this purpose:
- .. code:: bash
+ .. code:: console
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
@@ -182,7 +182,7 @@ Emergency recovery instructions
The example output above shows that the backup file includes a qube named ``personal`` and a qube named ``vault``, with ``backup-path`` values of ``vm123/`` and ``vm321/`` respectively. (Every other listed qube was not selected to be included in the backup file.) Use the corresponding value to untar the necessary data files of the qube:
- .. code:: bash
+ .. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
@@ -190,7 +190,7 @@ Emergency recovery instructions
8. Verify and decrypt the backed up data, decompress it, and extract it.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
@@ -204,7 +204,7 @@ Emergency recovery instructions
9. Mount ``private.img`` and access your data.
- .. code:: bash
+ .. code:: console
[user@restore ~]$ sudo mkdir /mnt/img
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/
diff --git a/user/how-to-guides/how-to-back-up-restore-and-migrate.rst b/user/how-to-guides/how-to-back-up-restore-and-migrate.rst
index 480d60d0..ce043221 100644
--- a/user/how-to-guides/how-to-back-up-restore-and-migrate.rst
+++ b/user/how-to-guides/how-to-back-up-restore-and-migrate.rst
@@ -15,7 +15,7 @@ Backing up changes to dom0
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up. Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup. Here is an example of how to back up Qubes config files and RPC policies:
-.. code:: bash
+.. code:: console
$ mkdir -p ~/backup/etc/qubes/
$ cp -a /etc/qubes/* ~/backup/etc/qubes/
diff --git a/user/how-to-guides/how-to-install-software.rst b/user/how-to-guides/how-to-install-software.rst
index cb41b3e0..d85bb5ab 100644
--- a/user/how-to-guides/how-to-install-software.rst
+++ b/user/how-to-guides/how-to-install-software.rst
@@ -52,7 +52,7 @@ If you are still using the distribution package manager, updates will likely sti
If you are using another installation method fetching remote resources, you might still be able to use the updates proxy by making the tools aware of the proxy. For many tools, it is enough to export the following environment variables in your shell session before proceeding:
-.. code:: bash
+.. code:: console
$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
@@ -300,7 +300,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run:
- .. code:: bash
+ .. code:: console
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
@@ -346,14 +346,14 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
This is expected and you can safely continue.
Shutdown the template:
- .. code:: bash
+ .. code:: console
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
- .. code:: bash
+ .. code:: console
[user@snap-demo-app qube ~]$ snap install
@@ -377,7 +377,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
2. List the names of the available desktop shortcuts by running the command ``ls /usr/share/applications`` and find the exact name of the shortcut to the app you want to autostart:
- .. code:: bash
+ .. code:: console
[user@example-app qube ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop
@@ -390,7 +390,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
3. Create the autostart directory:
- .. code:: bash
+ .. code:: console
[user@example-app qube ~]$ mkdir -p ~/.config/autostart
@@ -398,7 +398,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
4. Make a link to the desktop app file you’d like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
- .. code:: bash
+ .. code:: console
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
diff --git a/user/how-to-guides/how-to-update.rst b/user/how-to-guides/how-to-update.rst
index 2deed43b..c10d84d6 100644
--- a/user/how-to-guides/how-to-update.rst
+++ b/user/how-to-guides/how-to-update.rst
@@ -159,7 +159,7 @@ First, ensure that your UpdateVM contains the ``fwupd-qubes-vm`` package. This p
In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update fwupd-qubes-dom0
@@ -167,7 +167,7 @@ In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
Once the package is installed:
-.. code:: bash
+.. code:: console
$ sudo qubes-fwupdmgr get-devices
@@ -185,7 +185,7 @@ If so, `adjust your BIOS settings > /rw/config/qubes-firewall-user-script
@@ -154,7 +154,7 @@ In order to allow networking from qube A (client) to qube B (server) follow thes
-.. code:: bash
+.. code:: console
[user@B ~]$ sudo -i
[root@B user]# echo "nft add rule qubes custom-input ip saddr 10.137.2.25 accept" >> /rw/config/rc.local
@@ -181,7 +181,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In untrusted, use the Qubes tool ``qvm-connect-tcp``:
- .. code:: bash
+ .. code:: console
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
@@ -195,7 +195,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
Here ``@default`` is used to hide the destination qube which is specified in the Qubes RPC policy by ``target=mytcp-service``. Equivalent call is to use the tool as follow:
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::444
@@ -215,7 +215,7 @@ Consider now the case where someone prefers to specify the destination qube and
in ``/etc/qubes/policy.d/30-user-networking.policy`` and in untrusted, use the tool as follow:
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp 10444:mytcp-service:444
@@ -235,7 +235,7 @@ One can go further than the previous examples by redirecting different ports to
In that case, calling ``qvm-connect-tcp`` like previous examples, will still bind TCP port ``444`` of ``mytcp-service`` to ``untrusted`` but now, calling it with port ``445``
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::445
@@ -420,7 +420,7 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
Once you have confirmed that the counters increase, store the commands used in the previous steps in ``/rw/config/qubes-firewall-user-script`` so they get set on sys-net start-up:
-.. code:: bash
+.. code:: console
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
@@ -479,7 +479,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
Once you have confirmed that the counters increase, store these commands in the script ``/rw/config/qubes-firewall-user-script``
-.. code:: bash
+.. code:: console
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
@@ -522,7 +522,7 @@ The according rule to allow the traffic is:
To make it persistent, you need to add this command in the script ``/rw/config/rc.local``:
-.. code:: bash
+.. code:: console
[user@qubeDEST user]$ sudo -i
[root@qubeDEST user]# echo 'nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept' >> /rw/config/rc.local
diff --git a/user/security-in-qubes/firewall_4.1.rst b/user/security-in-qubes/firewall_4.1.rst
index 75a843b4..d22d22be 100644
--- a/user/security-in-qubes/firewall_4.1.rst
+++ b/user/security-in-qubes/firewall_4.1.rst
@@ -131,7 +131,7 @@ In order to allow networking between qubes A and B follow these steps:
-.. code:: bash
+.. code:: console
[user@sys-firewall ~]$ sudo bash
[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script
@@ -143,7 +143,7 @@ In order to allow networking between qubes A and B follow these steps:
-.. code:: bash
+.. code:: console
[user@B ~]$ sudo bash
[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local
@@ -171,7 +171,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In untrusted, use the Qubes tool ``qvm-connect-tcp``:
- .. code:: bash
+ .. code:: console
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
@@ -185,7 +185,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
Here ``@default`` is used to hide the destination qube which is specified in the Qubes RPC policy by ``target=mytcp-service``. Equivalent call is to use the tool as follow:
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::444
@@ -205,7 +205,7 @@ Consider now the case where someone prefers to specify the destination qube and
in ``/etc/qubes/policy.d/30-user-networking.policy`` and in untrusted, use the tool as follow:
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp 10444:mytcp-service:444
@@ -225,7 +225,7 @@ One can go further than the previous examples by redirecting different ports to
In that case, calling ``qvm-connect-tcp`` like previous examples, will still bind TCP port ``444`` of ``mytcp-service`` to ``untrusted`` but now, calling it with port ``445``
-.. code:: bash
+.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::445
diff --git a/user/security-in-qubes/split-gpg.rst b/user/security-in-qubes/split-gpg.rst
index 70d1a349..02de91ea 100644
--- a/user/security-in-qubes/split-gpg.rst
+++ b/user/security-in-qubes/split-gpg.rst
@@ -29,7 +29,7 @@ Configuring Split GPG
In dom0, make sure the ``qubes-gpg-split-dom0`` package is installed.
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0
@@ -38,7 +38,7 @@ Make sure you have the ``qubes-gpg-split`` package installed in the template you
For Debian or Whonix:
-.. code:: bash
+.. code:: console
[user@debian-10 ~]$ sudo apt install qubes-gpg-split
@@ -46,7 +46,7 @@ For Debian or Whonix:
For Fedora:
-.. code:: bash
+.. code:: console
[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
@@ -60,7 +60,7 @@ First, create a dedicated app qube for storing your keys (we will be calling it
Make sure that gpg is installed there. At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later. To check which private keys are in your GPG keyring, use:
-.. code:: bash
+.. code:: console
[user@work-gpg ~]$ gpg -K
/home/user/.gnupg/secring.gpg
@@ -73,7 +73,7 @@ Make sure that gpg is installed there. At this stage you can add the private key
This is pretty much all that is required. However, you might want to modify the default timeout: this tells the backend for how long the user’s approval for key access should be valid. (The default is 5 minutes.) You can change this via the ``QUBES_GPG_AUTOACCEPT`` environment variable. You can override it e.g. in ``~/.profile``:
-.. code:: bash
+.. code:: console
[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
@@ -88,7 +88,7 @@ Configuring the client apps to use Split GPG backend
Normally it should be enough to set the ``QUBES_GPG_DOMAIN`` to the GPG backend domain name and use ``qubes-gpg-client`` in place of ``gpg``, e.g.:
-.. code:: bash
+.. code:: console
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ gpg -K
@@ -116,7 +116,7 @@ Advanced Configuration
The ``qubes-gpg-client-wrapper`` script sets the ``QUBES_GPG_DOMAIN`` variable automatically based on the content of the file ``/rw/config/gpg-split-domain``, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
-.. code:: bash
+.. code:: console
[user@work-email ~]$ sudo bash
[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
@@ -158,7 +158,7 @@ In ``work-email``, use the Thunderbird config editor (found at the bottom of pre
You need to obtain your key ID which should be **exactly 16 characters**. Enter the command ``qubes-gpg-client-wrapper -K --keyid-format long``:
-.. code:: bash
+.. code:: console
[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
/home/user/.gnupg/pubring.kbx
@@ -170,7 +170,7 @@ You need to obtain your key ID which should be **exactly 16 characters**. Enter
-.. code:: bash
+.. code:: console
[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
@@ -218,7 +218,7 @@ The Keybase service does not preserve/pass the ``QUBES_GPG_DOMAIN`` environment
The following command will configure Keybase to use ``/usr/bin/qubes-gpg-client-wrapper`` instead of its built-in GPG client:
-.. code:: bash
+.. code:: console
$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
@@ -246,7 +246,7 @@ Git can be configured to utilize Split GPG, something useful if you would like t
Your key id is the public id of your signing key, which can be found by running ``qubes-gpg-client --list-keys``. In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
-.. code:: bash
+.. code:: console
[user@work-email ~]$ qubes-gpg-client --list-keys
/home/user/.gnupg/pubring.kbx
@@ -276,7 +276,7 @@ Importing public keys
Use ``qubes-gpg-import-key`` in the client app qube to import the key into the GPG backend VM.
-.. code:: bash
+.. code:: console
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
diff --git a/user/templates/debian/debian-upgrade.rst b/user/templates/debian/debian-upgrade.rst
index 9e921ff9..6f8e1e5d 100644
--- a/user/templates/debian/debian-upgrade.rst
+++ b/user/templates/debian/debian-upgrade.rst
@@ -18,7 +18,7 @@ Summary instructions for Debian templates
**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-``, or ``debian-``, where ```` is the Debian version number *from* which you are upgrading, and ```` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See `release-specific notes <#release-specific-notes>`__ for any instructions specific to your particular release.
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-clone debian- debian-
[user@dom0 ~]$ qvm-run -a debian- gnome-terminal
@@ -42,14 +42,14 @@ These instructions will show you how to upgrade Debian templates. The same gener
1. Ensure the existing template is not running.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-shutdown debian-
2. Clone the existing template and start a terminal in the new template.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-clone debian- debian-
[user@dom0 ~]$ qvm-run -a debian- gnome-terminal
@@ -57,7 +57,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
3. Update your ``apt`` repositories to use the new release’s code name instead of the old release’s code name. (This can be done manually with a text editor, but ``sed`` can be used to automatically update the files.)
- .. code:: bash
+ .. code:: console
[user@debian- ~]$ sudo sed -i 's///g' /etc/apt/sources.list
[user@debian- ~]$ sudo sed -i 's///g' /etc/apt/sources.list.d/qubes-r4.list
@@ -66,7 +66,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
4. Update the package lists and upgrade. During the process, it may prompt you to overwrite the file ``qubes-r4.list``. You should overwrite this file.
- .. code:: bash
+ .. code:: console
[user@debian- ~]$ sudo apt update
[user@debian- ~]$ sudo apt upgrade
@@ -76,7 +76,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
5. (Optional) Remove unnecessary packages that were previously installed.
- .. code:: bash
+ .. code:: console
[user@debian- ~]$ sudo apt-get autoremove
@@ -84,7 +84,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
6. (Optional) Clean cached packages from ``/var/cache/apt``.
- .. code:: bash
+ .. code:: console
[user@debian- ~]$ sudo apt-get clean
@@ -92,7 +92,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
7. (Optional) Trim the new template. (This should :ref:`no longer be necessary `, but it does not hurt. Some users have `reported `__ that it makes a difference.)
- .. code:: bash
+ .. code:: console
[user@debian- ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-
@@ -102,7 +102,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
8. Shut down the new template.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-shutdown debian-
@@ -111,7 +111,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
10. (Optional) Make the new template the global default.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qubes-prefs --set default_template debian-
@@ -140,7 +140,7 @@ Please see `Debian’s Bullseye upgrade instructions ` a specific Debian template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
-.. code:: bash
+.. code:: console
$ qvm-template install XX
diff --git a/user/templates/fedora/fedora-upgrade.rst b/user/templates/fedora/fedora-upgrade.rst
index a0e2e61f..27af9c9b 100644
--- a/user/templates/fedora/fedora-upgrade.rst
+++ b/user/templates/fedora/fedora-upgrade.rst
@@ -18,7 +18,7 @@ Summary instructions for standard Fedora templates
**Note:** The prompt on each line indicates where each command should be entered: ``dom0``, ``fedora-``, or ``fedora-``, where ```` is the Fedora version number *from* which you are upgrading, and ```` is the Fedora version number *to* which you are upgrading.
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-clone fedora- fedora-
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
@@ -47,14 +47,14 @@ These instructions will show you how to upgrade the standard Fedora template. Th
1. Ensure the existing template is not running.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-shutdown fedora-
2. Clone the existing template and start a terminal in the new template.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-clone fedora- fedora-
[user@dom0 ~]$ qvm-run -a fedora- gnome-terminal
@@ -62,7 +62,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
3. Attempt the upgrade process in the new template.
- .. code:: bash
+ .. code:: console
[user@fedora- ~]$ sudo dnf clean all
[user@fedora- ~]$ sudo dnf --releasever= distro-sync --best --allowerasing
@@ -86,7 +86,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
- If ``dnf`` reports that you do not have enough free disk space to proceed with the upgrade process, create an empty file in dom0 to use as a cache and attach it to the template as a virtual disk.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
@@ -94,7 +94,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
Then reattempt the upgrade process, but this time use the virtual disk as a cache.
- .. code:: bash
+ .. code:: console
[user@fedora- ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora- ~]$ sudo mount /dev/xvdi /mnt/removable
@@ -111,7 +111,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
4. Check that you are on the correct (new) Fedora release. Do this check only after completing the upgrade process. This is *not* a troubleshooting procedure for fixing download issues from the repository. This check simply verifies that your clone has successfully been upgraded.
- .. code:: bash
+ .. code:: console
[user@fedora- ~]$ cat /etc/fedora-release
@@ -119,7 +119,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
5. (Optional) Trim the new template. (This should :ref:`no longer be necessary `, but it does not hurt. Some users have `reported `__ that it makes a difference.)
- .. code:: bash
+ .. code:: console
[user@fedora- ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown fedora-
@@ -129,14 +129,14 @@ These instructions will show you how to upgrade the standard Fedora template. Th
6. Shut down the new template.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-shutdown fedora-
7. Remove the cache file, if you created one.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
@@ -144,7 +144,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
8. Set the template-name, which is used by the Qubes updater.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qvm-features fedora- template-name fedora-
@@ -153,7 +153,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
10. (Optional) Make the new template the global default.
- .. code:: bash
+ .. code:: console
[user@dom0 ~]$ qubes-prefs --set default_template fedora-
@@ -168,7 +168,7 @@ Summary instructions for Fedora Minimal templates
**Note:** The prompt on each line indicates where each command should be entered: ``dom0``, ``fedora-``, or ``fedora-``, where ```` is the Fedora version number *from* which you are upgrading, and ```` is the Fedora version number *to* which you are upgrading.
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-clone fedora--minimal fedora--minimal
[user@dom0 ~]$ qvm-run -u root -a fedora--minimal xterm
diff --git a/user/templates/fedora/fedora.rst b/user/templates/fedora/fedora.rst
index 72504b4a..44adc0f3 100644
--- a/user/templates/fedora/fedora.rst
+++ b/user/templates/fedora/fedora.rst
@@ -11,7 +11,7 @@ Installing
To :ref:`install ` a specific Fedora template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
-.. code:: bash
+.. code:: console
$ qvm-template install XX
diff --git a/user/templates/minimal-templates.rst b/user/templates/minimal-templates.rst
index 44bc8ad4..7ae018e1 100644
--- a/user/templates/minimal-templates.rst
+++ b/user/templates/minimal-templates.rst
@@ -44,21 +44,21 @@ Installation
The minimal templates can be installed with the following type of command:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template---minimal
If your desired version is not found, it may still be in :doc:`testing `. You may wish to try again with the testing repository enabled:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template---minimal
If you would like to install a community distribution, try the install command by enabling the community repository:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template---minimal
@@ -71,7 +71,7 @@ Passwordless root
It is an intentional design choice for :doc:`Passwordless Root Access in VMs ` to be optional in minimal templates. Since the minimal templates are *minimal*, they are not configured for passwordless root by default. To update or install packages, execute the following command in dom0:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-run -u root --minimal xterm
@@ -102,7 +102,7 @@ Fedora
The following list provides an overview of which packages are needed for which purpose. As usual, the required packages are to be installed in the running template with the following command (replace ``packages`` with a space-delimited list of packages to be installed):
-.. code:: bash
+.. code:: console
[user@your-new-clone ~]$ sudo dnf install packages
@@ -188,7 +188,7 @@ Debian
The following list provides an overview of which packages are needed for which purpose. As usual, the required packages are to be installed in the running template with the following command (replace ``packages`` with a space-delimited list of packages to be installed):
-.. code:: bash
+.. code:: console
[user@your-new-clone ~]$ sudo apt install packages
diff --git a/user/templates/templates.rst b/user/templates/templates.rst
index 941690d3..dfa588a3 100644
--- a/user/templates/templates.rst
+++ b/user/templates/templates.rst
@@ -103,7 +103,7 @@ You can manage your templates using the ``Qubes Template Manager``, a GUI tool a
At the command line in dom0, ``qvm-template list --available`` will show available templates. To install a template, use:
-.. code:: bash
+.. code:: console
$ qvm-template install
@@ -113,7 +113,7 @@ You can also use ``qvm-template`` to upgrade or reinstall templates.
Repository (repo) definitions are stored in dom0 in ``/etc/qubes/repo-templates`` and associated keys in ``/etc/qubes/repo-templates/keys``. There are additional repos for testing releases and community templates. To temporarily enable any of these repos, use the ``--enablerepo=`` option. E.g. :
-.. code:: bash
+.. code:: console
$ qvm-template --enablerepo qubes-templates-community install
@@ -164,7 +164,7 @@ To remove a template, the graphical ``Qube Manager`` (Qubes Menu > Qubes Tools >
Alternatively, to remove a template via the command line in dom0:
-.. code:: bash
+.. code:: console
$ qvm-template remove
@@ -172,7 +172,7 @@ Alternatively, to remove a template via the command line in dom0:
is the first column from the output of:
-.. code:: bash
+.. code:: console
$ qvm-template list --installed
diff --git a/user/templates/windows/qubes-windows-tools-4-0.rst b/user/templates/windows/qubes-windows-tools-4-0.rst
index e50ed0b2..6f86c3af 100644
--- a/user/templates/windows/qubes-windows-tools-4-0.rst
+++ b/user/templates/windows/qubes-windows-tools-4-0.rst
@@ -269,13 +269,13 @@ Once you start a Windows-based AppVM with Qubes Tools installed, you can easily
Also, the inter-VM services work as usual – e.g. to request opening a document or URL in the Windows AppVM from another VM:
-.. code:: bash
+.. code:: console
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
-.. code:: bash
+.. code:: console
[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com
diff --git a/user/templates/windows/qubes-windows-tools-4-1.rst b/user/templates/windows/qubes-windows-tools-4-1.rst
index 291d6a31..fdf6258b 100644
--- a/user/templates/windows/qubes-windows-tools-4-1.rst
+++ b/user/templates/windows/qubes-windows-tools-4-1.rst
@@ -136,7 +136,7 @@ The Xen PV Drivers bundled with QWT are signed by a Linux Foundation certificate
**Warning:** it is recommended to increase the default value of Windows VM’s ``qrexec_timeout`` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM’s virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when ``qrexec`` is not yet running, so timeout may occur with the default value. To change the property use this command in ``dom0``: *(where* ```` *is the name of your Windows VM)*
-.. code:: bash
+.. code:: console
[user@dom0 ~] $ qvm-prefs qrexec_timeout 7200
@@ -215,14 +215,14 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as ``qrexec_installed``, ``guiagent_installed``, and ``default_user``. This can be verified (but is not required) using the ``qvm-prefs`` command *(where* ```` *is the name of your Windows VM)*:
- .. code:: bash
+ .. code:: console
[user@dom0 ~] $ qvm-prefs
It is advisable to set some other parameters in order to enable audio and USB block device access, synchronize the Windows clock with the Qubes clock, and so on:
- .. code:: bash
+ .. code:: console
[user@dom0 ~] $ qvm-features audio-model ich9
[user@dom0 ~] $ qvm-features stubdom-qrexec 1
@@ -231,7 +231,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
For audio, the parameter ``audio-model`` can be selected as ``ich6`` or ``ich9``; select the value that gives the best audio quality. Audio quality may also be improved by setting the following parameters, but this can depend on the Windows version and on your hardware:
- .. code:: bash
+ .. code:: console
[user@dom0 ~] $ qvm-features timer-period 1000
[user@dom0 ~] $ qvm-features out.latency 10000
@@ -295,7 +295,7 @@ Using Windows AppVMs in seamless mode
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the ``-a`` switch used here, which will auto-start the VM if it is not running):
-.. code:: bash
+.. code:: console
[user@dom0 ~] $ qvm-run -a my-win-appvm explorer.exe
@@ -305,7 +305,7 @@ Once you start a Windows-based AppVM with Qubes Tools installed, you can easily
Also, the inter-VM services work as usual – e.g. to request opening a document or URL in the Windows AppVM from another VM:
-.. code:: bash
+.. code:: console
[user@dom0 ~] $ qvm-open-in-vm my-win-appvm roadmap.pptx
@@ -554,7 +554,7 @@ Updates
When we publish a new QWT version, it’s usually pushed to the ``current-testing`` or ``unstable`` repository first. To use versions from current-testing, run this in dom0:
-.. code:: bash
+.. code:: console
[user@dom0 ~] $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
diff --git a/user/templates/xfce-templates.rst b/user/templates/xfce-templates.rst
index 65b6fe46..8618ce68 100644
--- a/user/templates/xfce-templates.rst
+++ b/user/templates/xfce-templates.rst
@@ -13,28 +13,28 @@ Installation
The Fedora Xfce templates can be installed with the following command (where ``X`` is your desired distro and version number):
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
If your desired version is not found, it may still be in :doc:`testing `. You may wish to try again with the testing repository enabled:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-X-xfce
If you would like to install a community distribution such as Gentoo, try the install command by enabling the community repository:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
If your desired version is not found, it may still be in :doc:`testing `. You may wish to try again with the testing repository enabled:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing qubes-template-X-xfce
diff --git a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
index a63e4c99..7fc3bf58 100644
--- a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
+++ b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
@@ -27,7 +27,7 @@ With the command-line interface
To update the list of available applications, use the ``qvm-sync-appmenus`` command in dom0, replacing ```` by the qube name:
-.. code:: bash
+.. code:: console
$ qvm-sync-appmenus
@@ -35,7 +35,7 @@ To update the list of available applications, use the ``qvm-sync-appmenus`` comm
When using the *Refresh Applications* button in a qube’s settings, the command ``qvm-sync-appmenus`` is used at least one time. When refreshing an AppVM application, it is also run against the template. So the console equivalent of clicking the *Refresh button* is the following (always in dom0):
-.. code:: bash
+.. code:: console
$ qvm-sync-appmenus
$ qvm-sync-appmenus
@@ -44,7 +44,7 @@ When using the *Refresh Applications* button in a qube’s settings, the command
In dom0, the ``qvm-appmenus`` tool allows the user to see the list of available applications (unstable feature), the whitelist of currently show application (unstable feature) and to change this list:
-.. code:: bash
+.. code:: console
$ qvm-appmenus --set-whitelist
@@ -152,7 +152,7 @@ What if a removed application is still in the app menu?
First, try this in dom0:
-.. code:: bash
+.. code:: console
$ qvm-appmenus --update --force
@@ -160,7 +160,7 @@ First, try this in dom0:
You can also try:
-.. code:: bash
+.. code:: console
$ qvm-appmenus --remove
@@ -186,7 +186,7 @@ The line starting with ``Exec=`` points out the exact command run by dom0 to sta
It’s possible to run the command to check the output, by copying this line without ``Exec=``, and remove ``-q`` (quiet option). But it could be more useful to run it in the qube, with the ``qubes.StartApp`` service:
-.. code:: bash
+.. code:: console
$ /etc/qubes-rpc/qubes.StartApp
diff --git a/user/troubleshooting/disk-troubleshooting.rst b/user/troubleshooting/disk-troubleshooting.rst
index 18ce94e1..472569c2 100644
--- a/user/troubleshooting/disk-troubleshooting.rst
+++ b/user/troubleshooting/disk-troubleshooting.rst
@@ -67,7 +67,7 @@ The above steps applies to old VM disks format. These steps may work on Qubes 4.
For example:
-.. code:: bash
+.. code:: console
$ sudo lvs
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
diff --git a/user/troubleshooting/installation-troubleshooting.rst b/user/troubleshooting/installation-troubleshooting.rst
index 3c525416..99c3c5af 100644
--- a/user/troubleshooting/installation-troubleshooting.rst
+++ b/user/troubleshooting/installation-troubleshooting.rst
@@ -31,7 +31,7 @@ There are a variety of other problems that could arise when using a USB installa
This error message is related to the faulty creation of the USB installation medium. If you receive this error message during installation, please make sure you have followed the instructions on :ref:`how to write your ISO to a USB key `. Specifically, the ``dd`` command listed on that page has been verified to solve this issue on multiple Qubes installation versions.
-.. code:: bash
+.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
diff --git a/user/troubleshooting/resume-suspend-troubleshooting.rst b/user/troubleshooting/resume-suspend-troubleshooting.rst
index 792f0680..09d95bf5 100644
--- a/user/troubleshooting/resume-suspend-troubleshooting.rst
+++ b/user/troubleshooting/resume-suspend-troubleshooting.rst
@@ -21,7 +21,7 @@ First, determine which kernel module corresponds to your wireless card. There ar
The easiest is via the output of ``lspci -k`` in your sys-net VM:
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
@@ -64,7 +64,7 @@ You can check which drivers are currently loaded with ``lsmod``, and view detail
For example, we list what modules we have loaded:
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ lsmod
Module Size Used by
@@ -78,7 +78,7 @@ For example, we list what modules we have loaded:
and check one:
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation
@@ -91,7 +91,7 @@ Hey, it’s our wireless driver!
Now, check if reloading the module makes wireless work again:
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
@@ -102,7 +102,7 @@ and try reconnecting to a network that is known to work.
If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi:
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation
@@ -111,7 +111,7 @@ If that is successful, see below about having Qubes automatically reload the dri
-.. code:: bash
+.. code:: console
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
@@ -128,7 +128,7 @@ If reloading the driver (which resets the hardware into a known-state) resolves
In the above example, it would look like this:
-.. code:: bash
+.. code:: console
[user@sys-net config]$ cat /rw/config/suspend-module-blacklist
# You can list here modules you want to be unloaded before going to sleep. This
diff --git a/user/troubleshooting/vm-troubleshooting.rst b/user/troubleshooting/vm-troubleshooting.rst
index e8c7cf76..6f80bf39 100644
--- a/user/troubleshooting/vm-troubleshooting.rst
+++ b/user/troubleshooting/vm-troubleshooting.rst
@@ -33,7 +33,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
1. Check the state of ``installed_by_rpm``
- .. code:: bash
+ .. code:: console
$ qvm-prefs template-vm-name
@@ -41,7 +41,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
2. If ``installed_by_rpm - True``, mark the template as not installed by package manager
- .. code:: bash
+ .. code:: console
$ qvm-prefs template-vm-name installed_by_rpm false
@@ -53,7 +53,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
- If ``installed_by_rpm - False``, remove the template like you would a regular qube:
- .. code:: bash
+ .. code:: console
$ qvm-remove template-vm-name
@@ -95,7 +95,7 @@ If the error occurs as a result of too little initial memory, increase the initi
For example:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
Using sys-whonix as UpdateVM to download updates for Dom0; this may take some time...
From ba399ac488a2a308e7b882883ead9a60e4243be8 Mon Sep 17 00:00:00 2001
From: parulin <161326115+parulin@users.noreply.github.com>
Date: Wed, 30 Jul 2025 09:43:09 -0400
Subject: [PATCH 2/4] Correct code-block lexers
Changing `bash` lexer to `console` because it is appropriate most of
the time. Then after a manual review, some lexer have been changed.
I used `text` each time I was unsure, and for prompt outputs.
The page `/developer/building/qubes-iso-building.rst` still need to be
reviewed (look for lines starting with `$ #`).
I'm not sure about the Windows pages, should we use
[doscon](https://pygments.org/docs/lexers/#pygments.lexers.shell.MSDOSSessionLexer)
or `powershell`?
Is there an appropriate lexer for `guid.conf` content?
**Statistics - Before**
870 bash
9 python
9 c
2 yaml
**Statistics - After**
684 console
111 text
44 bash
16 yaml
9 systemd
9 c
8 python
4 ini
4 doscon
2 markdown
2 desktop
1 xorg.conf
1 xml+jinja
1 xml
1 kconfig
1 html
This suggests that the default lexer should be `console`.
---
developer/building/development-workflow.rst | 107 +++++++-------
developer/building/qubes-builder-v2.rst | 14 +-
developer/building/qubes-builder.rst | 40 ++---
developer/building/qubes-iso-building.rst | 84 +++++------
developer/code/code-signing.rst | 34 ++---
developer/code/source-code.rst | 8 +-
developer/debugging/automated-tests.rst | 26 ++--
developer/debugging/safe-remote-ttys.rst | 2 +-
developer/debugging/test-bench.rst | 70 ++++-----
developer/debugging/windows-debugging.rst | 10 +-
.../general/developing-gui-applications.rst | 10 +-
developer/general/gsoc.rst | 44 +++---
developer/general/usability-ux.rst | 6 +-
developer/releases/1_0/release-notes.rst | 4 +-
developer/releases/4_0/release-notes.rst | 8 +-
developer/releases/4_2/release-notes.rst | 10 +-
developer/services/qrexec-internals.rst | 10 +-
developer/services/qrexec-socket-services.rst | 62 ++++----
developer/services/qrexec.rst | 16 +-
developer/services/qrexec2.rst | 14 +-
developer/system/networking.rst | 16 +-
developer/system/template-manager.rst | 2 +-
developer/system/vm-sudo.rst | 6 +-
introduction/faq.rst | 14 +-
introduction/issue-tracking.rst | 6 +-
introduction/statistics.rst | 2 +-
project-security/security-pack.rst | 52 +++----
project-security/security.rst | 4 +-
project-security/verifying-signatures.rst | 34 ++---
user/advanced-topics/bind-dirs.rst | 14 +-
user/advanced-topics/config-files.rst | 14 +-
.../disposable-customization.rst | 10 +-
user/advanced-topics/gui-configuration.rst | 6 +-
user/advanced-topics/gui-domain.rst | 34 ++---
.../how-to-install-software-in-dom0.rst | 20 ++-
.../installing-contributed-packages.rst | 10 +-
user/advanced-topics/kde.rst | 14 +-
user/advanced-topics/managing-vm-kernels.rst | 52 +++----
user/advanced-topics/mount-from-other-os.rst | 8 +-
user/advanced-topics/qubes-service.rst | 2 +-
user/advanced-topics/resize-disk-image.rst | 8 +-
user/advanced-topics/salt.rst | 32 ++--
user/advanced-topics/secondary-storage.rst | 44 +++---
user/advanced-topics/standalones-and-hvms.rst | 46 +++---
user/advanced-topics/usb-qubes.rst | 16 +-
user/advanced-topics/volume-backup-revert.rst | 6 +-
.../testing.rst | 4 +-
.../upgrade/2.rst | 6 +-
.../upgrade/2b1.rst | 10 +-
.../upgrade/2b2.rst | 14 +-
.../upgrade/2b3.rst | 12 +-
.../upgrade/3_0.rst | 22 +--
.../upgrade/3_1.rst | 14 +-
.../upgrade/3_2.rst | 26 ++--
.../upgrade/4_0.rst | 2 +-
.../upgrade/4_1.rst | 16 +-
.../upgrade/4_2.rst | 18 +--
.../backup-emergency-restore-v2.rst | 2 +-
.../how-to-copy-and-move-files.rst | 6 +-
.../how-to-copy-and-paste-text.rst | 8 +-
user/how-to-guides/how-to-copy-from-dom0.rst | 6 +-
.../how-to-enter-fullscreen-mode.rst | 4 +-
.../how-to-guides/how-to-install-software.rst | 24 +--
.../how-to-organize-your-qubes.rst | 18 +--
.../how-to-reinstall-a-template.rst | 12 +-
user/how-to-guides/how-to-update.rst | 10 +-
.../how-to-use-block-storage-devices.rst | 34 ++---
user/how-to-guides/how-to-use-disposables.rst | 20 +--
user/how-to-guides/how-to-use-pci-devices.rst | 12 +-
user/how-to-guides/how-to-use-usb-devices.rst | 22 +--
user/security-in-qubes/anti-evil-maid.rst | 2 +-
user/security-in-qubes/ctap-proxy.rst | 6 +-
user/security-in-qubes/firewall.rst | 64 ++++----
user/security-in-qubes/firewall_4.1.rst | 138 +++++++++---------
user/security-in-qubes/mfa.rst | 50 +++----
user/security-in-qubes/split-gpg-2.rst | 20 +--
user/security-in-qubes/split-gpg.rst | 52 +++----
user/security-in-qubes/vm-sudo.rst | 4 +-
user/templates/debian/debian.rst | 2 +-
user/templates/fedora/fedora-upgrade.rst | 6 +-
user/templates/templates.rst | 10 +-
.../windows/qubes-windows-tools-4-0.rst | 64 ++++----
.../windows/qubes-windows-tools-4-1.rst | 60 ++++----
user/templates/windows/windows-qubes-4-0.rst | 34 ++---
user/templates/windows/windows-qubes-4-1.rst | 24 +--
.../app-menu-shortcut-troubleshooting.rst | 16 +-
...bian-and-whonix-update-troubleshooting.rst | 32 ++--
user/troubleshooting/disk-troubleshooting.rst | 16 +-
user/troubleshooting/gui-troubleshooting.rst | 10 +-
.../hardware-troubleshooting.rst | 2 +-
user/troubleshooting/hvm-troubleshooting.rst | 12 +-
.../installation-troubleshooting.rst | 8 +-
user/troubleshooting/pci-troubleshooting.rst | 16 +-
.../resume-suspend-troubleshooting.rst | 2 +-
user/troubleshooting/uefi-troubleshooting.rst | 10 +-
user/troubleshooting/usb-troubleshooting.rst | 10 +-
user/troubleshooting/vm-troubleshooting.rst | 2 +-
user/troubleshooting/vpn-troubleshooting.rst | 6 +-
98 files changed, 1022 insertions(+), 1029 deletions(-)
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
# `, and not everyone will want to use the same email client. On the other hand, almost everyone will need a password manager, and it pretty much always makes sense to keep it in an offline, network-isolated vault.
.. note::
-
+
As you gain experience with Qubes, you may find yourself disagreeing with some of the decisions our fictional friends made. That’s okay! There are many different ways to organize a Qubes system, and the most important criterion is that it serves the needs of its owner. Since everyone’s needs are different, it’s perfectly normal to find yourself doing things a bit differently. Nonetheless, there are some general principles that almost all users find helpful, especially when they’re first starting out.
As you’re designing your own Qubes system, keep in mind some of the following lessons from our case studies:
@@ -189,16 +189,16 @@ As you’re designing your own Qubes system, keep in mind some of the following
.. |Alice’s system: diagram 1| image:: /attachment/doc/howto_use_qubes_alice_1.png
-
+
.. |Alice’s system: diagram 2| image:: /attachment/doc/howto_use_qubes_alice_2.png
-
+
.. |A diagram of Bob’s system| image:: /attachment/doc/howto_use_qubes_bob.png
-
+
.. |A diagram of Carol’s system| image:: /attachment/doc/howto_use_qubes_carol.png
-
+
.. |Simple VM setup| image:: /attachment/doc/Simple_Setup.png
-
+
diff --git a/user/how-to-guides/how-to-reinstall-a-template.rst b/user/how-to-guides/how-to-reinstall-a-template.rst
index ba9e95e0..1922f3ae 100644
--- a/user/how-to-guides/how-to-reinstall-a-template.rst
+++ b/user/how-to-guides/how-to-reinstall-a-template.rst
@@ -11,7 +11,7 @@ Automatic Method
First, copy any files that you wish to keep from the template’s ``/home`` and ``/rw`` folders to a safe storage location. Then, in a dom0 terminal, run:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update --action=reinstall qubes-template-package-name
@@ -23,7 +23,7 @@ Note that Qubes may initially refuse to perform the reinstall if the exact revis
**Reminder:** If you’re trying to reinstall a template that is not in an enabled repo, you must enable that repo. For example:
-.. code:: bash
+.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws
@@ -51,14 +51,14 @@ In what follows, the term “target template” refers to whichever template you
3. Uninstall the target template from dom0:
- .. code:: bash
+ .. code:: console
$ sudo dnf remove
For example, to uninstall the ``whonix-gw`` template:
- .. code:: bash
+ .. code:: console
$ sudo dnf remove qubes-template-whonix-gw
@@ -66,14 +66,14 @@ In what follows, the term “target template” refers to whichever template you
4. Reinstall the target template in dom0:
- .. code:: bash
+ .. code:: console
$ sudo qubes-dom0-update --enablerepo= \
For example, to install the ``whonix-gw`` template:
- .. code:: bash
+ .. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
qubes-template-whonix-gw
diff --git a/user/how-to-guides/how-to-update.rst b/user/how-to-guides/how-to-update.rst
index c10d84d6..4339ccf5 100644
--- a/user/how-to-guides/how-to-update.rst
+++ b/user/how-to-guides/how-to-update.rst
@@ -36,7 +36,7 @@ By default, the **Qubes Update** tool will appear as an icon in the Notification
However, you can also start the tool manually by selecting it in the Applications Menu under “Qubes Tools.” Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting all desired items from the list and clicking “Update”.
.. note::
-
+
For information about how templates download updates, please see :ref:`Why don’t templates have normal network access? ` and the :ref:`Updates proxy ` .
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the “last checked” column. If updates are available for any qube, you will receive a notification as described above, and in the “Updates available” column you will see “YES” for that qube(s). If the update check did not find any new updates, “NO” will appear in the column. Respectively, for qubes that are no longer supported, “OBSOLETE” will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the “Updates available” column will be set to “MAYBE”.
@@ -82,7 +82,7 @@ Command-line interface
.. DANGER::
-
+
**Warning:** Updating with direct commands such as dnf update and apt update is not recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the **Qubes Update** tool or its command-line equivalents, as described below. (By contrast, :doc:`installing ` packages using direct package manager commands is fine.)
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
@@ -175,7 +175,7 @@ Once the package is installed:
Examine the terminal output for warnings or errors. You may see the following warning:
-.. code:: bash
+.. code:: text
WARNING: UEFI capsule updates not available or enabled
@@ -212,7 +212,7 @@ Computers without fwupd support
For computers that do not have firmware update support via ``fwupd``, follow the firmware update instructions on the manufacturer’s website. Verify the authenticity of any firmware updates you apply.
.. |Qube Updates Available| image:: /attachment/doc/r4.2-qube-updates-available.png
-
+
.. |Qubes Update| image:: /attachment/doc/r4.2-software-update.png
-
+
diff --git a/user/how-to-guides/how-to-use-block-storage-devices.rst b/user/how-to-guides/how-to-use-block-storage-devices.rst
index d1fa7f15..2029240e 100644
--- a/user/how-to-guides/how-to-use-block-storage-devices.rst
+++ b/user/how-to-guides/how-to-use-block-storage-devices.rst
@@ -27,7 +27,7 @@ Block Devices in VMs
If not specified otherwise, block devices will show up as ``/dev/xvdi*`` in a linux VM, where ``*`` may be the partition-number. If a block device isn’t automatically mounted after attaching, open a terminal in the VM and execute:
-.. code:: bash
+.. code:: console
cd ~
mkdir mnt
@@ -55,14 +55,14 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
1. In a dom0 console (running as a normal user), list all available block devices:
- .. code:: bash
+ .. code:: console
qvm-block
This will list all available block devices in your system across all VMs. The name of the qube hosting the block device is displayed before the colon in the device ID. The string after the colon is the ID of the device used within the qube, like so:
- .. code:: bash
+ .. code:: console
sourceVM:sdb Cruzer () 4GiB
sourceVM:sdb1 Disk () 2GiB
@@ -71,7 +71,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
2. Assuming your block device is attached to ``sys-usb`` and its device node is ``sdb``, we attach the device to a qube with the name ``work`` like so:
- .. code:: bash
+ .. code:: console
qvm-block attach work sys-usb:sdb
@@ -85,7 +85,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
3. The block device is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. If you’ve attached a single partition (e.g. ``sdb2`` instead of ``sdb`` in our example), you may need to manually mount before it becomes visible:
- .. code:: bash
+ .. code:: console
cd ~
mkdir mnt
@@ -99,7 +99,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
- .. code:: bash
+ .. code:: console
sudo umount mnt
@@ -107,7 +107,7 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
5. In a dom0 console, detach the device
- .. code:: bash
+ .. code:: console
qvm-block detach work sys-usb:sdb
@@ -125,7 +125,7 @@ If you fail to detach the device before it’s destroyed in the sourceVM (e.g.
To recover from this error state, in dom0 run
-.. code:: bash
+.. code:: console
virsh detach-disk targetVM xvdi
@@ -145,7 +145,7 @@ Currently (until issue `1082 template_for_dispvms True
@@ -73,7 +73,7 @@ The default system wide disposable template can be changed with ``qubes-prefs de
You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube in question and go to the “Advanced” tab. Here you can edit the “Default disposable” setting to specify which disposable template will be used to launch disposables from that qube. This can also be changed from the command line with:
-.. code:: bash
+.. code:: console
qvm-prefs default_dispvm
@@ -89,7 +89,7 @@ A disposable launched from the app menu inherits the net qube and firewall setti
**Important Notes:** Some disposable templates will automatically create a menu item to launch a disposable. If you do not see an entry and want to add one, please use the command:
-.. code:: bash
+.. code:: console
qvm-features appmenus-dispvm 1
@@ -97,7 +97,7 @@ A disposable launched from the app menu inherits the net qube and firewall setti
To launch a disposable template from the command line, execute the following command in dom0:
-.. code:: bash
+.. code:: console
qvm-run --dispvm= --service qubes.StartApp+
@@ -136,7 +136,7 @@ Opening a file in a disposable via command line (from app qube)
Use the ``qvm-open-in-dvm`` command from a terminal in your app qube:
-.. code:: bash
+.. code:: console
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
@@ -166,7 +166,7 @@ Starting an arbitrary program in a disposable from an app qube
Sometimes it can be useful to start an arbitrary program in a disposable. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here `__). Starting an arbitrary program can be done from an app qube by running
-.. code:: bash
+.. code:: console
[user@vault ~]$ qvm-run '@dispvm' xterm
@@ -180,7 +180,7 @@ Starting an arbitrary application in a disposable via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks. The disposable will stay running so long as the process which started the disposable has not exited. Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details `here `__). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
-.. code:: bash
+.. code:: console
$ qvm-run --dispvm= --service qubes.StartApp+xterm
@@ -194,7 +194,7 @@ Opening a link in a disposable based on a non-default disposable template from a
Suppose that the default disposable template for your ``email`` qube has no networking (e.g., so that untrusted attachments can’t phone home). However, sometimes you want to open email links in disposables. Obviously, you can’t use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template. You can do that with this command from the ``email`` qube (as long as your RPC policies allow it):
-.. code:: bash
+.. code:: console
$ qvm-open-in-vm @dispvm: https://www.qubes-os.org
@@ -208,7 +208,7 @@ Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file ``/etc/qubes-rpc/policy/qubes.OpenURL``
-.. code:: bash
+.. code:: text
@anyvm @dispvm: allow
@@ -235,4 +235,4 @@ Customizing disposables
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found :doc:`here `.
.. |disposablevm-example.png| image:: /attachment/doc/disposablevm-example.png
-
+
diff --git a/user/how-to-guides/how-to-use-pci-devices.rst b/user/how-to-guides/how-to-use-pci-devices.rst
index 34af08ec..4e1851ad 100644
--- a/user/how-to-guides/how-to-use-pci-devices.rst
+++ b/user/how-to-guides/how-to-use-pci-devices.rst
@@ -53,7 +53,7 @@ The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for
To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
-.. code:: bash
+.. code:: console
qvm-pci
@@ -61,7 +61,7 @@ To figure out what device to attach, first list the available PCI devices by run
This will show you the ``backend:BDF`` (Bus_Device.Function) address of each PCI device. It will look something like ``dom0:00_1a.0``. Once you’ve found the address of the device you want to attach, then attach it like this:
-.. code:: bash
+.. code:: console
qvm-pci attach targetVM sourceVM:[BDF] --persistent
@@ -71,7 +71,7 @@ Since PCI devices have to be attached on bootup, attaching has to happen with th
For example, if ``00_1a.0`` is the BDF of the device you want to attach to the “work” domain, you would do this:
-.. code:: bash
+.. code:: console
qvm-pci attach work dom0:00_1a.0 --persistent
@@ -99,7 +99,7 @@ Do not require PCI device to be reset before attaching it to another VM. This ma
usage example:
-.. code:: bash
+.. code:: console
qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
@@ -113,7 +113,7 @@ Allow write access to full PCI config space instead of whitelisted registers. Th
usage example:
-.. code:: bash
+.. code:: console
qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
@@ -139,7 +139,7 @@ or
- Go to the sysfs (``/sys/bus/pci``), find the right device, detach it from the pciback driver, and attach it back to the original driver. Replace ```` with your full device, for example ``0000:00:1c.2``:
- .. code:: bash
+ .. code:: console
echo > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices//modalias`
diff --git a/user/how-to-guides/how-to-use-usb-devices.rst b/user/how-to-guides/how-to-use-usb-devices.rst
index 648e7c6e..2805acd4 100644
--- a/user/how-to-guides/how-to-use-usb-devices.rst
+++ b/user/how-to-guides/how-to-use-usb-devices.rst
@@ -47,7 +47,7 @@ In dom0, you can use ``qvm-usb`` from the commandline to attach and detach devic
Listing available USB devices:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-usb
BACKEND:DEVID DESCRIPTION USED BY
@@ -58,7 +58,7 @@ Listing available USB devices:
Attaching selected USB device:
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-usb attach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
@@ -72,7 +72,7 @@ Now, you can use your USB device (camera in this case) in the ``work`` qube. If
When you finish, detach the device.
-.. code:: bash
+.. code:: console
[user@dom0 ~]$ qvm-usb detach work sys-usb:2-5
[user@dom0 ~]$ qvm-usb
@@ -102,7 +102,7 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
- Fedora:
- .. code:: bash
+ .. code:: console
sudo dnf install qubes-usb-proxy
@@ -110,7 +110,7 @@ If you receive this error: ``ERROR: qubes-usb-proxy not installed in the qube``,
- Debian/Ubuntu:
- .. code:: bash
+ .. code:: console
sudo apt-get install qubes-usb-proxy
@@ -136,7 +136,7 @@ You can find your controller and its BDF address using the method described belo
First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube):
-.. code:: bash
+.. code:: console
lsusb
@@ -144,7 +144,7 @@ First, find out which USB bus the device is connected to (note that these steps
For example, I want to attach a broadband modem to the NetVM. In the output of ``lsusb`` it may be listed as something like:
-.. code:: bash
+.. code:: text
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
@@ -156,7 +156,7 @@ The device is connected to USB bus #3. Check which other devices are connected t
To find the right controller, follow the usb bus:
-.. code:: bash
+.. code:: console
readlink /sys/bus/usb/devices/usb3
@@ -164,7 +164,7 @@ To find the right controller, follow the usb bus:
This should output something like:
-.. code:: bash
+.. code:: text
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
@@ -172,7 +172,7 @@ This should output something like:
Now you see the path: the text between ``/pci0000:00/0000:`` and ``/usb3`` i.e. ``00:1a.0`` is the BDF address. Strip the address and pass it to the :doc:`qvm-pci tool ` to attach the controller to the target qube, like this:
-.. code:: bash
+.. code:: console
qvm-pci attach --persistent personal dom0:00_1a.0
@@ -180,7 +180,7 @@ Now you see the path: the text between ``/pci0000:00/0000:`` and ``/usb3`` i.e.
It is possible that on some system configurations the readlink method produces output which is different from the example above, For example, you might see output like this:
-.. code:: bash
+.. code:: text
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1
diff --git a/user/security-in-qubes/anti-evil-maid.rst b/user/security-in-qubes/anti-evil-maid.rst
index c5d97ccc..10d557b4 100644
--- a/user/security-in-qubes/anti-evil-maid.rst
+++ b/user/security-in-qubes/anti-evil-maid.rst
@@ -23,7 +23,7 @@ Installing
In Dom0 install ``anti-evil-maid``:
-.. code:: bash
+.. code:: console
sudo qubes-dom0-update anti-evil-maid
diff --git a/user/security-in-qubes/ctap-proxy.rst b/user/security-in-qubes/ctap-proxy.rst
index d06c8f51..952a3415 100644
--- a/user/security-in-qubes/ctap-proxy.rst
+++ b/user/security-in-qubes/ctap-proxy.rst
@@ -88,7 +88,7 @@ If you are using Qubes 4.0, you can further compartmentalise your CTAP keys by r
To enable this, create a file in dom0 named ``/etc/qubes/policy.d/30-user-ctapproxy.policy`` with the following content:
-.. code:: bash
+.. code:: text
policy.RegisterArgument +u2f.Authenticate sys-usb @anyvm allow target=dom0
@@ -104,7 +104,7 @@ Non-default USB qube name
If your USB qube is named differently than ``sys-usb``, then do the following in the appropriate template(s):
-.. code:: bash
+.. code:: console
systemctl enable qubes-ctapproxy@USB_QUBE.service
systemctl disable qubes-ctapproxy@sys-usb.service
@@ -122,4 +122,4 @@ Template and browser support
The large number of possible combinations of template (Fedora 37, 38; Debian 10, 11) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes CTAP Proxy. In some cases, you may be the first person to try a particular combination. Consequently, (and as with any new feature), users will inevitably encounter bugs. We ask for your patience and understanding in this regard. As always, please :doc:`report any bugs you encounter `.
.. |Qubes CTAP Proxy diagram| image:: /attachment/doc/ctap.svg
-
+
diff --git a/user/security-in-qubes/firewall.rst b/user/security-in-qubes/firewall.rst
index 511db9a6..035c8f4c 100644
--- a/user/security-in-qubes/firewall.rst
+++ b/user/security-in-qubes/firewall.rst
@@ -45,7 +45,7 @@ Instead of using the firewall GUI, you can use the ``qvm-firewall`` command in D
The firewall rules for each qube are saved in an XML file in that qube’s directory in dom0:
-.. code:: bash
+.. code:: text
/var/lib/qubes/appvms//firewall.xml
@@ -61,7 +61,7 @@ Reconnecting qubes after a NetVM reboot
Normally Qubes doesn’t let the user stop a NetVM if there are other qubes running which use it as their own NetVM. But in case the NetVM stops for whatever reason (e.g. it crashes, or the user forces its shutdown via qvm-kill via terminal in Dom0), Qubes R4.x will often automatically repair the connection. If it does not, then there is an easy way to restore the connection to the NetVM by issuing in dom0:
-.. code:: bash
+.. code:: console
qvm-prefs netvm
@@ -69,7 +69,7 @@ Normally Qubes doesn’t let the user stop a NetVM if there are other qubes runn
Normally qubes do not connect directly to the actual NetVM (sys-net by default) which has networking devices, but rather to the default sys-firewall first, and in most cases it would be the NetVM that will crash, e.g. in response to S3 sleep/restore or other issues with WiFi drivers. In that case it is only necessary to issue the above command once, for the sys-firewall (this assumes default VM-naming used by the default Qubes installation):
-.. code:: bash
+.. code:: console
qvm-prefs sys-firewall netvm sys-net
@@ -83,7 +83,7 @@ Qubes does not support running any networking services (e.g. VPN, local DNS ser
Instead, you should deploy a network infrastructure such as
-.. code:: bash
+.. code:: text
sys-net <--> sys-firewall-1 <--> network service qube <--> sys-firewall-2 <--> [client qubes]
@@ -121,7 +121,7 @@ In order to allow networking from qube A (client) to qube B (server) follow thes
-.. code:: bash
+.. code:: console
sudo nft add rule ip qubes custom-forward ip saddr ip daddr ct state new,established,related counter accept
@@ -131,7 +131,7 @@ In order to allow networking from qube A (client) to qube B (server) follow thes
-.. code:: bash
+.. code:: console
sudo nft add rule qubes custom-input ip saddr ct state new,established,related counter accept
@@ -173,7 +173,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In dom0, add the following to ``/etc/qubes/policy.d/30-user-networking.policy``: (it could be ``another-other-name.policy`` – just remember to keep it consistent)
- .. code:: bash
+ .. code:: text
qubes.ConnectTCP * untrusted @default allow target=mytcp-service
@@ -207,7 +207,7 @@ which means to use default local port of ``unstrusted`` as the same of the remot
Consider now the case where someone prefers to specify the destination qube and use another port in untrusted, for example ``10044``. Instead of previous case, add
-.. code:: bash
+.. code:: text
qubes.ConnectTCP * untrusted mytcp-service allow
@@ -227,7 +227,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
One can go further than the previous examples by redirecting different ports to different qubes. For example, let assume that another qube ``mytcp-service-bis`` with a TCP service is running on port ``445``. If someone wants ``untrusted`` to be able to reach this service but port ``445`` is reserved to ``mytcp-service-bis`` then, in dom0, add the following to ``/etc/qubes/policy.d/30-user-networking.policy``:
-.. code:: bash
+.. code:: text
qubes.ConnectTCP +445 untrusted @default allow target=mytcp-service-bis
@@ -247,15 +247,15 @@ will restrict the binding to only the corresponding TCP port of ``mytcp-service-
For creating a permanent port bind between two qubes, ``systemd`` can be used. We use the case of the first example. In ``/rw/config`` (or any place you find suitable) of qube ``untrusted``, create ``my-tcp-service.socket`` with content:
-.. code:: bash
+.. code:: systemd
[Unit]
Description=my-tcp-service
-
+
[Socket]
ListenStream=127.0.0.1:444
Accept=true
-
+
[Install]
WantedBy=sockets.target
@@ -263,11 +263,11 @@ For creating a permanent port bind between two qubes, ``systemd`` can be used. W
and ``my-tcp-service@.service`` with content:
-.. code:: bash
+.. code:: systemd
[Unit]
Description=my-tcp-service
-
+
[Service]
ExecStart=qrexec-client-vm '' qubes.ConnectTCP+444
StandardInput=socket
@@ -353,7 +353,7 @@ When writing rules in sys-net, you can use ``iif`` or ``iifname``. ``iif`` is fa
In the sys-net VM’s Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
-.. code:: bash
+.. code:: console
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@@ -367,7 +367,7 @@ In the sys-net VM’s Terminal, the first step is to define an nftables chain th
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
-.. code:: bash
+.. code:: console
nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
@@ -375,7 +375,7 @@ Second step, code a natting firewall rule to route traffic on the outside interf
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
-.. code:: bash
+.. code:: console
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
@@ -389,7 +389,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains ``custom-forward`` and ``custom-dnat-qubeDEST``:
-.. code:: bash
+.. code:: console
nft list table ip qubes
@@ -397,12 +397,12 @@ Verify the rules on the sys-net firewall correctly match the packets you want by
In this example, we can see 7 packets in the forward rule, and 3 packets in the dnat rule:
-.. code:: bash
+.. code:: console
chain custom-forward {
iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
}
-
+
chain custom-dnat-qubeDEST {
type nat hook prerouting priority filter + 1; policy accept;
iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
@@ -412,7 +412,7 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
(Optional) You can send a test packet by trying to connect to the service from an external device using the following command:
-.. code:: bash
+.. code:: console
telnet 192.168.x.n 443
@@ -432,13 +432,13 @@ Content of ``/rw/config/qubes-firewall-user-script`` in ``sys-net``:
.. code:: bash
#!/bin/sh
-
+
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
-
+
# allow forwarded traffic
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
fi
@@ -451,7 +451,7 @@ For the following example, we use the fact that the interface of sys-firewall fa
In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
-.. code:: bash
+.. code:: console
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@@ -459,7 +459,7 @@ In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
-.. code:: bash
+.. code:: console
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
@@ -467,7 +467,7 @@ Second step, code a natting firewall rule to route traffic on the outside interf
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
-.. code:: bash
+.. code:: console
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
@@ -491,13 +491,13 @@ Content of ``/rw/config/qubes-firewall-user-script`` in ``sys-firewall``:
.. code:: bash
#!/bin/sh
-
+
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
-
+
# allow forwarded traffic
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
fi
@@ -514,7 +514,7 @@ For the following example, we assume that the target VM running the web server h
The according rule to allow the traffic is:
-.. code:: bash
+.. code:: console
nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept
@@ -547,7 +547,7 @@ An effective console utility to troubleshoot network is `tcpdump /firewall.xml
@@ -71,7 +71,7 @@ Qubes does not support running any networking services (e.g. VPN, local DNS ser
Instead, you should deploy a network infrastructure such as
-.. code:: bash
+.. code:: text
sys-net <--> sys-firewall-1 <--> network service qube <--> sys-firewall-2 <--> [client qubes]
@@ -109,7 +109,7 @@ In order to allow networking between qubes A and B follow these steps:
-.. code:: bash
+.. code:: console
sudo iptables -I FORWARD 2 -s -d -j ACCEPT
@@ -119,7 +119,7 @@ In order to allow networking between qubes A and B follow these steps:
-.. code:: bash
+.. code:: console
sudo iptables -I INPUT -s -j ACCEPT
@@ -163,7 +163,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In dom0, add the following to ``/etc/qubes/policy.d/30-user-networking.policy``: (it could be ``another-other-name.policy`` – just remember to keep it consistent)
- .. code:: bash
+ .. code:: text
qubes.ConnectTCP * untrusted @default allow target=mytcp-service
@@ -197,7 +197,7 @@ which means to use default local port of ``unstrusted`` as the same of the remot
Consider now the case where someone prefers to specify the destination qube and use another port in untrusted, for example ``10044``. Instead of previous case, add
-.. code:: bash
+.. code:: text
qubes.ConnectTCP * untrusted mytcp-service allow
@@ -217,7 +217,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
One can go further than the previous examples by redirecting different ports to different qubes. For example, let assume that another qube ``mytcp-service-bis`` with a TCP service is running on port ``445``. If someone wants ``untrusted`` to be able to reach this service but port ``445`` is reserved to ``mytcp-service-bis`` then, in dom0, add the following to ``/etc/qubes/policy.d/30-user-networking.policy``:
-.. code:: bash
+.. code:: text
qubes.ConnectTCP +445 untrusted @default allow target=mytcp-service-bis
@@ -237,15 +237,15 @@ will restrict the binding to only the corresponding TCP port of ``mytcp-service-
For creating a permanent port bind between two qubes, ``systemd`` can be used. We use the case of the first example. In ``/rw/config`` (or any place you find suitable) of qube ``untrusted``, create ``my-tcp-service.socket`` with content:
-.. code:: bash
+.. code:: systemd
[Unit]
Description=my-tcp-service
-
+
[Socket]
ListenStream=127.0.0.1:444
Accept=true
-
+
[Install]
WantedBy=sockets.target
@@ -253,11 +253,11 @@ For creating a permanent port bind between two qubes, ``systemd`` can be used. W
and ``my-tcp-service@.service`` with content:
-.. code:: bash
+.. code:: systemd
[Unit]
Description=my-tcp-service
-
+
[Service]
ExecStart=qrexec-client-vm '' qubes.ConnectTCP+444
StandardInput=socket
@@ -327,7 +327,7 @@ For the following example, we assume that the physical interface eth0 in sys-net
In the sys-net VM’s Terminal, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
-.. code:: bash
+.. code:: console
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT --to-destination 10.137.1.z
@@ -335,7 +335,7 @@ In the sys-net VM’s Terminal, code a natting firewall rule to route traffic on
Code the appropriate new filtering firewall rule to allow new connections for the service
-.. code:: bash
+.. code:: console
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
@@ -351,7 +351,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2)
-.. code:: bash
+.. code:: console
iptables -t nat -L -v -n
iptables -L -v -n
@@ -362,7 +362,7 @@ Verify you are cutting through the sys-net VM firewall by looking at its counter
-.. code:: bash
+.. code:: console
nft list table ip qubes-firewall
@@ -370,7 +370,7 @@ Verify you are cutting through the sys-net VM firewall by looking at its counter
Send a test packet by trying to connect to the service from an external device
-.. code:: bash
+.. code:: console
telnet 192.168.x.y 443
@@ -378,7 +378,7 @@ Send a test packet by trying to connect to the service from an external device
Once you have confirmed that the counters increase, store these command in ``/rw/config/rc.local`` so they get set on sys-net start-up
-.. code:: bash
+.. code:: console
sudo nano /rw/config/rc.local
@@ -387,45 +387,45 @@ Once you have confirmed that the counters increase, store these command in ``/rw
.. code:: bash
#!/bin/sh
-
-
+
+
####################
# My service routing
-
+
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
-
+
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.1.z
-
+
fi
-
-
+
+
# If no prerouting rule exist for my service
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
-
+
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j MY-HTTPS
fi
-
-
+
+
######################
# My service filtering
-
+
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
-
+
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
-
+
fi
-
+
# If no forward rule exist for my service
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
-
+
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 2 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
-
+
fi
@@ -438,13 +438,13 @@ Once you have confirmed that the counters increase, store these command in ``/rw
#############
# In Qubes R4
-
+
# If not already present
if nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
-
+
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept
-
+
fi
@@ -455,7 +455,7 @@ For the following example, we use the fact that the physical interface of sys-fi
In the sys-firewall VM’s Terminal, code a natting firewall rule to route traffic on its outside interface for the service to the qube
-.. code:: bash
+.. code:: console
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j DNAT --to-destination 10.137.0.xx
@@ -463,7 +463,7 @@ In the sys-firewall VM’s Terminal, code a natting firewall rule to route traff
Code the appropriate new filtering firewall rule to allow new connections for the service
-.. code:: bash
+.. code:: console
iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
@@ -475,7 +475,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
-.. code:: bash
+.. code:: console
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
@@ -483,7 +483,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
Once you have confirmed that the counters increase, store these command in ``/rw/config/qubes-firewall-user-script``
-.. code:: bash
+.. code:: console
sudo nano /rw/config/qubes-firewall-user-script
@@ -492,63 +492,63 @@ Once you have confirmed that the counters increase, store these command in ``/rw
.. code:: bash
#!/bin/sh
-
-
+
+
####################
# My service routing
-
+
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
-
+
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.0.xx
-
+
fi
-
-
+
+
# If no prerouting rule exist for my service
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
-
+
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j MY-HTTPS
fi
-
-
+
+
######################
# My service filtering
-
+
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
-
+
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
-
+
fi
-
+
# If no forward rule exist for my service
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
-
+
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 4 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
-
+
fi
-
+
################
# In Qubes OS R4
-
+
# If not already present
if ! nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
-
+
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
-
+
fi
Finally make this file executable (so it runs at every Firewall VM update)
-.. code:: bash
+.. code:: console
sudo chmod +x /rw/config/qubes-firewall-user-script
@@ -560,7 +560,7 @@ If the service should be available to other VMs on the same system, do not forge
Here no routing is required, only filtering. Proceed in the same way as above but store the filtering rule in the ``/rw/config/rc.local`` script. For the following example, we assume that the target VM running the web server has the IP address 10.137.0.xx
-.. code:: bash
+.. code:: console
sudo nano /rw/config/rc.local
@@ -570,21 +570,21 @@ Here no routing is required, only filtering. Proceed in the same way as above bu
######################
# My service filtering
-
+
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
-
+
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -j ACCEPT
-
+
fi
-
+
# If no input rule exists for my service
if ! iptables -w -n -L INPUT | grep --quiet MY-HTTPS; then
-
+
# add a forward rule for the traffic (same reason)
iptables -w -I INPUT 5 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
-
+
fi
diff --git a/user/security-in-qubes/mfa.rst b/user/security-in-qubes/mfa.rst
index e219e740..5e30028f 100644
--- a/user/security-in-qubes/mfa.rst
+++ b/user/security-in-qubes/mfa.rst
@@ -25,7 +25,7 @@ As the name implies, this generates authentication code that is time-dependent.
1. Download ``google-authenticator`` in dom0:
- .. code:: bash
+ .. code:: console
sudo qubes-dom0-update google-authenticator
@@ -33,7 +33,7 @@ As the name implies, this generates authentication code that is time-dependent.
2. Run google authenticator:
- .. code:: bash
+ .. code:: console
google-authenticator
@@ -41,14 +41,14 @@ As the name implies, this generates authentication code that is time-dependent.
3. Walk through the setup instructions which will also generate your QR code for your auth app of choice:
- .. code:: bash
+ .. code:: text
Do you want me to update your “/home/user/.google_authenticator” file (y/n) y
-
+
Do you want to disallow multiple uses of the same authentication token? This restricts you to one login about every 30s, but it increases your chances to notice or even prevent man-in-the-middle attacks (y/n)
-
+
By default, tokens are good for 30 seconds, and to compensate for possible time-skew between the client and the server, we allow an extra token before and after the current time. If you experience problems with poor time synchronization, you can increase the window from its default size of 1:30min to about 4min. Do you want to do so (y/n)
-
+
If the computer that you are logging into isn’t hardened against brute-force login attempts, you can enable rate-limiting for the authentication module. By default, this limits attackers to no more than 3 login attempts every 30s. Do you want to enable rate-limiting (y/n)
@@ -66,14 +66,14 @@ Now we are going to add the authenticator as a login requirement:
2. Edit the custom system authentication template in ``/etc/authselect/custom/mfa/system-auth``.
Add the following line right after ``auth required pam_faildelay.so delay=2000000``:
- .. code:: bash
+ .. code:: text
auth required pam_google_authenticator.so
After the change, the top of the file should look like this:
- .. code:: bash
+ .. code:: text
{imply "with-smartcard" if "with-smartcard-required"}
auth required pam_env.so
@@ -84,7 +84,7 @@ Now we are going to add the authenticator as a login requirement:
3. Lastly, activate this authentication method with:
- .. code:: bash
+ .. code:: console
sudo authselect select custom/mfa
@@ -108,7 +108,7 @@ The following assumes you haven’t restarted your computer since setting up TOT
2. Revert to the original policy with:
- .. code:: bash
+ .. code:: console
sudo authselect select sssd
@@ -168,7 +168,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
- .. code:: bash
+ .. code:: console
sudo dnf install ykpers
@@ -178,7 +178,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
- .. code:: bash
+ .. code:: console
sudo apt-get install yubikey-personalization
@@ -202,7 +202,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
2. Install `qubes-app-yubikey `__ in dom0. This provides the program to authenticate with password and YubiKey / NitroKey3.
- .. code:: bash
+ .. code:: console
sudo qubes-dom0-update qubes-yubikey-dom0
@@ -236,7 +236,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
- Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your USB qube and running the following commands in it:
- .. code:: bash
+ .. code:: console
AESKEY=$(echo -n "your-20-digit-secret" | base32)
nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
@@ -281,7 +281,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
- You can calculate your hashed password using the following two commands. First run the following command to store your password in a temporary variable ``password``. (This way your password will not leak to the terminal command history file.)
- .. code:: bash
+ .. code:: console
read -r password
@@ -289,7 +289,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
- Now run the following command to calculate your hashed password.
- .. code:: bash
+ .. code:: console
echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
@@ -299,7 +299,7 @@ All these requirements are described below, step by step, for the YubiKey and Ni
6. To enable multi-factor authentication for a service, you need to add
- .. code:: bash
+ .. code:: text
auth include yubikey
@@ -337,7 +337,7 @@ Optional: Enforce YubiKey / NitroKey3 Login
Edit ``/etc/pam.d/yubikey`` (or appropriate file if you are using other screen locker program) and remove ``default=ignore`` so the line looks like this.
-.. code:: bash
+.. code:: text
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
@@ -353,7 +353,7 @@ In dom0:
1. First configure the qrexec service. Create ``/etc/qubes-rpc/custom.LockScreen`` with a simple command to lock the screen. In the case of xscreensaver (used in Xfce) it would be:
- .. code:: bash
+ .. code:: text
DISPLAY=:0 xscreensaver-command -lock
@@ -361,7 +361,7 @@ In dom0:
2. Then make ``/etc/qubes-rpc/custom.LockScreen`` executable.
- .. code:: bash
+ .. code:: console
sudo chmod +x /etc/qubes-rpc/custom.LockScreen
@@ -369,7 +369,7 @@ In dom0:
3. Allow your USB VM to call that service. Assuming that it’s named ``sys-usb`` it would require creating ``/etc/qubes-rpc/policy/custom.LockScreen`` with:
- .. code:: bash
+ .. code:: text
sys-usb dom0 allow
@@ -381,7 +381,7 @@ In your USB VM:
1. Create udev hook. Store it in ``/rw/config`` to have it persist across VM restarts. For example name the file ``/rw/config/yubikey.rules``. Add the following line:
- .. code:: bash
+ .. code:: text
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen"
@@ -398,7 +398,7 @@ In your USB VM:
3. Then make ``/rw/config/rc.local`` executable.
- .. code:: bash
+ .. code:: console
sudo chmod +x /rw/config/rc.local
@@ -406,7 +406,7 @@ In your USB VM:
4. For changes to take effect, you need to call this script manually for the first time.
- .. code:: bash
+ .. code:: console
sudo /rw/config/rc.local
@@ -416,7 +416,7 @@ In your USB VM:
If you use KDE, the command(s) in first step would be different:
-.. code:: bash
+.. code:: console
# In the case of USB VM being autostarted, it will not have direct access to D-Bus
# session bus, so find its address manually:
diff --git a/user/security-in-qubes/split-gpg-2.rst b/user/security-in-qubes/split-gpg-2.rst
index 734097b7..772537ea 100644
--- a/user/security-in-qubes/split-gpg-2.rst
+++ b/user/security-in-qubes/split-gpg-2.rst
@@ -23,7 +23,7 @@ Configuration
Create/Edit ``/etc/qubes/policy.d/30-user-gpg2.policy`` in dom0, and add a line like this:
-.. code:: bash
+.. code:: console
qubes.Gpg2 + gpg-client-vm @default allow target=gpg-server-vm
@@ -31,7 +31,7 @@ Create/Edit ``/etc/qubes/policy.d/30-user-gpg2.policy`` in dom0, and add a line
Import/Generate your secret keys in the server domain. For example:
-.. code:: bash
+.. code:: console
gpg-server-vm$ gpg --import /path/to/my/secret-keys-export
gpg-server-vm$ gpg --import-ownertrust /path/to/my/ownertrust-export
@@ -40,7 +40,7 @@ Import/Generate your secret keys in the server domain. For example:
or
-.. code:: bash
+.. code:: console
gpg-server-vm$ gpg --gen-key
@@ -48,21 +48,21 @@ or
In dom0 enable the ``split-gpg2-client`` service in the client domain, for example via the command-line:
-.. code:: bash
+.. code:: console
dom0$ qvm-service split-gpg2-client on
To verify if this was done correctly:
-.. code:: bash
+.. code:: console
dom0$ qvm-service
Output should be:
-.. code:: bash
+.. code:: console
split-gpg2-client on
@@ -71,12 +71,12 @@ Restart the client domain.
Export the **public** part of your keys and import them in the client domain. Also import/set proper “ownertrust” values. For example:
-.. code:: bash
+.. code:: console
gpg-server-vm$ gpg --export > public-keys-export
gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
-
+
gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
@@ -84,7 +84,7 @@ Export the **public** part of your keys and import them in the client domain. Al
This should be enough to have it running:
-.. code:: bash
+.. code:: console
gpg-client-vm$ gpg -K
/home/user/.gnupg/pubring.kbx
@@ -140,4 +140,4 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.. |split-gpg-diagram.png| image:: /attachment/doc/split-gpg-diagram.png
-
+
diff --git a/user/security-in-qubes/split-gpg.rst b/user/security-in-qubes/split-gpg.rst
index 02de91ea..a304e9d5 100644
--- a/user/security-in-qubes/split-gpg.rst
+++ b/user/security-in-qubes/split-gpg.rst
@@ -4,7 +4,7 @@ Split GPG
.. warning::
-
+
**Note:** This information concerns split-gpg. The implementation has been updated to provide more features in split-gpg-2. Some incomplete information on split-gpg-2 is available :doc:`here `.
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the “smart card” is played by another Qubes app qube. This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations – such as encryption/decryption and signing – to another, more trusted, network-isolated domain. This way the compromise of your domain where Thunderbird or another client app is running – arguably a not-so-unthinkable scenario – does not allow the attacker to automatically also steal all your keys. (We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
@@ -99,7 +99,7 @@ Normally it should be enough to set the ``QUBES_GPG_DOMAIN`` to the GPG backend
uid Qubes OS Security Team
ssb 4096R/30498E2A 2012-11-15
(...)
-
+
[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
(...)
@@ -124,7 +124,7 @@ The ``qubes-gpg-client-wrapper`` script sets the ``QUBES_GPG_DOMAIN`` variable a
Split GPG’s default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in ``dom0`` place the following line at the top of the file ``/etc/qubes-rpc/policy/qubes.Gpg``:
-.. code:: bash
+.. code:: text
work-email work-gpg allow
@@ -134,7 +134,7 @@ where ``work-email`` is the Thunderbird + Enigmail app qube and ``work-gpg`` con
You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append ``default_target=`` to ``ask`` in ``/etc/qubes-rpc/policy/qubes.Gpg``. For the examples given on this page:
-.. code:: bash
+.. code:: text
@anyvm @anyvm ask default_target=work-gpg
@@ -232,13 +232,13 @@ Using Git with Split GPG
Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed. The most basic ``~/.gitconfig`` file enabling Split GPG looks something like this.
-.. code:: bash
+.. code:: ini
[user]
name =
email =
signingKey =
-
+
[gpg]
program = qubes-gpg-client-wrapper
@@ -261,7 +261,7 @@ Your key id is the public id of your signing key, which can be found by running
To sign commits, you now add the “-S” flag to your commit command, which should prompt for Split GPG usage. If you would like to automatically sign all commits, you can add the following snippet to ``~/.gitconfig``.
-.. code:: bash
+.. code:: ini
[commit]
gpgSign = true
@@ -300,8 +300,8 @@ Setup Description
In this example, the following keys are stored in the following locations (see below for definitions of these terms):
-.. list-table::
- :widths: 10 10
+.. list-table::
+ :widths: 10 10
:align: center
:header-rows: 1
@@ -313,7 +313,7 @@ In this example, the following keys are stored in the following locations (see b
- ``work-gpg``
* - ``pub``
- ``work-email``
-
+
- ``sec`` (master secret key)
@@ -395,50 +395,50 @@ Current limitations
- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase. It will give an ``Inappropriate ioctl for device`` error. Do not set passphrases for the private keys in the GPG backend domain. Doing so won’t provide any extra security anyway, as explained in the introduction and in `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__. If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use ``gpg2 --edit-key `` then ``passwd`` to set an empty passphrase. Note that ``pinentry`` might show an error when you try to set an empty passphrase, but it will still make the change. (See `this StackExchange answer `__ for more information.) **Note:** The error shows only if you **do not** have graphical pinentry installed.
-.. [1]
+.. [1]
In order to gain access to the ``vault`` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a :ref:`signed, compromised package which is already installed in the template ` upon which the ``vault`` VM is based.
.. |split-gpg-diagram.png| image:: /attachment/doc/split-gpg-diagram.png
-
+
.. |r2-split-gpg-1.png| image:: /attachment/doc/r2-split-gpg-1.png
-
+
.. |r2-split-gpg-3.png| image:: /attachment/doc/r2-split-gpg-3.png
-
+
.. |tb78-1.png| image:: /attachment/doc/tb78-1.png
-
+
.. |tb78-2.png| image:: /attachment/doc/tb78-2.png
-
+
.. |tb78-3.png| image:: /attachment/doc/tb78-3.png
-
+
.. |tb78-4.png| image:: /attachment/doc/tb78-4.png
-
+
.. |tb78-5.png| image:: /attachment/doc/tb78-5.png
-
+
.. |tb78-6.png| image:: /attachment/doc/tb78-6.png
-
+
.. |tb78-7.png| image:: /attachment/doc/tb78-7.png
-
+
.. |tb78-8.png| image:: /attachment/doc/tb78-8.png
-
+
.. |tb78-9.png| image:: /attachment/doc/tb78-9.png
-
+
.. |tb78-10.png| image:: /attachment/doc/tb78-10.png
-
+
.. |tb-enigmail-split-gpg-settings-2.png| image:: /attachment/doc/tb-enigmail-split-gpg-settings-2.png
-
+
.. |r2-split-gpg-5.png| image:: /attachment/doc/r2-split-gpg-5.png
-
+
diff --git a/user/security-in-qubes/vm-sudo.rst b/user/security-in-qubes/vm-sudo.rst
index a798e2ed..9e841beb 100644
--- a/user/security-in-qubes/vm-sudo.rst
+++ b/user/security-in-qubes/vm-sudo.rst
@@ -5,10 +5,10 @@ Passwordless root access in qubes
The background to passswordless root access is summarised in this statement, that used to be found at ``/etc/sudoers.d/qubes`` in each qube:
-.. code:: bash
+.. code:: text
user ALL=(ALL) NOPASSWD: ALL
-
+
# WTF?! Have you lost your mind?!
#
# In Qubes VMs there is no point in isolating the root account from
diff --git a/user/templates/debian/debian.rst b/user/templates/debian/debian.rst
index 6a9af8a6..72b154e5 100644
--- a/user/templates/debian/debian.rst
+++ b/user/templates/debian/debian.rst
@@ -73,7 +73,7 @@ The Debian-12 templates that ship with release 4.2.4 cannot be used for salting
If you have a Debian template from an earlier release that you want to use for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded. Do this by marking these packages on hold *before* updating the template.
-.. code:: bash
+.. code:: console
sudo apt-mark hold salt-common salt-ssh
sudo apt update
diff --git a/user/templates/fedora/fedora-upgrade.rst b/user/templates/fedora/fedora-upgrade.rst
index 27af9c9b..c6dfa293 100644
--- a/user/templates/fedora/fedora-upgrade.rst
+++ b/user/templates/fedora/fedora-upgrade.rst
@@ -7,7 +7,7 @@ How to upgrade a Fedora template in-place
This page is intended for advanced users.
.. DANGER::
-
+
**Warning:** This page is intended for advanced users only. Most users seeking to upgrade should instead :ref:`install a new Fedora template ` . Learn more about the two options :ref:`here ` .
This page provides instructions for performing an in-place upgrade of an installed :doc:`Fedora Template `. If you wish to install a new, unmodified Fedora template instead of upgrading a template that is already installed in your system, please see the :doc:`Fedora Template ` page instead. (:ref:`Learn more about the two options. `)
@@ -70,7 +70,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
**Note:** ``dnf`` might ask you to approve importing a new package signing key. For example, you might see a prompt like this one:
- .. code:: bash
+ .. code:: text
warning: /mnt/removable/updates-0b4cc238d1aa4ffe/packages/example-package.fc.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID XXXXXXXX: NOKEY
Importing GPG key 0xXXXXXXXX:
@@ -206,7 +206,7 @@ Additional information
As mentioned above, you may encounter the following ``dnf`` error:
-.. code:: bash
+.. code:: text
At least X MB more space needed on the / filesystem.
diff --git a/user/templates/templates.rst b/user/templates/templates.rst
index dfa588a3..597a694d 100644
--- a/user/templates/templates.rst
+++ b/user/templates/templates.rst
@@ -203,14 +203,14 @@ When you install a new template or :ref:`upgrade `` with the name of the disposable template on which ``sys-usb`` is based, ```` with the name of the new template, and ```` with the name of your USB qube. Other than these substitutions, make sure to enter the command exactly as written.
- .. code:: bash
+ .. code:: console
qvm-shutdown --wait --all; qvm-prefs template ; qvm-start
With substitutions, your command should look similar to this example. (**Warning:** This is just an example. Do not attempt to use it.)
- .. code:: bash
+ .. code:: console
qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb
@@ -238,8 +238,8 @@ Whenever an app qube is created, the contents of the ``/home`` directory of its
Once an app qube has been created, any changes in its ``/home``, ``/usr/local``, or ``/rw/config`` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the app qube. No changes in any other directories in app qubes persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent template.
-.. list-table::
- :widths: 44 44 44
+.. list-table::
+ :widths: 44 44 44
:align: center
:header-rows: 1
@@ -255,7 +255,7 @@ Once an app qube has been created, any changes in its ``/home``, ``/usr/local``,
* - :ref:`disposable `
- ``/rw`` (includes ``/home``, ``/usr/local``, and ``bind-dirs``)
- nothing
-
+
| :superscript:`1` Upon creation
| :superscript:`2` Following shutdown
diff --git a/user/templates/windows/qubes-windows-tools-4-0.rst b/user/templates/windows/qubes-windows-tools-4-0.rst
index 6f86c3af..aa22de69 100644
--- a/user/templates/windows/qubes-windows-tools-4-0.rst
+++ b/user/templates/windows/qubes-windows-tools-4-0.rst
@@ -21,8 +21,8 @@ Qubes Windows Tools are a set of programs and drivers that provide integration o
Below is a breakdown of the feature availability depending on the windows version:
-.. list-table::
- :widths: 39 39 39
+.. list-table::
+ :widths: 39 39 39
:align: center
:header-rows: 1
@@ -59,7 +59,7 @@ Below is a breakdown of the feature availability depending on the windows versio
* - Audio
- n
- n
-
+
Qubes Windows Tools are open source and are distributed under a GPL license.
@@ -102,7 +102,7 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
6. Check the integrity of the file ``qubes-tools-4.0.1.3.exe``by comparing its hash checksum. This can be done using the Windows command ``certutil`` on the windows command prompt (``cmd.exe``) and specifying an appropriate hash algorithm like:
- .. code:: bash
+ .. code:: doscon
certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256
@@ -120,7 +120,7 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
9. On a ``dom0`` terminal write: *(where* ```` *is the name of your Windows 10 VM)*
- .. code:: bash
+ .. code:: console
qvm-features gui 1
qvm-prefs qrexec_timeout 300
@@ -133,7 +133,7 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
12. Lastly to enable file copy operations to a Windows 10 VM the ``default_user`` property should be set the ```` that you use to login to the Windows VM. This can be done via the following command on a ``dom0`` terminal: *(where* ```` *is the name of your Windows 10 VM)*
- .. code:: bash
+ .. code:: console
qvm-prefs default_user
@@ -143,7 +143,7 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
**Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
-.. code:: bash
+.. code:: text
C:\Windows\System32\config\systemprofile\Documents\QubesIncoming\
@@ -157,7 +157,7 @@ Installing Qubes guest tools in Windows 7 VMs
First, make sure that ``qubes-windows-tools`` is installed in your system:
-.. code:: bash
+.. code:: console
sudo qubes-dom0-update qubes-windows-tools
@@ -167,7 +167,7 @@ First, make sure that ``qubes-windows-tools`` is installed in your system:
You can also install the package from testing repositories, where we usually publish new versions first:
-.. code:: bash
+.. code:: console
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
@@ -189,7 +189,7 @@ In the future this step will not be necessary anymore, because we will sign our
To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option ``--install-windows-tools``:
-.. code:: bash
+.. code:: console
qvm-start lab-win7 --install-windows-tools
@@ -201,7 +201,7 @@ After successful installation, the Windows VM must be shut down and started agai
Qubes will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as ``qrexec_installed``, ``guiagent_installed``, and ``default_user``. This can be verified (but is not required) using qvm-prefs command:
-.. code:: bash
+.. code:: console
qvm-prefs
@@ -209,7 +209,7 @@ Qubes will automatically detect the tools has been installed in the VM and will
**Note:** it is recommended to increase the default value of Windows VM’s ``qrexec_timeout`` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM’s virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
-.. code:: bash
+.. code:: console
qvm-prefs qrexec_timeout 300
@@ -245,7 +245,7 @@ Notes about using Xen’s VBD (storage) PV driver:
With Qubes Windows Tools installed the early graphical console provided in debugging mode isn’t needed anymore since Qubes’ display driver will be used instead of the default VGA driver:
-.. code:: bash
+.. code:: console
qvm-prefs -s win7new debug false
@@ -259,7 +259,7 @@ Using Windows AppVMs in seamless mode
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the ``-a`` switch used here, which will auto-start the VM if it is not running):
-.. code:: bash
+.. code:: console
qvm-run -a my-win7-appvm explorer.exe
@@ -303,7 +303,7 @@ Qubes allows HVM VMs to share a common root filesystem from a select Template VM
In order to create a HVM TemplateVM one can use the following command, suitably adapted:
-.. code:: bash
+.. code:: console
qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green
@@ -333,7 +333,7 @@ It also makes sense to disable Automatic Updates for all the template-based AppV
Once the template has been created and installed it is easy to create AppVMs based on it:
-.. code:: bash
+.. code:: console
qvm-create --property virt_mode=hvm --template --label ` mode (Xen’s current PVH limitations precludes from using PVH):
-.. code:: bash
+.. code:: console
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
@@ -195,7 +195,7 @@ Windows’ installer requires a significant amount of memory or else the VM will
``/var/log/xen/console/hypervisor.log``:
-.. code:: bash
+.. code:: text
p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
(XEN) domain_crash called from p2m-pod.c:1218
@@ -205,7 +205,7 @@ Windows’ installer requires a significant amount of memory or else the VM will
So, increase the VM’s memory to 4096MB (memory = maxmem because we don’t use memory balancing).
-.. code:: bash
+.. code:: console
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
@@ -214,7 +214,7 @@ So, increase the VM’s memory to 4096MB (memory = maxmem because we don’t use
Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence:
-.. code:: bash
+.. code:: console
qvm-prefs win7new kernel ''
@@ -222,7 +222,7 @@ Disable direct boot so that the VM will go through the standard cdrom/HDD boot s
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/…). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows’s disk manager).
-.. code:: bash
+.. code:: console
qvm-volume extend win7new:root 25g
@@ -230,7 +230,7 @@ A typical Windows 7 installation requires between 15GB up to 19GB of disk space
Set the debug flag in order to have a graphical console:
-.. code:: bash
+.. code:: console
qvm-prefs win7new debug true
@@ -238,7 +238,7 @@ Set the debug flag in order to have a graphical console:
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in “transient” mode with the following error in ``guest-win7new-dm.log``:
-.. code::
+.. code:: text
qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
@@ -246,7 +246,7 @@ The second part of the installation process will crash with the standard VGA vid
To avoid that error we temporarily have to switch the video adapter to ‘cirrus’:
-.. code:: bash
+.. code:: console
qvm-features win7new video-model cirrus
@@ -254,7 +254,7 @@ To avoid that error we temporarily have to switch the video adapter to ‘cirrus
The VM is now ready to be started; the best practice is to use an installation ISO :ref:`located in a VM `:
-.. code:: bash
+.. code:: console
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
@@ -264,7 +264,7 @@ Given the higher than usual memory requirements of Windows, you may get a ``Not
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
-.. code:: bash
+.. code:: console
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
@@ -278,7 +278,7 @@ The second part of Windows’ installer should then be able to complete successf
Decrease the VM’s memory to a more reasonable value (memory balancing on Windows is unstable so keep ``memory`` equal to ``maxmen``).
-.. code:: bash
+.. code:: console
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
@@ -287,7 +287,7 @@ Decrease the VM’s memory to a more reasonable value (memory balancing on Windo
Revert to the standard VGA adapter: the ‘cirrus’ adapter will limit the maximum screen resolution to 1024x768 pixels, while the default VGA adapter allows for much higher resolutions (up to 2560x1600 pixels).
-.. code:: bash
+.. code:: console
qvm-features --unset win7new video-model
@@ -295,7 +295,7 @@ Revert to the standard VGA adapter: the ‘cirrus’ adapter will limit the maxi
Finally, increase the VM’s ``qrexec_timeout``: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won’t complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools’ installation.
-.. code:: bash
+.. code:: console
qvm-prefs win7new qrexec_timeout 300
@@ -309,7 +309,7 @@ Windows as a template
Windows 7 and 10 can be installed as TemplateVM by selecting
-.. code:: bash
+.. code:: console
qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template
@@ -327,7 +327,7 @@ For Windows 10, configuration data like those stored in directories like ``AppDa
AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying
-.. code:: bash
+.. code:: console
qvm-create --class=AppVM --template=
diff --git a/user/templates/windows/windows-qubes-4-1.rst b/user/templates/windows/windows-qubes-4-1.rst
index 9d4c7aa0..be4ee5ef 100644
--- a/user/templates/windows/windows-qubes-4-1.rst
+++ b/user/templates/windows/windows-qubes-4-1.rst
@@ -130,14 +130,14 @@ Create a VM named WindowsNew in :doc:`HVM
@@ -406,7 +406,7 @@ On starting the AppVM, sometimes a message is displayed that the Xen PV Network
Furthermore, if manual IP setup was used for the template, the IP address selected for the template will also be used for the AppVM, as it inherits this address from the template. Qubes, however, will have assigned a different address to the AppVM, which will have to be changed to that of the template (e.g. 10.137.0.x) so that the AppVM can access the network, via the CLI command in a dom0 terminal:
-.. code:: bash
+.. code:: console
qvm-prefs WindowsNew ip 10.137.0.x
diff --git a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
index 7fc3bf58..82868e25 100644
--- a/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
+++ b/user/troubleshooting/app-menu-shortcut-troubleshooting.rst
@@ -52,7 +52,7 @@ In dom0, the ``qvm-appmenus`` tool allows the user to see the list of available
To change the whitelist shown in app menu, you need to provide a list of the desktop entries. Each line contains a desktop entry name, with its ``.desktop`` extension, like this:
-.. code:: bash
+.. code:: console
qubes-open-file-manager.desktop
qubes-run-terminal.desktop
@@ -78,7 +78,7 @@ You can manually create new entries in the “available applications” list of
2. Create a custom ``.desktop`` file in ``/usr/share/applications`` (you may need to first create the subdirectory). Look in ``/usr/share/applications`` for existing examples, or see the full `file specification `__. It will be something like:
- .. code:: bash
+ .. code:: desktop
[Desktop Entry]
Type=Application
@@ -111,7 +111,7 @@ To add a custom menu entry instead:
4. Add a custom menu entry referring to your newly created ``.desktop`` file.
- .. code:: bash
+ .. code:: xml