Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-05 21:24:15 -04:00
Code Issues Projects Releases Packages Wiki Activity

Correct code-block lexers

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

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

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

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

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

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

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

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

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

@ -38,7 +38,7 @@ Prepare fresh version of kernel sources, with Qubes-specific patches applied
In ``qubes-builder/artifacts/sources/linux-kernel``:
.. code:: bash
.. code:: console
make prep
@ -46,14 +46,9 @@ In ``qubes-builder/artifacts/sources/linux-kernel``:
The resulting tree will be in kernel-<VERSION>/linux-<VERSION>:
.. code:: bash
.. code:: console
ls -ltrd kernel*/linux*
.. code:: bash
drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18
drwxr-xr-x 6 user user 4096 Nov 21 20:48 kernel-3.4.18/linux-obj
@ -65,7 +60,7 @@ Go to the kernel tree and update the version
In ``qubes-builder/artifacts/sources/linux-kernel``:
.. code:: bash
.. code:: console
cd kernel-3.4.18/linux-3.4.18
@ -77,7 +72,7 @@ Changing the config
In ``kernel-3.4.18/linux-3.4.18``:
.. code:: bash
.. code:: console
cp ../../config .config
make oldconfig
@ -86,7 +81,7 @@ In ``kernel-3.4.18/linux-3.4.18``:
Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``:
.. code:: bash
.. code:: console
make menuconfig
@ -94,7 +89,7 @@ Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``:
Copy the modified config back into the kernel tree:
.. code:: bash
.. code:: console
cp .config ../../../config
@ -106,7 +101,7 @@ 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
@ -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
@ -347,7 +342,7 @@ In source VM, grab `linux-yum <https://GitHub.com/QubesOS/qubes-linux-yum>`__ re
In target VM, setup actual yum repository (also based on `linux-yum <https://GitHub.com/QubesOS/qubes-linux-yum>`__, this time without modifications). You will also need to setup some gpg key for signing packages (it is possible to force yum to install unsigned packages, but it isn’t possible for ``qubes-dom0-update`` tool). Fill ``~/.rpmmacros`` with key description:
.. code:: bash
.. code:: text
%_gpg_name Test packages signing key
@ -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
@ -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

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

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

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

@ -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,7 +84,7 @@ 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
@ -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

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

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

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

@ -68,7 +68,7 @@ In the example below, we will use ``keyserver.ubuntu.com``.
Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID** which is the last 16 hex digits of the long number in the second line of the output above:
.. code:: bash
.. code:: text
pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30]
87975838063F97A968D503266E2F4E7AF50A5827
@ -89,7 +89,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
1. Set up Git to use your key:
.. code:: bash
.. code:: console
git config --global user.signingkey <KEYID>
@ -97,14 +97,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
2. Set up Git to sign your commits with your key:
.. code:: bash
.. code:: console
git config --global commit.gpgsign true
Alternatively, manually specify when a commit is to be signed:
.. code:: bash
.. code:: console
git commit -S
@ -113,14 +113,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check.
This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history.
.. code:: bash
.. code:: console
git tag -s <tag_name> -m "<tag_message>"
You can also create an alias to make this easier. Edit your ``~/.gitconfig`` file. In the ``[alias]`` section, add ``stag`` to create signed tags and ``spush`` to create signed tags and push them.
.. code:: bash
.. code:: ini
[alias]
stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'"
@ -129,7 +129,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign
You may also find it convenient to have an alias for verifying the tag on the latest commit:
.. code:: bash
.. code:: console
vtag = !git tag -v `git describe`
@ -169,14 +169,14 @@ In this case, you have several options to sign the commit:
1. Amend the commit and replace it with a signed commit. You can use this command to create a new signed commit:
.. code:: bash
.. code:: console
git commit --amend -S
This also rewrites the commit so you need to push it forcefully:
.. code:: bash
.. code:: console
git push -f
@ -184,7 +184,7 @@ In this case, you have several options to sign the commit:
2. Create a signed tag for the unsigned commit. If the commit is back in history and you do not want to change it, you can create a signed tag for this commit and push the signature. You can use the alias from above:
.. code:: bash
.. code:: console
git checkout <commit>
git spush

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

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

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

@ -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

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

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

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

@ -78,7 +78,7 @@ 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
@ -94,7 +94,7 @@ 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
@ -117,7 +117,7 @@ Because of the above reason, some additional configurations need to be done to y
The following commands should work for you, but do keep in mind that the provisioning scripts are designed for the `openQA environment <https://openqa.qubes-os.org/>`__ and not your specific local testing system. Run the following in ``dom0``:
.. code:: bash
.. code:: console
# For future reference the following commands are an adaptation of
# https://github.com/marmarek/openqa-tests-qubesos/blob/master/tests/update.pm
@ -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
@ -220,7 +220,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$
``qtb-iterate``:
.. code:: bash
.. code:: console
#!/bin/sh
@ -247,7 +247,7 @@ 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
@ -258,7 +258,7 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked
``core-admin/.git/hooks/pre-push``:
.. code:: bash
.. code:: console
#!/bin/sh

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

@ -45,7 +45,7 @@ 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' %}
@ -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.

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

@ -32,7 +32,7 @@ For example, the following code can be used to run the ``qui-domains`` tool usin
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

4
developer/general/gsoc.rst
View file

@ -49,7 +49,7 @@ 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
@ -90,7 +90,7 @@ Project Ideas
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the :ref:`qubes-devel mailing list <introduction/support:qubes-devel>` and associated GitHub issue to learn more about the idea.
.. code::
.. code:: markdown
### Adding a Proposal

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

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

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

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

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

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

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

@ -91,7 +91,7 @@ Notes
- Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change ``*`` in the argument column to ``+`` (i.e., change “any argument” to “only empty”). To use the more restrictive behavior globally, add the following “deny” rule before all other relevant rules:
.. code:: bash
.. code:: text
qubes.Filecopy +allow-all-names @anyvm @anyvm deny

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

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

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

@ -15,7 +15,7 @@ When a Qubes RPC service is invoked, qrexec searches for a file that handles it
Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after ``QUBESRPC``. When running in a VM, this is:
.. code:: bash
.. code:: text
<service_name> <source>\0
@ -23,7 +23,7 @@ Before passing user input, the socket service will receive a null-terminated ser
When running in dom0, it is:
.. code:: bash
.. code:: text
<service_name> <source> <target_type> <target>\0
@ -81,7 +81,7 @@ 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
@ -100,7 +100,7 @@ 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
@ -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
@ -238,7 +238,7 @@ Using the service
The service is invoked in the same way as a standard Qubes RPC service:
.. code:: bash
.. code:: console
echo <input_data> | qrexec-client -d domX 'DEFAULT:QUBESRPC policy.Ask'
@ -246,7 +246,7 @@ The service is invoked in the same way as a standard Qubes RPC service:
You can also connect to it locally, but remember to include the service descriptor:
.. code:: bash
.. code:: console
echo -e 'policy.Ask dom0\0<input data>' | nc -U /etc/qubes-rpc/policy.Ask

16
developer/services/qrexec.rst
View file

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

14
developer/services/qrexec2.rst
View file

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

4
developer/system/networking.rst
View file

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

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

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

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

@ -9,7 +9,7 @@ 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; });

6
introduction/faq.rst
View file

@ -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 ``<BDF>`` with your device, for example ``00:1c.2``:
.. code:: bash
.. code:: console
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/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 <HVMname> 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.

2
introduction/issue-tracking.rst
View file

@ -207,7 +207,7 @@ Use collapsible sections for long, nonessential content
On GitHub, create collapsible sections in Markdown like so:
.. code:: bash
.. code:: html
<details>
<summary>Summary goes here. This line is optional.</summary>

2
introduction/statistics.rst
View file

@ -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)

2
project-security/security-pack.rst
View file

@ -129,7 +129,7 @@ History and rationale
On 2013-01-05, Joanna Rutkowska announced the qubes-secpack and explained its rationale in an `email <https://groups.google.com/d/msg/qubes-devel/twkOEaMLtNI/lZyGx6_jFCEJ>`__ to the Qubes mailing lists:
.. code:: bash
.. code:: console
Hello,

2
project-security/security.rst
View file

@ -31,7 +31,7 @@ Reporting security issues in Qubes OS
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) <https://www.qubes-os.org/security/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 <https://keys.qubes-os.org/keys/qubes-os-security-team-key.asc>`__ to encrypt your email to this address:
.. code:: bash
.. code:: console
security at qubes-os dot org

12
project-security/verifying-signatures.rst
View file

@ -107,7 +107,7 @@ So, what *should* you do? One option is to use the PGP `Web of Trust <https://en
Perhaps the most common route is to rely on the key’s fingerprint, which is a string of 40 alphanumeric characters, like this:
.. code:: bash
.. code:: text
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
@ -119,7 +119,7 @@ But how do you know which fingerprint is the real one? After all, :ref:`this web
For the purpose of convincing yourself that you know the authentic QMSK fingerprint, spaces and capitalization don’t matter. In other words, all of these fingerprints are considered the same:
.. code:: bash
.. code:: text
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
427f 11fd 0faa 4b08 0123 f01c ddfa 1a3e 3687 9494
@ -132,7 +132,7 @@ Instead, what matters is that *all* the characters are present in *exactly* the
However, for the purpose of *searching for*, *looking up*, or *entering* keys, spaces and capitalization can matter, depending on the software or tool you’re using. You may need to try different variations (e.g., with and without spaces). You may also sometimes see (or need to enter) the entire fingerprint prefixed with ``0x``, as in:
.. code:: bash
.. code:: text
0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
0x427f11fd0faa4b080123f01cddfa1a3e36879494
@ -167,7 +167,7 @@ Once you’ve observed enough matching fingerprints from enough independent sour
Now that you’ve imported the authentic QMSK, set its trust level to “ultimate” so that it can be used to automatically verify all the keys signed by the QMSK (in particular, RSKs).
.. code::
.. code:: console
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
@ -321,7 +321,7 @@ In addition to the ``.DIGESTS`` files on the `downloads <https://www.qubes-os.or
If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the digest file for that ISO is ``Qubes-RX-x86_64.iso.DIGESTS``, where ``X`` is a specific release of Qubes. The digest filename is always the same as the ISO filename followed by ``.DIGESTS``. Since the digest file is a plain text file, you can open it with any text editor. Inside, you should find text that looks similar to this:
.. code:: bash
.. code:: text
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
@ -458,7 +458,7 @@ Now, our goal is to perform the same verification steps as we did with the origi
This command reads exactly the number of bytes of your Qubes ISO (obtained with ``stat -c %s /path/to/iso``) from the USB drive and pipes them into ``sha256sum``. The output should look something like this:
.. code:: bash
.. code:: console
0e68dd3347b68618d9e5f3ddb580bf7ecdd2166747630859b3582803f1ca8801 -
5523+0 records in

14
user/advanced-topics/bind-dirs.rst
View file

@ -28,7 +28,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f
1. Make sure the directory ``/rw/config/qubes-bind-dirs.d`` exists.
.. code:: bash
.. code:: console
sudo mkdir -p /rw/config/qubes-bind-dirs.d
@ -36,7 +36,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f
2. Create the file ``/rw/config/qubes-bind-dirs.d/50_user.conf`` with root permissions, if it doesn’t already exist.
.. code:: bash
.. code:: console
sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf
@ -54,7 +54,7 @@ In this example, we want to make ``/var/lib/tor`` persistent. Enter all of the f
5. If the directory you wish to make persistent doesn’t exist in the template on which the app qube is based, you’ll need to create the directory (with its full path) under ``/rw/bind-dirs`` in the app qube. For example, if ``/var/lib/tor`` didn’t exist in the template, then you would execute the following command in your app qube:
.. code:: bash
.. code:: console
sudo mkdir -p /rw/bind-dirs/var/lib/tor
@ -155,7 +155,7 @@ Bind dirs are obviously still supported but this must be configured either in th
To use this feature, first, enable it:
.. code:: bash
.. code:: console
qvm-service -e my-app-vm custom-persist
@ -163,7 +163,7 @@ To use this feature, first, enable it:
Then, configure a persistent directory with ``qvm-features``:
.. code:: bash
.. code:: console
qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir
@ -171,7 +171,7 @@ Then, configure a persistent directory with ``qvm-features``:
To re-enable ``/home`` and ``/usr/local`` persistence, just add them to the list:
.. code:: bash
.. code:: console
qvm-features my-app-vm custom-persist.home /home
qvm-features my-app-vm custom-persist.usrlocal /usr/local
@ -182,7 +182,7 @@ When starting the VM, declared custom-persist bind dirs are automatically added
A user may want their bind-dirs to be automatically pre-created in ``/rw/bind-dirs``. Custom persist can do this for you by providing the type of the resource to create (file or dir), owner, group and mode. For example:
.. code:: bash
.. code:: console
qvm-features my-app-vm custom-persist.downloads dir:user:user:0755:/home/user/Downloads
qvm-features my-app-vm custom-persist.my_ssh_known_hosts_file file:user:user:0600:/home/user/.ssh/known_hosts

4
user/advanced-topics/config-files.rst
View file

@ -37,7 +37,7 @@ These files are placed in ``/rw``, which survives a VM restart. That way, they c
- In ProxyVMs (or app qubes with ``qubes-firewall`` service enabled), scripts placed in the following directories will be executed in the listed order followed by ``qubes-firewall-user-script`` at start up. Good place to write custom firewall rules.
.. code:: bash
.. code:: text
/etc/qubes/qubes-firewall.d
/rw/config/qubes-firewall.d
@ -84,7 +84,7 @@ GUI and audio configuration in dom0
The GUI configuration file ``/etc/qubes/guid.conf`` in one of a few not managed by ``qubes-prefs`` or the Qubes Manager tool. Sample config (included in default installation):
.. code:: bash
.. code::
# Sample configuration file for Qubes GUI daemon
# For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html

10
user/advanced-topics/disposable-customization.rst
View file

@ -93,7 +93,7 @@ You can use a :ref:`named disposable <user/reference/glossary:named disposable>`
To create one that has no PCI devices attached, such as for ``sys-firewall``:
.. code:: bash
.. code:: console
qvm-create -C DispVM -l green <SERVICE_QUBE>
qvm-prefs <SERVICE_QUBE> 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 <user/how-to-guides/how-to-use-pci-devices:\`\`qvm-pci\`\` usage>` the ``<BDF>``. Also, you will often need to include the ``-o no-strict-reset=True`` :ref:`option <user/how-to-guides/how-to-use-pci-devices:no-strict-reset>` with USB controllers.
.. code:: bash
.. code:: console
qvm-create -C DispVM -l red <SERVICE_QUBE>
qvm-prefs <SERVICE_QUBE> 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 <SERVICE_QUBE> 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 <SERVICE_QUBE>
@ -141,7 +141,7 @@ Also make sure to update any :doc:`RPC policies </user/advanced-topics/rpc-polic
Here is an example of a complete ``sys-net`` replacement:
.. code:: bash
.. code:: console
qvm-create -C DispVM -l red sys-net2
qvm-prefs sys-net2 virt_mode hvm

6
user/advanced-topics/gui-configuration.rst
View file

@ -14,7 +14,7 @@ When a qube starts, a fixed amount of RAM is allocated to the graphics buffer ca
To increase the minimum size of the video RAM buffer:
.. code:: bash
.. code:: console
qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
qvm-features dom0 gui-videoram-overhead 0
@ -24,7 +24,7 @@ Where ``$WIDTH`` × ``$HEIGHT`` is the maximum desktop size that you anticipate
In the case of multiple display with different orientations or if you plug/unplug displays, the following code will set correct memory size using xrandr.
.. code:: bash
.. code:: console
qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e 's/.*current //' -e 's/\,.*//' | awk '{print $1*$3*4/1024}')
@ -41,7 +41,7 @@ Default overhead is about 8 MiB, which is enough for a 1080p display (see above)
You might face issues when playing video, if the video is choppy instead of smooth display this could be because the X server doesn’t work. You can use the Linux terminal (Ctrl-Alt-F2) after starting the virtual machine, login. You can look at the Xorg logs file. As an option you can have the below config as well present in ``/etc/X11/xorg.conf.d/90-intel.conf`` (depends on HD graphics though).
.. code:: bash
.. code:: xorg.conf
Section "Device"
Identifier "Intel Graphics"

28
user/advanced-topics/gui-domain.rst
View file

@ -20,7 +20,7 @@ Here, we describe how to setup ``sys-gui`` that we call *hybrid mode* or referen
In ``dom0``, enable the formula for ``sys-gui`` with pillar data:
.. code:: bash
.. code:: console
sudo qubesctl top.enable qvm.sys-gui
sudo qubesctl top.enable qvm.sys-gui pillar=True
@ -28,14 +28,14 @@ In ``dom0``, enable the formula for ``sys-gui`` with pillar data:
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
You can now disable the ``sys-gui`` formula:
.. code:: bash
.. code:: console
sudo qubesctl top.disable qvm.sys-gui
@ -56,7 +56,7 @@ Here, we describe how to setup ``sys-gui-gpu`` which is a GUI domain with *GPU p
In ``dom0``, enable the formula for ``sys-gui-gpu`` with pillar data:
.. code:: bash
.. code:: console
sudo qubesctl top.enable qvm.sys-gui-gpu
sudo qubesctl top.enable qvm.sys-gui-gpu pillar=True
@ -64,21 +64,21 @@ In ``dom0``, enable the formula for ``sys-gui-gpu`` with pillar data:
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
You can now disable the ``sys-gui-gpu`` formula:
.. code:: bash
.. code:: console
sudo qubesctl top.disable qvm.sys-gui-gpu
One more step is needed: attaching the actual GPU to ``sys-gui-gpu``. This can be done either manually via ``qvm-pci`` (remember to enable permissive option), or via:
.. code:: bash
.. code:: console
sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu
@ -103,7 +103,7 @@ Here, we describe how to setup ``sys-gui-vnc`` that we call a *remote* GUI domai
In ``dom0``, enable the formula for ``sys-gui-vnc`` with pillar data:
.. code:: bash
.. code:: console
sudo qubesctl top.enable qvm.sys-gui-vnc
sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True
@ -111,21 +111,21 @@ In ``dom0``, enable the formula for ``sys-gui-vnc`` with pillar data:
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
You can now disable the ``sys-gui-vnc`` formula:
.. code:: bash
.. code:: console
sudo qubesctl top.disable qvm.sys-gui-vnc
At this point, you need to shutdown all your running qubes as the ``default_guivm`` qubes global property has been set to ``sys-gui-vnc``. Then, you can start ``sys-gui-vnc``:
.. code:: bash
.. code:: console
qvm-start sys-gui-vnc
@ -186,21 +186,21 @@ The following commands have to be run in ``dom0``.
Set ``default_guivm`` as ``dom0``:
.. code:: bash
.. code:: console
qubes-prefs default_guivm dom0
and for every selected qubes not using default value for GUI domain property, for example with a qube ``personal``:
.. code:: bash
.. code:: console
qvm-prefs personal guivm dom0
You are now able to delete the GUI domain, for example ``sys-gui-gpu``:
.. code:: bash
.. code:: console
qvm-remove -f sys-gui-gpu

20
user/advanced-topics/how-to-install-software-in-dom0.rst
View file

@ -46,7 +46,7 @@ How to downgrade a specific package
To downgrade a specific package in dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --action=downgrade package-version
@ -58,7 +58,7 @@ How to re-install a package
To re-install a package in dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --action=reinstall package
@ -70,7 +70,7 @@ How to uninstall a package
If you’ve installed a package such as anti-evil-maid, you can remove it with the following command:
.. code:: bash
.. code:: console
sudo dnf remove anti-evil-maid
@ -94,7 +94,7 @@ If you wish to install updates that are still in :doc:`testing </user/downloadin
To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` 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 <https://forum.qubes-os.org/t/19014>`__.
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`

10
user/advanced-topics/installing-contributed-packages.rst
View file

@ -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

8
user/advanced-topics/kde.rst
View file

@ -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,7 +82,7 @@ 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...
@ -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 <vm_name> -q --tray -a <vm_name> '<run_program_command>'
@ -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

20
user/advanced-topics/managing-vm-kernels.rst
View file

@ -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 <clonetemplatename> virt_mode hvm
qvm-prefs <clonetemplatename> 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 <kernel-version>
@ -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

2
user/advanced-topics/mount-from-other-os.rst
View file

@ -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

2
user/advanced-topics/qubes-service.rst
View file

@ -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 name>.service.d/30_qubes.conf``. It should contain the following:
.. code:: bash
.. code:: systemd
[Unit]
ConditionPathExists=/var/run/qubes-service/<service name>

8
user/advanced-topics/resize-disk-image.rst
View file

@ -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 <vm_name>:root <size>
@ -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 <vm_name>:private <size>
@ -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

28
user/advanced-topics/salt.rst
View file

@ -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 <https://docs.saltproject.io/en/latest/ref/states/ordering.html>`__ 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 <https://docs.saltproject.io/en/latest/ref/states/top.html>`__). 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,7 +193,7 @@ 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]
@ -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:

44
user/advanced-topics/secondary-storage.rst
View file

@ -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
<file> refers to using a simple file for image storage and lacks a few features.
<file-reflink> 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 <https://ac
First, collect some information in a dom0 terminal:
.. code:: bash
.. code:: console
sudo pvs
sudo lvs
@ -56,7 +56,7 @@ First, collect some information in a dom0 terminal:
Take note of the VG and thin pool names for your second drive., then register it with Qubes:
.. code:: bash
.. code:: console
# <pool_name> is a freely chosen pool name
# <vg_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
# <pool_name> is a freely chosen pool name
# <dir_path> 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 <pool_name> --label red <vmname>
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 <pool_name> <sourceVMname> <cloneVMname>
qvm-remove <sourceVMname>
@ -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 <appvmname_based_on_old_template> template <new_template_name>
@ -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
# <label> Btrfs Label
sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
@ -184,7 +184,7 @@ First create the physical volume:
Then mount the new Btrfs to a temporary path:
.. code:: bash
.. code:: console
sudo mkdir -p /mnt/new_qube_storage
sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
@ -192,7 +192,7 @@ Then mount the new Btrfs to a temporary path:
Create a subvolume to hold the data:
.. code:: bash
.. code:: console
sudo btrfs subvolume create /mnt/new_qube_storage/qubes
@ -200,7 +200,7 @@ Create a subvolume to hold the data:
Unmount the temporary Btrfs filesystem:
.. code:: bash
.. code:: console
sudo umount /mnt/new_qube_storage
rmdir /mnt/new_qube_storage
@ -208,7 +208,7 @@ Unmount the temporary Btrfs filesystem:
Mount the subvolume with compression enabled if desired:
.. code:: bash
.. code:: console
# <compression> zlib|lzo|zstd
# <subvol> btrfs subvolume "qubes" in this example
@ -217,14 +217,14 @@ Mount the subvolume with compression enabled if desired:
Finally we will tell Qubes to add a new pool on the just created Btrfs subvolume:
.. code:: bash
.. code:: console
qvm-pool --add poolhd0_qubes file-reflink -o dir_path=/var/lib/qubes_newpool,revisions_to_keep=2
By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary drive do the following on a dom0 terminal:
.. code:: bash
.. code:: console
qvm-create -P poolhd0_qubes --label red unstrusted-hdd

38
user/advanced-topics/standalones-and-hvms.rst
View file

@ -44,7 +44,7 @@ You can create a standalone in the Qube Manager by selecting the “Type” of
Alternatively, to create an empty standalone from the dom0 command line:
.. code:: bash
.. code:: console
qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm <NEW_STANDALONE_NAME>
@ -52,7 +52,7 @@ Alternatively, to create an empty standalone from the dom0 command line:
Or to create a standalone copied from a template:
.. code:: bash
.. code:: console
qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm --template <TEMPLATE_QUBE_NAME> <NEW_STANDALONE_NAME>
@ -88,7 +88,7 @@ Command line
Qubes are template-based (i.e., :ref:`app qubes <user/reference/glossary:app qube>` by default, so you must set the ``--class StandaloneVM`` option to create a standalone. The name and label color used below are for illustration purposes.
.. code:: bash
.. code:: console
qvm-create my-new-vm --class StandaloneVM --property virt_mode=hvm --property kernel='' --label=green
@ -96,7 +96,7 @@ Qubes are template-based (i.e., :ref:`app qubes <user/reference/glossary:app qub
If you receive an error like this one, then you must first enable VT-x in your BIOS:
.. code:: bash
.. code:: text
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
@ -112,7 +112,7 @@ You will have to boot the qube with the installation media “attached” to it.
1. If you have the physical CD-ROM media and an optical disc drive:
.. code:: bash
.. code:: console
qvm-start <YOUR_HVM> --cdrom=/dev/cdrom
@ -120,7 +120,7 @@ You will have to boot the qube with the installation media “attached” to it.
2. If you have an ISO image of the installation media located in dom0:
.. code:: bash
.. code:: console
qvm-start <YOUR_HVM> --cdrom=dom0:/usr/local/iso/<YOUR_INSTALLER.ISO>
@ -128,7 +128,7 @@ You will have to boot the qube with the installation media “attached” to it.
3. If you have an ISO image of the installation media located in a qube (the qube where the media is located must be running):
.. code:: bash
.. code:: console
qvm-start <YOUR_HVM> --cdrom=<YOUR_OTHER_QUBE>:/home/user/<YOUR_INSTALLER.ISO>
@ -203,7 +203,7 @@ Qubes allows HVMs to share a common root filesystem from a select template. This
In order to create an HVM template, you use the following command, suitably adapted:
.. code:: bash
.. code:: console
qvm-create --class TemplateVM <YOUR_HVM_TEMPLATE_NAME> --property virt_mode=HVM --property kernel='' -l <YOUR_COLOR>
@ -379,7 +379,7 @@ About 60 GB of disk space is required for conversion. Use an external hard drive
In a Debian app qube, install ``qemu-utils`` and ``unzip``:
.. code:: bash
.. code:: console
sudo apt install qemu-utils unzip
@ -387,7 +387,7 @@ In a Debian app qube, install ``qemu-utils`` and ``unzip``:
In a Fedora app qube:
.. code:: bash
.. code:: console
sudo dnf install qemu-img
@ -395,7 +395,7 @@ In a Fedora app qube:
Unzip VirtualBox zip file:
.. code:: bash
.. code:: console
unzip *.zip
@ -403,7 +403,7 @@ Unzip VirtualBox zip file:
Extract OVA tar archive:
.. code:: bash
.. code:: console
tar -xvf *.ova
@ -411,7 +411,7 @@ Extract OVA tar archive:
Convert vmdk to raw:
.. code:: bash
.. code:: console
qemu-img convert -O raw *.vmdk win10.raw
@ -419,7 +419,7 @@ Convert vmdk to raw:
Copy the root image file from the originating qube (here called ``untrusted``) to a temporary location in dom0, typing this in a dom0 terminal:
.. code:: bash
.. code:: console
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /home/user/win10-root.img
@ -427,7 +427,7 @@ Copy the root image file from the originating qube (here called ``untrusted``) t
From within dom0, create a new HVM (here called ``win10``) with the root image we just copied to dom0 (change the amount of RAM in GB as you wish):
.. code:: bash
.. code:: console
qvm-create --property=virt_mode=hvm --property=memory=4096 --property=kernel='' --label red --standalone --root-move-from /home/user/win10-root.img win10
@ -435,7 +435,7 @@ From within dom0, create a new HVM (here called ``win10``) with the root image w
Start ``win10``:
.. code:: bash
.. code:: console
qvm-start win10
@ -447,7 +447,7 @@ Optional ways to get more information
Filetype of OVA file:
.. code:: bash
.. code:: console
file *.ova
@ -455,7 +455,7 @@ Filetype of OVA file:
List files of OVA tar archive:
.. code:: bash
.. code:: console
tar -tf *.ova
@ -463,7 +463,7 @@ List files of OVA tar archive:
List filetypes supported by qemu-img:
.. code:: bash
.. code:: console
qemu-img -h | tail -n1

16
user/advanced-topics/usb-qubes.rst
View file

@ -28,7 +28,7 @@ If you’re reading this section, it’s likely because the installer did not al
First, make sure you have the latest ``qubes-mgmt-salt-dom0-virtual-machines`` package by :ref:`updating dom0 <user/advanced-topics/how-to-install-software-in-dom0:how to update dom0>`. Then, enter the following command in dom0:
.. code:: bash
.. code:: console
sudo qubesctl state.sls qvm.usb-keyboard
@ -46,7 +46,7 @@ Manual setup for USB keyboards
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0. Edit the ``qubes.InputKeyboard`` policy file in dom0, which is located here:
.. code:: bash
.. code:: text
/etc/qubes-rpc/policy/qubes.InputKeyboard
@ -54,7 +54,7 @@ In order to use a USB keyboard, you must first attach it to a USB qube, then giv
Add a line like this one to the top of the file:
.. code:: bash
.. code:: text
sys-usb dom0 allow
@ -66,7 +66,7 @@ You can now use your USB keyboard to log in to your dom0 user account (after LUK
You can set up your system so that there’s a confirmation prompt each time the USB keyboard is connected. However, this will effectively disable your USB keyboard for dom0 user account login and the screen locker, so **don’t do this if you want to log into and unlock your device with a USB keyboard!** If you’re sure you wish to proceed, change the previous line to:
.. code:: bash
.. code:: text
sys-usb dom0 ask,default_target=dom0
@ -110,7 +110,7 @@ Handling a USB mouse isn’t as critical as handling a keyboard, since you can l
If you want to attach the USB mouse automatically anyway, you have to edit the ``qubes.InputMouse`` policy file in dom0, located at:
.. code:: bash
.. code:: text
/etc/qubes-rpc/policy/qubes.InputMouse
@ -118,7 +118,7 @@ If you want to attach the USB mouse automatically anyway, you have to edit the `
The first line should read similar to:
.. code:: bash
.. code:: text
sys-usb dom0 ask,default_target=dom0
@ -130,7 +130,7 @@ If the file is empty or does not exist, something might have gone wrong during s
In case you are absolutely sure you do not want to confirm mouse access from ``sys-usb`` to ``dom0``, you may add the following line to the top of the file:
.. code:: bash
.. code:: text
sys-usb dom0 allow
@ -146,7 +146,7 @@ If `automatically creating a USB qube for use with a USB keyboard <#how-to-creat
You can create a USB qube using the management stack by executing the following command as root in dom0:
.. code:: bash
.. code:: console
sudo qubesctl state.sls qvm.sys-usb

6
user/advanced-topics/volume-backup-revert.rst
View file

@ -12,7 +12,7 @@ In Qubes, when you create a new VM, it’s volumes are stored in one of the syst
For the private volume associated with a VM named *vmname*, you may inspect the value of ``revisions_to_keep`` from the dom0 CLI as follows:
.. code:: bash
.. code:: console
qvm-volume info vmname:private
@ -20,7 +20,7 @@ For the private volume associated with a VM named *vmname*, you may inspect the
The output of the above command will also display the “Available revisions (for revert)” at the bottom. For a very large volume in a small pool, ``revisions_to_keep`` should probably be set to the maximum value of 1 to minimize the possibility of the pool being accidentally filled up by snapshots. For a smaller volume for which you would like to have the future option of reverting, ``revisions_to_keep`` should probably be set to at least 2. To set ``revisions_to_keep`` for this same VM / volume example:
.. code:: bash
.. code:: console
qvm-volume config vmname:private revisions_to_keep 2
@ -28,7 +28,7 @@ The output of the above command will also display the “Available revisions (fo
With the VM stopped, you may revert to an older snapshot of the private volume from the above list of “Available revisions (for revert)”, where the last item on the list with the largest integer is the most recent snapshot:
.. code:: bash
.. code:: console
qvm-volume revert vmname:private <revision>

2
user/downloading-installing-upgrading/testing.rst
View file

@ -62,7 +62,7 @@ How to test :doc:`templates </user/templates/templates>`:
To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` option. Example commands:
.. code:: bash
.. code:: console
qvm-template --enablerepo=qubes-templates-itl-testing list --available
qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>

6
user/downloading-installing-upgrading/upgrade/2.rst
View file

@ -31,7 +31,7 @@ Note that dom0 in R2 is based on Fedora 20, in contrast to Fedora 18 in previous
2. Install all the updates for Dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update
@ -49,7 +49,7 @@ After this step you should have ``qubes-release-2-5`` in your Dom0. Important: i
**Note:** be sure that the VM used as a update-downloading-vm (by default its the firewallvm based on the default template) has been updated to the latest Qubes packages, specifically ``qubes-core-vm-2.1.33`` or later. This doesn’t imply that the VM must already be upgraded to fc20 – for Dom0 upgrade we could still use an fc18-based VM (updatevm) it is only important to install the latest Qubes packages there.
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-dom0-dist-upgrade
sudo qubes-dom0-update
@ -64,7 +64,7 @@ After this step you should have ``qubes-release-2-5`` in your Dom0. Important: i
4a. If you chose not to upgrade your fc18 templates, but instead to download our new fc20-based template you should now be able to do that by simply typing:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-template-fedora-20-x64

10
user/downloading-installing-upgrading/upgrade/2b1.rst
View file

@ -19,7 +19,7 @@ By default, in Qubes R1, there is only one template, however users are free to c
2. Install ``qubes-upgrade-vm`` package (this package brings in R2 repo definitions and R2 keys)
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
@ -27,14 +27,14 @@ By default, in Qubes R1, there is only one template, however users are free to c
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
.. code:: bash
.. code:: console
sudo yum update
The installer (yum) will prompt to accept the new Qubes R2 signing key:
.. code:: bash
.. code:: text
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
@ -70,7 +70,7 @@ Be sure to do steps described in this section after *all* your template and stan
2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-release
@ -79,7 +79,7 @@ Be sure to do steps described in this section after *all* your template and stan
3. Install R2 packages:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=2

14
user/downloading-installing-upgrading/upgrade/2b2.rst
View file

@ -17,7 +17,7 @@ By default, in Qubes R1, there is only one template, however users are free to c
2. Install ``qubes-upgrade-vm`` package (this package brings in R2 repo definitions and R2 keys)
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
@ -25,14 +25,14 @@ By default, in Qubes R1, there is only one template, however users are free to c
3. Proceed with normal update in the template (this should bring in also the R2 packages for the VMs):
.. code:: bash
.. code:: console
sudo yum update
The installer (yum) will prompt to accept the new Qubes R2 signing key:
.. code:: bash
.. code:: text
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
@ -86,7 +86,7 @@ Be sure to do steps described in this section after *all* your template and stan
2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-release
@ -95,7 +95,7 @@ Be sure to do steps described in this section after *all* your template and stan
3. Install R2 upgrade package:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
@ -103,7 +103,7 @@ Be sure to do steps described in this section after *all* your template and stan
4. Start upgrade process:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade
@ -115,7 +115,7 @@ Be sure to do steps described in this section after *all* your template and stan
7. When system starts up, login and start start
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade

12
user/downloading-installing-upgrading/upgrade/2b3.rst
View file

@ -21,7 +21,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
2. Proceed with normal update in the template:
.. code:: bash
.. code:: console
sudo yum update
@ -29,7 +29,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
3. Ensure that you’ve got qubes-core-vm package version 2.1.13-3.fc18:
.. code:: bash
.. code:: console
rpm -q qubes-core-vm
@ -37,7 +37,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
4. Update the system to R2 beta3 packages:
.. code:: bash
.. code:: console
sudo yum --enablerepo=qubes-vm-r2b3-current update
@ -57,7 +57,7 @@ Be sure to do steps described in this section after *all* your template and stan
2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-release
@ -66,7 +66,7 @@ Be sure to do steps described in this section after *all* your template and stan
3. Upgrade dom0 to R2 beta3:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
@ -76,7 +76,7 @@ Be sure to do steps described in this section after *all* your template and stan
5. Now is the time to shutdown all the VMs:
.. code:: bash
.. code:: console
qvm-shutdown --all --wait

22
user/downloading-installing-upgrading/upgrade/3_0.rst
View file

@ -27,7 +27,7 @@ Upgrade Fedora template:
2. Install ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
@ -35,7 +35,7 @@ Upgrade Fedora template:
3. Proceed with normal update in the template:
.. code:: bash
.. code:: console
sudo yum update
@ -54,7 +54,7 @@ Upgrade Debian template:
2. Update repository definition:
.. code:: bash
.. code:: console
sudo cp /etc/apt/sources.list.d/qubes-r2.list
/etc/apt/sources.list.d/qubes-r3-upgrade.list
@ -64,7 +64,7 @@ Upgrade Debian template:
3. Proceed with normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
@ -86,7 +86,7 @@ Be sure to do steps described in this section after *all* your template and stan
2. Upgrade the ``qubes-release`` package to the latest version which brings in new repo definitions and R2 signing keys:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-release
@ -95,7 +95,7 @@ Be sure to do steps described in this section after *all* your template and stan
3. Upgrade dom0 to R3.0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=3.0
@ -106,7 +106,7 @@ Be sure to do steps described in this section after *all* your template and stan
5. Enable Xen services:
.. code:: bash
.. code:: console
sudo systemctl enable xenconsoled.service xenstored.service
@ -124,7 +124,7 @@ Please note that if you use Anti Evil Maid, then it won’t be able to unseal th
Now, when you have dom0 upgraded, you can install new templates from Qubes R3.0 repositories. Especially Fedora 21 - default Qubes R3.0 template:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-template-fedora-21
@ -161,7 +161,7 @@ Because of above limitations, you will need to configure some of those manually.
2. Start the VM from command line:
.. code::
.. code:: console
[user@dom0 ~]$ qvm-start custom-template
--> Loading the VM (type = template)...
@ -177,14 +177,14 @@ Because of above limitations, you will need to configure some of those manually.
3. Access VM console:
.. code::
.. code:: console
[user@dom0 ~]$ virsh -c xen:/// console custom-template
4. Configure network according to parameters retrieved in first step:
.. code:: bash
.. code:: console
ip addr add 10.137.1.53/32 dev eth0
ip route add 10.137.1.1/32 dev eth0

14
user/downloading-installing-upgrading/upgrade/3_1.rst
View file

@ -21,7 +21,7 @@ Upgrade Fedora templates:
2. Install the ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
@ -29,7 +29,7 @@ Upgrade Fedora templates:
3. Proceed with a normal upgrade in the template:
.. code:: bash
.. code:: console
sudo yum upgrade
@ -47,7 +47,7 @@ Upgrade Debian (and Whonix) templates:
2. Update repository definition:
.. code:: bash
.. code:: console
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.0/r3.1/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
@ -56,7 +56,7 @@ Upgrade Debian (and Whonix) templates:
3. Proceed with a normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
@ -65,7 +65,7 @@ Upgrade Debian (and Whonix) templates:
4. Remove unnecessary now file:
.. code:: bash
.. code:: console
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
@ -85,7 +85,7 @@ Upgrading dom0
2. Upgrade dom0 to R3.1:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=3.1
@ -108,7 +108,7 @@ If you use USB VM, you may encounter problem with starting it on updated Xen ver
Once you have upgraded dom0, you can install new templates from Qubes R3.1 repositories, in particular the new default Fedora 23 template:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-template-fedora-23

24
user/downloading-installing-upgrading/upgrade/3_2.rst
View file

@ -17,7 +17,7 @@ Upgrading dom0
3. Install ``qubes-release`` package carrying R3.2 repository information.
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=3.2 qubes-release
@ -29,7 +29,7 @@ Upgrading dom0
.. code:: bash
.. code:: console
sudo qubes-dom0-update systemd-compat-libs perl-libwww-perl perl-Term-ANSIColor perl-Term-Cap gdk-pixbuf2-xlib speexdsp qubes-mgmt-salt-admin-tools lvm2
(...)
@ -48,7 +48,7 @@ Upgrading dom0
4. Upgrade dom0 to R3.2:
.. code:: bash
.. code:: console
sudo qubes-dom0-update
@ -66,7 +66,7 @@ Upgrading dom0
.. code:: bash
.. code:: text
warning: /etc/salt/minion.d/f_defaults.conf created as /etc/salt/minion.d/f_defaults.conf.rpmnew
@ -76,7 +76,7 @@ Upgrading dom0
.. code:: bash
.. code:: console
rm -f /etc/group.rpmnew
rm -f /etc/shadow.rpmnew
@ -116,7 +116,7 @@ Upgrade Fedora templates:
2. Install the ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo dnf install --refresh qubes-upgrade-vm
@ -124,7 +124,7 @@ Upgrade Fedora templates:
3. Proceed with a normal upgrade in the template:
.. code:: bash
.. code:: console
sudo dnf upgrade --refresh
@ -132,7 +132,7 @@ Upgrade Fedora templates:
4. Add new packages (only needed in default template):
.. code:: bash
.. code:: console
sudo dnf install qubes-mgmt-salt-vm-connector
@ -150,7 +150,7 @@ Upgrade Debian (and Whonix) templates:
2. Update repository definition:
.. code:: bash
.. code:: console
sudo cp /etc/apt/sources.list.d/qubes-r3.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
sudo sed -i 's/r3.1/r3.2/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
@ -159,7 +159,7 @@ Upgrade Debian (and Whonix) templates:
3. Proceed with a normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
@ -168,7 +168,7 @@ Upgrade Debian (and Whonix) templates:
4. Add new packages (only needed in default template):
.. code:: bash
.. code:: console
sudo apt-get install qubes-mgmt-salt-vm-connector
@ -176,7 +176,7 @@ Upgrade Debian (and Whonix) templates:
5. Remove unnecessary now file:
.. code:: bash
.. code:: console
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list

2
user/downloading-installing-upgrading/upgrade/4_0.rst
View file

@ -63,7 +63,7 @@ Restore from your backup
2. Since patches may have been released since your installation image was created, update Qubes R4.0 by going to the dom0 command line (**Qubes menu -> Terminal Emulator**) then running:
.. code:: bash
.. code:: console
sudo qubes-dom0-update

8
user/downloading-installing-upgrading/upgrade/4_1.rst
View file

@ -37,7 +37,7 @@ The upgrade may take several hours, and will download several gigabytes of data.
In place upgrade is a complex operation. For this reason, we provide a ``qubes-dist-upgrade`` tool to handle all the necessary steps automatically. You can install it with the following command in the dom0 terminal:
.. code:: bash
.. code:: console
sudo qubes-dom0-update -y qubes-dist-upgrade
@ -47,7 +47,7 @@ The upgrade consists of seven stages — six before restarting the system — la
Full list of options can be obtained with ``qubes-dist-upgrade --help``:
.. code:: bash
.. code:: text
Usage: qubes-dist-upgrade [OPTIONS]...
@ -82,7 +82,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
After installing the tool, upgrade can be performed all at once with:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade --all
@ -94,7 +94,7 @@ Alternatively, each upgrade stage can be started separately (see the list of opt
After completing “STAGE 0” through “STAGE 5”, restart the system. Then perform the final step:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade --resync-appmenus-features

12
user/downloading-installing-upgrading/upgrade/4_2.rst
View file

@ -21,7 +21,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla
2. Install the ``qubes-dist-upgrade`` tool. This is the inplace upgrade tool, which is not what we’re doing. However it will be needed in order to prepare the templates for the 4.2 version. You install it with the following command in the dom0 terminal:
.. code:: bash
.. code:: console
sudo qubes-dom0-update -y qubes-dist-upgrade
@ -29,7 +29,7 @@ If you would prefer to perform a clean installation rather than upgrading in-pla
3. Change your templates to use the 4.2 repositories instead of the 4.1 ones. You do this with the following command in the dom0 terminal:
.. code:: bash
.. code:: console
qubes-dist-upgrade --template-standalone-upgrade
@ -56,7 +56,7 @@ The upgrade may take several hours, and will download several gigabytes of data.
In place upgrade is a complex operation. For this reason, we provide a ``qubes-dist-upgrade`` tool to handle all the necessary steps automatically. You can install it with the following command in the dom0 terminal:
.. code:: bash
.. code:: console
sudo qubes-dom0-update -y qubes-dist-upgrade
@ -66,7 +66,7 @@ The upgrade consists of six stages — three before restarting the system — la
Full list of options can be obtained with ``qubes-dist-upgrade --help``:
.. code:: bash
.. code:: text
Usage: qubes-dist-upgrade [OPTIONS]...
@ -102,7 +102,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
After installing the tool, before-reboot stages can be performed at once with:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade --all-pre-reboot
@ -114,7 +114,7 @@ Alternatively, each upgrade stage can be started separately (see the list of opt
After completing “STAGE 1” through “STAGE 3”, restart the system. Then perform the final steps:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade --all-post-reboot

2
user/how-to-guides/backup-emergency-restore-v2.rst
View file

@ -71,7 +71,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
**Note:** For multi-part files, a loop can be used:
.. code:: bash
.. code:: console
find -name 'private.img.*' | sort -V | while read f; do
openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in $f -out

6
user/how-to-guides/how-to-copy-and-move-files.rst
View file

@ -15,7 +15,7 @@ For simplicity, these instructions will refer to copying/moving a single file, b
3. If the target qube is not already running, it will be started automatically, and the file will be copied there. It will show up in this directory (which will automatically be created if it does not already exist):
.. code:: bash
.. code:: text
/home/user/QubesIncoming/<source_qube>/<filename>
@ -28,13 +28,13 @@ For simplicity, these instructions will refer to copying/moving a single file, b
The same operations are also available via these command-line tools:
.. code:: bash
.. code:: console
qvm-copy [--without-progress] file [file]+
.. code:: bash
.. code:: console
qvm-move [--without-progress] file [file]+

8
user/how-to-guides/how-to-copy-and-paste-text.rst
View file

@ -43,7 +43,7 @@ Clipboard automatic policy enforcement
The Qubes clipboard :doc:`RPC policy </user/advanced-topics/rpc-policy>` is configurable in:
.. code:: bash
.. code:: console
/etc/qubes-rpc/policy/qubes.ClipboardPaste
@ -51,7 +51,7 @@ The Qubes clipboard :doc:`RPC policy </user/advanced-topics/rpc-policy>` is conf
You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your “vault” app qube (and it is highly recommended that you do not), then you should edit the policy as follows:
.. code:: bash
.. code:: text
@anyvm vault deny
@anyvm @anyvm ask
@ -66,7 +66,7 @@ By default data pasted into a qube will remain there until user copies something
To enable automatic wiping of the clipboard after a minute use ``qvm-service``:
.. code:: bash
.. code:: console
qvm-service --enable VMNAME gui-agent-clipboard-wipe
@ -78,7 +78,7 @@ Shortcut configuration
The copy/paste shortcuts are configurable via ``qvm-features``, e.g.
.. code:: bash
.. code:: console
qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'

6
user/how-to-guides/how-to-copy-from-dom0.rst
View file

@ -15,7 +15,7 @@ Copying files from dom0
To copy a file from dom0 to a VM, simply use ``qvm-copy-to-vm``:
.. code:: bash
.. code:: console
qvm-copy-to-vm <target_vm> <file>
@ -71,7 +71,7 @@ There should normally be few reasons for the user to want to copy anything from
If you are determined to copy some files to dom0 anyway, you can use the following method. (If you want to copy text, first save it into a text file.) Run this command in a dom0 terminal:
.. code:: bash
.. code:: console
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
@ -79,7 +79,7 @@ If you are determined to copy some files to dom0 anyway, you can use the followi
Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don’t want to use ``qvm-copy-to-vm``):
.. code:: bash
.. code:: console
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'

4
user/how-to-guides/how-to-enter-fullscreen-mode.rst
View file

@ -31,7 +31,7 @@ You can always put a window into fullscreen mode in Xfce4 using the trusted wind
As an alternative to the Xfce4 method, you can enable fullscreen mode for select VMs by creating the following entry in the ``/etc/qubes/guid.conf`` file in dom0:
.. code:: bash
.. code:: console
VM: {
personal: {
@ -47,7 +47,7 @@ The string ‘personal’ above is an example only and should be replaced by the
One can also enable this functionality for all the VMs globally in the same file, by modifying the ‘global’ section:
.. code:: bash
.. code:: text
global: {
# default values

10
user/how-to-guides/how-to-install-software.rst
View file

@ -155,7 +155,7 @@ There are three Qubes VM testing repositories (where ``*`` denotes the Release):
To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` option. Example commands:
.. code:: bash
.. code:: console
sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
@ -193,7 +193,7 @@ RPMFusion for Fedora templates
If you would like to enable the `RPM Fusion <https://rpmfusion.org/>`__ repositories, open a Terminal of the template and type the following commands, depending on which RPM Fusion repositories you wish to enable (see `RPM Fusion <https://rpmfusion.org/>`__ for details):
.. code:: bash
.. code:: console
sudo dnf config-manager setopt rpmfusion-free.enabled=1
sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
@ -229,7 +229,7 @@ Root revert
2. In a dom0 terminal:
.. code:: bash
.. code:: console
qvm-volume revert <template>:root
@ -281,7 +281,7 @@ The updates proxy uses RPC/qrexec. The proxy is configured in qrexec policy in d
Example policy file in R4.1 (with Whonix installed, but not set as default UpdateVM for all templates):
.. code:: bash
.. code:: console
# any VM with tag `whonix-updatevm` should use `sys-whonix`; this tag is added to `whonix-gw` and `whonix-ws` during installation and is preserved during template clone
@tag:whonix-updatevm @default allow,target=sys-whonix
@ -337,7 +337,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
You may see the following message:
.. code:: bash
.. code:: console
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
/usr/sbin/semodule: Failed!

2
user/how-to-guides/how-to-organize-your-qubes.rst
View file

@ -15,7 +15,7 @@ Alice, the software developer
Alice is a freelance dev who works on several projects for different clients simultaneously. The projects have varying requirements and often different build environments. She has a separate set of qubes for each project. She keeps them organized by coming up with a naming scheme, such as:
.. code:: bash
.. code:: text
clientA-code
clientA-build

12
user/how-to-guides/how-to-reinstall-a-template.rst
View file

@ -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 <template-package-name>
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=<optional-additional-repo> \
<template-package-name>
For example, to install the ``whonix-gw`` template:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update --enablerepo=qubes-templates-community \
qubes-template-whonix-gw

2
user/how-to-guides/how-to-update.rst
View file

@ -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

34
user/how-to-guides/how-to-use-block-storage-devices.rst
View file

@ -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 <https://github.com/QubesOS/qubes-issues/issues/108
2. Attach the device manually to the same VM using the ``xl block-attach`` command. It is important to use the same “frontend” device name (by default, ``xvdi``). You can get it from the ``qvm-block`` listing:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
@ -175,7 +175,7 @@ To attach a file as block device to another qube, first turn it into a loopback
1. In the linux sourceVM run
.. code:: bash
.. code:: console
sudo losetup -f --show /path/to/file
@ -190,7 +190,7 @@ To attach a file as block device to another qube, first turn it into a loopback
.. code:: bash
.. code:: console
~]$ qvm-block
BACKEND:DEVID DESCRIPTION USED BY
@ -199,7 +199,7 @@ To attach a file as block device to another qube, first turn it into a loopback
3. Attach the ``loop0``-device using qvm-block as usual:
.. code:: bash
.. code:: console
qvm-block a targetVM sourceVM:loop0
@ -207,7 +207,7 @@ To attach a file as block device to another qube, first turn it into a loopback
4. After detaching, destroy the loop-device inside the sourceVM as follows:
.. code:: bash
.. code:: console
sudo losetup -d /dev/loop0
@ -229,7 +229,7 @@ This option allows you to specify the name of the device node made available in
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
@ -247,7 +247,7 @@ If the device is a read-only device, this option is forced true.
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o read-only=true
@ -255,7 +255,7 @@ usage example:
There exists a shortcut to set read-only ``true``, ``--ro``:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 --ro
@ -271,7 +271,7 @@ Usually, a block device is attached as disk. In case you need to attach a block
usage example:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 -o devtype=cdrom

18
user/how-to-guides/how-to-use-disposables.rst
View file

@ -63,7 +63,7 @@ On a fresh installation of Qubes, the default disposable template is called ``fe
You can set any app qube to have the ability to act as a disposable template with:
.. code:: bash
.. code:: console
qvm-prefs <APP_QUBE> 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 <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
@ -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 <DISPOSABLE_TEMPLATE> 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=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
@ -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 <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). 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 <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). It is possible to start an arbitrary application in a disposable directly from dom0 by running:
.. code:: bash
.. code:: console
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --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:<ONLINE_DISPOSABLE_TEMPLATE> 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:<ONLINE_DISPOSABLE_TEMPLATE> allow

12
user/how-to-guides/how-to-use-pci-devices.rst
View file

@ -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 ``<BDF>`` with your full device, for example ``0000:00:1c.2``:
.. code:: bash
.. code:: console
echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`

22
user/how-to-guides/how-to-use-usb-devices.rst
View file

@ -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 </user/how-to-guides/how-to-use-pci-devices>` 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

2
user/security-in-qubes/anti-evil-maid.rst
View file

@ -23,7 +23,7 @@ Installing
In Dom0 install ``anti-evil-maid``:
.. code:: bash
.. code:: console
sudo qubes-dom0-update anti-evil-maid

4
user/security-in-qubes/ctap-proxy.rst
View file

@ -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

48
user/security-in-qubes/firewall.rst
View file

@ -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/<vm-name>/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 <vm> netvm <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 address of A> ip daddr <IP address of B> 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 <IP address of A> 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,7 +247,7 @@ 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
@ -263,7 +263,7 @@ 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
@ -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,7 +397,7 @@ 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
@ -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
@ -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
@ -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 <https://www.tc
For instance, if you want to check if your network interface ``eth0`` is receiving packets on port TCP 443 from the network 192.168.x.y, you can run this command:
.. code:: bash
.. code:: console
tcpdump -i eth0 -nn dst port 443 and src net 192.168.x.y/24
@ -565,7 +565,7 @@ By adding ``flush ruleset`` at the top of the file, you can achieve atomic updat
You can dump the ruleset in two files using the following command:
.. code:: bash
.. code:: console
nft list ruleset | tee nft_backup | tee nft_new_ruleset
@ -575,7 +575,7 @@ Then, edit ``nft_new_ruleset``, add ``flush ruleset`` on top and make changes, l
You can revert to the original ruleset with the following commands:
.. code:: bash
.. code:: console
nft flush ruleset && nft -f nft_backup

42
user/security-in-qubes/firewall_4.1.rst
View file

@ -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/<vm-name>/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 <IP address of A> -d <IP address of B> -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 <IP address of A> -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,7 +237,7 @@ 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
@ -253,7 +253,7 @@ 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
@ -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
@ -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
@ -548,7 +548,7 @@ Once you have confirmed that the counters increase, store these command in ``/rw
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

44
user/security-in-qubes/mfa.rst
View file

@ -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,7 +41,7 @@ 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
@ -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 <https://github.com/QubesOS/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:

16
user/security-in-qubes/split-gpg-2.rst
View file

@ -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_DOMAIN_NAME> split-gpg2-client on
To verify if this was done correctly:
.. code:: bash
.. code:: console
dom0$ qvm-service <SPLIT_GPG2_CLIENT_DOMAIN_NAME>
Output should be:
.. code:: bash
.. code:: console
split-gpg2-client on
@ -71,7 +71,7 @@ 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
@ -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

8
user/security-in-qubes/split-gpg.rst
View file

@ -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=<vmname>`` 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,7 +232,7 @@ 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 = <YOUR_NAME>
@ -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

2
user/security-in-qubes/vm-sudo.rst
View file

@ -5,7 +5,7 @@ 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

2
user/templates/debian/debian.rst
View file

@ -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

4
user/templates/fedora/fedora-upgrade.rst
View file

@ -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<new>.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.

4
user/templates/templates.rst
View file

@ -203,14 +203,14 @@ When you install a new template or :ref:`upgrade <user/how-to-guides/how-to-upda
- If your only keyboard or mouse *are* connected through a USB qube, and that USB qube *is* a disposable, then you will have to enter a special command that shuts down all of your qubes, switches the USB qube’s disposable template to the new template, then starts the USB qube again. In order to avoid being locked out of your system, you must be very careful to enter this command without typos and with the correct substitutions.
In the App Menu, click on Terminal Emulator. Type the command below, substituting ``<SYS_USB_DISPOSABLE_TEMPLATE>`` with the name of the disposable template on which ``sys-usb`` is based, ``<NEW_TEMPLATE>`` with the name of the new template, and ``<USB_QUBE>`` 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 <SYS_USB_DISPOSABLE_TEMPLATE> template <NEW_TEMPLATE>; qvm-start <USB_QUBE>
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

26
user/templates/windows/qubes-windows-tools-4-0.rst
View file

@ -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* ``<VMname>`` *is the name of your Windows 10 VM)*
.. code:: bash
.. code:: console
qvm-features <VMname> gui 1
qvm-prefs <VMname> 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 ``<username>`` that you use to login to the Windows VM. This can be done via the following command on a ``dom0`` terminal: *(where* ``<VMname>`` *is the name of your Windows 10 VM)*
.. code:: bash
.. code:: console
qvm-prefs <VMname> default_user <username>
@ -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\<source_VM>
@ -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 <your-appvm-name>
@ -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 <vm-name> 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 <new windows appvm name> --template <name of template vm> --label <label color>

14
user/templates/windows/qubes-windows-tools-4-1.rst
View file

@ -37,7 +37,7 @@ Qubes Windows Tools (QWT) are a set of programs and drivers that provide integra
**Note:** Due to the security problems described in `QSB-091 <https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-091-2023.txt>`__, installation of Qubes Windows Tools is currently blocked. Instead, a text file containing a warning is displayed. Currently, it is difficult to estimate the severity of the risks posed by the sources of the Xen drivers used in QWT possibly being compromised, so it was decided not to offer direct QWT installation until this problem could be treated properly. While Windows qubes are, in Qubes, generally not regarded as being very trustworthy, a possible compromise of the Xen drivers used in Qubes Windows Tools might create a risk for Xen or ``dom0`` and thus be dangerous for Qubes itself. This risk may be small or even non-existent, as stated in QSB-091. If you **understand** this risk and are **willing to take it**, you can still install the previous versions of Qubes Windows Tools, using the command
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-windows-tools-4.1.68
@ -45,7 +45,7 @@ Qubes Windows Tools (QWT) are a set of programs and drivers that provide integra
for Qubes R4.1.2, or
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-windows-tools-4.1.69
@ -160,7 +160,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
1. First, make sure that ``qubes-windows-tools`` is installed in your system:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-windows-tools
@ -168,14 +168,14 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.)
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
If an earlier version of Qubes Windows Tools is already installed, with enabled current-testing repo you need to specify as action to ``upgrade`` the existing package, because the default action is ``install``, which will fail if it detects that QWT is already present in Dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing --action=upgrade qubes-windows-tools
@ -184,7 +184,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
2. **For Windows 8.1, 10 and 11:** From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which may lead to corruption of the VM’s disk.
.. code:: bash
.. code:: doscon
powercfg -H off
@ -193,7 +193,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
3. 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 <VMname> --install-windows-tools

34
user/templates/windows/windows-qubes-4-0.rst
View file

@ -122,7 +122,7 @@ Qubes 4.0 - importing a Windows VM from R3.2
Importing should work, simply make sure that you are not using Xen’s newer linux stubdomain and that the VM is in HVM mode (these steps should be done automatically when importing the VM):
.. code:: bash
.. code:: console
qvm-features VMNAME linux-stubdom ''
qvm-prefs VMNAME virt_mode hvm
@ -145,7 +145,7 @@ Summary
^^^^^^^
.. code:: bash
.. code:: console
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
qvm-prefs win7new memory 4096
@ -185,7 +185,7 @@ MS Windows versions considerations:
Create a VM named win7new in :doc:`HVM </user/advanced-topics/standalones-and-hvms>` 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 <user/advanced-topics/standalones-and-hvms:installing an os in an hvm>`:
.. 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=<VMname>

20
user/templates/windows/windows-qubes-4-1.rst
View file

@ -130,14 +130,14 @@ Create a VM named WindowsNew in :doc:`HVM </user/advanced-topics/standalones-and
.. code:: bash
.. code:: console
qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew
and for a template:
.. code:: bash
.. code:: console
qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew
@ -147,7 +147,7 @@ Create a VM named WindowsNew in :doc:`HVM </user/advanced-topics/standalones-and
.. code:: bash
.. code:: console
qvm-volume extend WindowsNew:root 60g
qvm-prefs WindowsNew memory 4096
@ -167,7 +167,7 @@ These parameters are set for the following reasons:
- The Windows’ installer requires a significant amount of memory or else the VM will crash with such errors:
.. code:: bash
.. code:: text
/var/log/xen/console/hypervisor.log:
@ -182,7 +182,7 @@ These parameters are set for the following reasons:
- After creating the new qube, 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. So set the parameter via the following CLI command from a dom0 terminal, because the Qube manager does not support this setting:
.. code:: bash
.. code:: console
qvm-prefs WindowsNew qrexec_timeout 7200
@ -213,7 +213,7 @@ These parameters are set for the following reasons:
This can also be done via the following CLI command in dom0 (assuming that the Windows installer ISO is stored in the directory ``/home/user/`` in the AppVM ``untrusted``):
.. code:: bash
.. code:: console
qvm-start --cdrom=untrusted:/home/user/windows_install.iso WindowsNew
@ -310,7 +310,7 @@ These parameters are set for the following reasons:
- From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which could lead to corruption of the VM’s disk.
.. code:: bash
.. code:: doscon
powercfg -H off
@ -340,7 +340,7 @@ These parameters are set for the following reasons:
- Given the higher than usual memory requirements of Windows, you may get a ``Not enough memory to start domain 'WindowsNew'`` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
.. code:: bash
.. code:: doscon
tailf /var/log/qubes/vm-WindowsNew.log \
/var/log/xen/console/hypervisor.log \
@ -394,7 +394,7 @@ If the user data have been moved to ``Q:``, be sure not to user the option ``Mov
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=<VMname>
@ -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

12
user/troubleshooting/app-menu-shortcut-troubleshooting.rst
View file

@ -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 <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. 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
<Menu>
<Name>Webmail</Name>
@ -178,7 +178,7 @@ First, check in the corresponding ``.desktop`` file in ``~/.local/share/qubes-ap
The line starting with ``Exec=`` points out the exact command run by dom0 to start the application. It should be something like:
.. code:: bash
.. code:: desktop
Exec=qvm-run -q -a --service -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
@ -206,7 +206,7 @@ The whitelist given to ``qvm-appmenu --set-whitelist`` is stored as a feature ca
Actual command lines for the menu shortcuts involve the ``qvm-run`` command which starts a process in another domain. Examples:
.. code:: bash
.. code:: console
qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox
qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager
@ -215,7 +215,7 @@ Actual command lines for the menu shortcuts involve the ``qvm-run`` command whic
Note that you can create a shortcut that points to a ``.desktop`` file in your app qube with e.g.:
.. code:: bash
.. code:: console
qvm-run -q -a --service -- personal qubes.StartApp+firefox

18
user/troubleshooting/debian-and-whonix-update-troubleshooting.rst
View file

@ -15,7 +15,7 @@ Updating Error Messages
After running the commands to update Debian or Whonix, hopefully everything will complete perfectly.
.. code:: bash
.. code:: console
sudo apt-get update && sudo apt-get dist-upgrade
@ -23,7 +23,7 @@ After running the commands to update Debian or Whonix, hopefully everything will
However, if you see something like the following, then something went wrong.
.. code:: bash
.. code:: text
W: Failed to fetch http://ftp.us.debian.org/debian/dist/jessie/contrib/binary-i386/Packages 404 Not Found
@ -60,7 +60,7 @@ This could be a temporary Tor exit relay or server failure that should fix itsel
Sometimes if you see a message such as:
.. code:: bash
.. code:: text
Could not resolve 'security.debian.org'
@ -68,7 +68,7 @@ Sometimes if you see a message such as:
It helps to run the following command:
.. code:: bash
.. code:: console
nslookup security.debian.org
@ -76,7 +76,7 @@ It helps to run the following command:
And then trying running the ``update`` and ``upgrade`` commands again.
.. code:: bash
.. code:: console
sudo apt-get update && sudo apt-get dist-upgrade
@ -90,7 +90,7 @@ Never Install Unsigned Packages
If you see something like this:
.. code::
.. code:: text
WARNING: The following packages cannot be authenticated!
icedove
@ -106,7 +106,7 @@ Signature Verification Warnings
There should be none at the moment. If there was such a warning, it would look like this:
.. code::
.. code:: text
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681
@ -120,7 +120,7 @@ In past various apt repositories were signed with expired key: `The Tor Project
You saw the following warning:
.. code::
.. code:: text
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681
@ -139,7 +139,7 @@ Changed Configuration Files
If you see something like the following.
.. code::
.. code:: text
Setting up ifupdown ...
Configuration file /etc/network/interfaces

16
user/troubleshooting/disk-troubleshooting.rst
View file

@ -9,7 +9,7 @@ Disk troubleshooting
If the disk is completely full, you will get an ``Out of disk space`` error that may crash your system because Dom0 does not have enough disk space to work. So it’s good practice to regularly check disk space usage. Running the ``df -h`` command in dom0 terminal will show some information, but not include all the relevant details. The Qubes user interface provides a disk space widget. If you are unable to access the interface, the command line version is running ``sudo lvs | head`` and looking at top entry for LVM pool. For example:
.. code:: bash
.. code:: text
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
pool00 qubes_dom0 twi-aotz-- 453.17g 89.95 69.78
@ -28,7 +28,7 @@ In any case you’ll need some disk space to start the VM. Check ``df -h`` outpu
1. Clean yum cache.
.. code:: bash
.. code:: console
sudo dnf clean all
@ -36,7 +36,7 @@ In any case you’ll need some disk space to start the VM. Check ``df -h`` outpu
2. Delete ``.img`` files of a less important VM, which can be found in ``/var/lib/qubes/appvms/``. Then, when the system is working again, clean up the rest.
.. code:: bash
.. code:: console
qvm-remove <VMname>
@ -45,7 +45,7 @@ In any case you’ll need some disk space to start the VM. Check ``df -h`` outpu
3. Decrease the filesystem safety margin (5% by default).
.. code:: bash
.. code:: console
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
@ -96,7 +96,7 @@ For example:
After freeing some initial space, it may be possible to recover more space by deleting files in a userVM after connecting to the userVM terminal:
.. code:: bash
.. code:: console
qvm-start <VMname>
qvm-console-dispvm <VMname>
@ -115,7 +115,7 @@ To fix this issue:
1. In the dom0 terminal get a root console on the vm (eg. sys-usb) with:
.. code:: bash
.. code:: console
qvm-console-dispvm sys-usb
@ -125,7 +125,7 @@ To fix this issue:
3. When you attempt to unmount the ``/home`` directory using the ``umount /home`` command, you will encounter an error because there are processes using the ``/home`` directory. You can view a list of these processes with the ``fuser`` command:
.. code:: bash
.. code:: console
fuser -m /home
@ -137,7 +137,7 @@ Kill these process until they are all gone using ``kill <process ID>``.
4. Finally, run:
.. code:: bash
.. code:: console
umount /home
fsck /dev/xvdb

10
user/troubleshooting/gui-troubleshooting.rst
View file

@ -13,7 +13,7 @@ When a qube starts, a fixed amount of RAM is allocated to the graphics buffer ca
To determine if this is the problem affecting you, look at the Xorg log inside the Qube at ``/home/user/.local/share/xorg/Xorg.0.log`` for lines like the following:
.. code:: bash
.. code:: text
[ 1623.988] (EE) DUMMYQBS(0): Unable to set up a virtual screen size of 3440x1440 with 17101 Kb of video memory available. Please increase the video memory size.
@ -39,7 +39,7 @@ Post installation, screen goes black and freezes following LUKS decryption
After installing Qubes, you may experience a black screen after entering your LUKS decryption password. To fix the problem, use your preferred text editor (``nano`` works) to edit ``/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg``, adding the ``efi=no-rs`` option to the end of the ``options= line``. For example:
.. code:: bash
.. code:: text
[4.14.18-1.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs
@ -54,7 +54,7 @@ Can start VM, but can't launch any applications
If you can start your VM, but can’t launch any applications, then you need to fix the issues from the ``VM console``, accessible from xen through:
.. code:: bash
.. code:: console
qvm-start <VMname> # Make sure the VM is started
qvm-console-dispvm <VMname>
@ -62,7 +62,7 @@ If you can start your VM, but can’t launch any applications, then you need to
After launching a VM console using ``qvm-console-dispvm``, you may look at the ``qubes-gui-agent`` service state with:
.. code:: bash
.. code:: console
systemctl status -l qubes-gui-agent
@ -78,7 +78,7 @@ Disable audited messages
During troubleshooting, you may be getting a lot of ‘audit’ messages which make the log very noisy. To disable audited messages, you need to edit your VM kernel parameters:
.. code:: bash
.. code:: console
previous_kernel_parameters=$(qvm-prefs --get <VMname> kernelopts) # Get current kernel parameters
qvm-prefs --set <VMname> kernelopts "<previous_kernel_parameters> audit=0"

2
user/troubleshooting/hardware-troubleshooting.rst
View file

@ -9,7 +9,7 @@ Audio doesn't work / Troubleshooting newer hardware
By default, the kernel that is installed in dom0 comes from the ``kernel`` package, which is an older Linux LTS kernel. For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues. For example, the audio might not work if the sound card is too new for the LTS kernel. To fix this, you can try the ``kernel-latest`` package – though be aware that it’s less tested! (See :ref:`here <user/advanced-topics/how-to-install-software-in-dom0:kernel upgrade>` for more information about upgrading kernels in dom0). In dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update kernel-latest

12
user/troubleshooting/hvm-troubleshooting.rst
View file

@ -9,7 +9,7 @@ HVM pauses on boot, followed by kernel error
The HVM may pause on boot, showing a fixed cursor. After a while a series of warnings may be shown similar to this:
.. code:: bash
.. code:: text
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
@ -43,7 +43,7 @@ If this solves the problem then you will want to make the change permanent:
3. Remove this text from that line:
.. code:: bash
.. code:: text
rhgb
@ -51,7 +51,7 @@ If this solves the problem then you will want to make the change permanent:
4. Add this text to that line:
.. code:: bash
.. code:: text
modprobe.blacklist=bochs_drm
@ -59,7 +59,7 @@ If this solves the problem then you will want to make the change permanent:
5. Run this command:
.. code:: bash
.. code:: console
grub2-mkconfig --output=/boot/grub2/grub.cfg
@ -75,7 +75,7 @@ Can't start an OS in an HVM / "Probing EDD (edd=off to disable!… ok" message
If you see a screen popup with SeaBios and 4 lines, last one being ``Probing EDD (edd=off to disable!... ok``, then enter the following command from a ``dom0`` prompt:
.. code:: bash
.. code:: console
qvm-prefs <HVMname> kernel ""
@ -90,7 +90,7 @@ You can disable memory-balancing in the settings, under the “Advanced” tab.
To give the VM a RAM of 2GB, open a terminal in ``dom0`` and enter:
.. code:: bash
.. code:: console
qvm-prefs <HVMname> memory 2000

8
user/troubleshooting/installation-troubleshooting.rst
View file

@ -65,14 +65,14 @@ These errors may also occur due to an incompatible Nvidia graphics card. If you
.. code:: bash
.. code:: text
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
If the above code doesn’t fix the problem, replace it with:
.. code:: bash
.. code:: text
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
@ -105,7 +105,7 @@ In Qubes 4.0, the default installation won’t function properly without IOMMU,
In Qubes 4.1, the default sys-net and sys-usb qubes need additional configuration to be usable without an IOMMU. Otherwise they will fail to start with this error message:
.. code:: bash
.. code:: text
Start failed: internal error: libxenlight failed to create new domain 'sys-net', see /var/log/libvirt/libxl/libxl-driver.log for details
@ -113,7 +113,7 @@ In Qubes 4.1, the default sys-net and sys-usb qubes need additional configuratio
To confirm that a missing IOMMU is causing this problem, check for the following error message in ``/var/log/libvirt/libxl/libxl-driver.log``:
.. code:: bash
.. code:: text
2022-03-01 13:27:17.117+0000: libxl: libxl_create.c:1146:libxl__domain_config_setdefault: passthrough not supported on this platform

12
user/troubleshooting/pci-troubleshooting.rst
View file

@ -11,7 +11,7 @@ VMs with attached PCI devices in Qubes have allocated a small buffer for DMA ope
To change this allocation, edit VM’s kernel parameters (this is expressed in 512B chunks) by running the following in a dom0 terminal:
.. code:: bash
.. code:: console
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
@ -55,7 +55,7 @@ Using the command line
1. To see all the PCI available devices, enter the ``lspci`` command into the dom0 terminal. Each device will be listed on a line, for example:
.. code:: bash
.. code:: text
0000:03:00.0 Audio device: Intel Corporation Haswell-ULT HD Audio Controller (rev 0b)
@ -64,14 +64,14 @@ Using the command line
2. Now that you can see all the PCI devices and their BDFs, you can decide which to remove and which to keep. Imagine we faced the following error message:
.. code:: bash
.. code:: text
libvirt.libvirtError: internal error: Unable to reset PCI device 0000:03:00.1: internal error: Active 0000:03:00.0 devices on bus with 0000:03:00.1, not doing bus reset
In the above case, the device ``0000:03:00.1`` is the device which we want to use. But we are facing the ``Unable to reset PCI device`` error because another device, ``0000:03:00.0``, is active. To fix this error and get device ``0000:03:00.1`` to work, we must first remove the offending device ``0000:03:00.0``.
.. code:: bash
.. code:: console
sudo su
echo -n "1" > /sys/bus/pci/devices/0000:03:00.0/remove
@ -80,7 +80,7 @@ Using the command line
3. In order to make this change persistent, create a file ``/etc/systemd/system/qubes-pre-netvm.service`` and add the following:
.. code:: bash
.. code:: systemd
[Unit]
Description=Netvm fixup
@ -107,7 +107,7 @@ This is a :ref:`PCI passthrough issue <user/troubleshooting/pci-troubleshooting:
NOTE: The ``permissive`` flag increases attack surface and possibility of `side channel attacks <https://en.wikipedia.org/wiki/Side-channel_attack>`__. While using the ``no-strict-reset`` flag, do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent. Both ``permissive`` and ``no-strict-reset`` options may not be necessary and you should try one first, then the other, before using both.
.. code:: bash
.. code:: console
qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>

2
user/troubleshooting/resume-suspend-troubleshooting.rst
View file

@ -39,7 +39,7 @@ Checking logs for relevant messages
View the output of ``dmesg`` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not):
.. code:: bash
.. code:: text
iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm
iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208

10
user/troubleshooting/uefi-troubleshooting.rst
View file

@ -15,7 +15,7 @@ Successfully installed in legacy mode, but had to change some xen parameters
2. Open a terminal and enter the command ``sudo su -``. Use your preferred text editor (e.g ``vi``) to edit your xen config (``EFI/BOOT/grub.cfg``):
.. code:: bash
.. code:: console
vi EFI/BOOT/grub.cfg
@ -63,7 +63,7 @@ Some Dell systems and probably others have `another bug in UEFI firmware <https:
3. Execute:
.. code:: bash
.. code:: console
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
@ -85,7 +85,7 @@ Or if you have already rebooted after the first stage install and have encounter
4. Execute:
.. code:: bash
.. code:: console
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
@ -111,7 +111,7 @@ Some firmware will not recognize the default Qubes EFI configuration. As such, i
4. Copy ``grubx64.efi`` to the fallback path:
.. code:: bash
.. code:: console
cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi
@ -131,7 +131,7 @@ Some firmware will not recognize the default Qubes EFI configuration. As such, i
3. Create boot entry in EFI firmware (replace ``/dev/sda`` with your disk name and ``-p 1`` with ``/boot/efi`` partition number):
.. code:: bash
.. code:: console
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1

10
user/troubleshooting/usb-troubleshooting.rst
View file

@ -41,7 +41,7 @@ A device that does not support reset is not ideal and generally should not be as
Most likely the offending controller is a USB 3.0 device. You can remove this controller from the USB VM, and see if this allows the VM to boot. Alternatively you may be able to disable USB 3.0 in the BIOS. If the BIOS does not have the option to disable USB 3.0, try running the following command in dom0 to force USB 2.0 modes for the USB ports:
.. code:: bash
.. code:: console
lspci -nn | grep USB | cut -d '[' -f3 | cut -d ']' -f1 | xargs -I@ setpci -H1 -d @ d0.l=0
@ -51,7 +51,7 @@ Errors suggesting this issue:
- in ``xl dmesg`` output:
.. code::
.. code:: text
(XEN) [VT-D] It's disallowed to assign 0000:00:1a.0 with shared RMRR at dbe9a000 for Dom19.
(XEN) XEN_DOMCTL_assign_device: assign 0000:00:1a.0 to dom19 failed (-1)
@ -60,7 +60,7 @@ Errors suggesting this issue:
- during ``qvm-start sys-usb``:
.. code::
.. code:: text
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
@ -72,7 +72,7 @@ Another solution would be to set the pci_strictreset option in dom0:
- In Qubes R4.x, when attaching the PCI device to the VM (where ``<BDF>`` can be obtained from running ``qvm-pci``):
.. code:: bash
.. code:: console
qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0:<BDF>
@ -80,7 +80,7 @@ Another solution would be to set the pci_strictreset option in dom0:
- In Qubes R3.x, by modifying the VM’s properties:
.. code:: bash
.. code:: console
qvm-prefs usbVM -s pci_strictreset false

2
user/troubleshooting/vm-troubleshooting.rst
View file

@ -73,7 +73,7 @@ Some packages will throw an error on installation in this situation. For example
One solution is to add a dummy interface to allow the package to install correctly:
.. code:: bash
.. code:: console
ip link add d0 type dummy
ip addr add 192.168.0.1/24 dev d0

6
user/troubleshooting/vpn-troubleshooting.rst
View file

@ -9,7 +9,7 @@ Tips
- If using qubes-vpn, check the VPN service’s log in the VPN VM by running:
.. code:: bash
.. code:: console
sudo journalctl -u qubes-vpn-handler
@ -45,7 +45,7 @@ To figure out the root of the problem, check the VPN logs in ``/var/log/syslog``
`Some VPN guides <https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061>`__ use complex scripts that include a call to ``notify-send``, yet some images may not contain this tool or may not have it working properly. For instance calling ``notify-send`` on a ``fedora-36`` template VM gives:
.. code:: bash
.. code:: text
Failed to execute child process “dbus-launch” (No such file or directory)
@ -53,7 +53,7 @@ To figure out the root of the problem, check the VPN logs in ``/var/log/syslog``
To check this tool is working properly run:
.. code:: bash
.. code:: console
sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle