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