Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-12-02 17:37:30 -05:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'rst' into toki_fix_findings

Browse source
This commit is contained in:
Tobias Killer 2025-08-16 20:05:30 +02:00 • committed by GitHub
commit cad541c3af
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
115 changed files with 1960 additions and 1862 deletions
Download patch file Download diff file Expand all files Collapse all files

4
user/advanced-topics/awesomewm.rst
View file

@ -24,7 +24,7 @@ Installation
AwesomeWM can be installed with the standard dom0 installation mechanisms.
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update awesome
@ -37,7 +37,7 @@ Development
To :doc:`contribute code </introduction/contributing>` you may clone the AwesomeWM repository as follows:
.. code:: bash
.. code:: console
$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome

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

@ -28,17 +28,17 @@ 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
$ sudo mkdir -p /rw/config/qubes-bind-dirs.d
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
$ sudo touch /rw/config/qubes-bind-dirs.d/50_user.conf
@ -54,9 +54,9 @@ 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
$ sudo mkdir -p /rw/bind-dirs/var/lib/tor
@ -155,26 +155,26 @@ 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
$ qvm-service -e my-app-vm custom-persist
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
$ qvm-features my-app-vm custom-persist.my_persistent_dir /var/my_persistent_dir
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
$ qvm-features my-app-vm custom-persist.home /home
$ qvm-features my-app-vm custom-persist.usrlocal /usr/local
@ -182,10 +182,10 @@ 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
$ 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

14
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
@ -52,12 +52,12 @@ These files are placed in ``/rw``, which survives a VM restart. That way, they c
.. code:: bash
#!/bin/bash
command="$1"
vif="$2"
vif_type="$3"
ip="$4"
if [ "$ip" == '10.137.0.100' ]; then
case "$command" in
online)
@ -84,11 +84,11 @@ GUI and audio configuration in dom0
The GUI configuration file ``/etc/qubes/guid.conf`` in one of a few not managed by ``qubes-prefs`` or the Qubes Manager tool. Sample config (included in default installation):
.. code:: bash
.. code::
# Sample configuration file for Qubes GUI daemon
# For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html
global: {
# default values
#allow_fullscreen = false;
@ -102,9 +102,9 @@ The GUI configuration file ``/etc/qubes/guid.conf`` in one of a few not managed
#trayicon_mode = "border1";
#startup_timeout = 45;
};
# most of setting can be set per-VM basis
VM: {
work: {
allow_utf8_titles = true;

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

@ -12,14 +12,14 @@ Introduction
A :doc:`disposable </user/how-to-guides/how-to-use-disposables>` can be based on any :ref:`app qube <user/reference/glossary:app qube>`. You can also choose to use different :ref:`disposable templates <user/reference/glossary:disposable template>` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the ``appmenus-dispvm`` feature:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
@ -38,7 +38,7 @@ Creating a new disposable template
In Qubes 4.0, you’re no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like. To create a new disposable template:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-create --template <TEMPLATE> --label red <DISPOSABLE_TEMPLATE>
[user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
@ -47,7 +47,7 @@ In Qubes 4.0, you’re no longer restricted to a single disposable template. Ins
Optionally, set it as the default disposable template:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qubes-prefs default_dispvm <DISPOSABLE_TEMPLATE>
@ -66,7 +66,7 @@ It is possible to change the settings for each new disposable. This can be done
1. Start a terminal in the ``<DISPOSABLE_TEMPLATE>`` qube (or another disposable template) by running the following command in a dom0 terminal. (If you enable ``appmenus-dispvm`` feature (as explained at the top), applications menu for this VM (``<DISPOSABLE_TEMPLATE>``) will be “Disposable: ” (instead of “Domain: ”) and entries there will start new disposable based on that VM (``<DISPOSABLE_TEMPLATE>``). Not in that VM (``<DISPOSABLE_TEMPLATE>``) itself).
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-run -a <DISPOSABLE_TEMPLATE> gnome-terminal
@ -93,13 +93,13 @@ 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
qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
qvm-prefs <SERVICE_QUBE> provides_network true
qvm-features <SERVICE_QUBE> appmenus-dispvm ''
$ qvm-create -C DispVM -l green <SERVICE_QUBE>
$ qvm-prefs <SERVICE_QUBE> autostart true
$ qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
$ qvm-prefs <SERVICE_QUBE> provides_network true
$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
@ -109,31 +109,31 @@ 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
qvm-service <SERVICE_QUBE> meminfo-writer off
qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
qvm-prefs <SERVICE_QUBE> autostart true
qvm-prefs <SERVICE_QUBE> netvm ''
qvm-features <SERVICE_QUBE> appmenus-dispvm ''
$ qvm-create -C DispVM -l red <SERVICE_QUBE>
$ qvm-prefs <SERVICE_QUBE> virt_mode hvm
$ qvm-service <SERVICE_QUBE> meminfo-writer off
$ qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
$ qvm-prefs <SERVICE_QUBE> autostart true
$ qvm-prefs <SERVICE_QUBE> netvm ''
$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
Optionally, if this disposable will also provide network access to other qubes:
.. code:: bash
.. code:: console
qvm-prefs <SERVICE_QUBE> provides_network true
$ qvm-prefs <SERVICE_QUBE> provides_network true
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>
$ qvm-prefs sys-firewall netvm <SERVICE_QUBE>
@ -141,19 +141,19 @@ 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
qvm-service sys-net2 meminfo-writer off
qvm-pci attach --persistent sys-net2 dom0:00_1a.0
qvm-prefs sys-net2 autostart true
qvm-prefs sys-net2 netvm ''
qvm-features sys-net2 appmenus-dispvm ''
qvm-prefs sys-net2 provides_network true
qvm-prefs sys-net autostart false
qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
$ qvm-create -C DispVM -l red sys-net2
$ qvm-prefs sys-net2 virt_mode hvm
$ qvm-service sys-net2 meminfo-writer off
$ qvm-pci attach --persistent sys-net2 dom0:00_1a.0
$ qvm-prefs sys-net2 autostart true
$ qvm-prefs sys-net2 netvm ''
$ qvm-features sys-net2 appmenus-dispvm ''
$ qvm-prefs sys-net2 provides_network true
$ qvm-prefs sys-net autostart false
$ qvm-prefs sys-firewall netvm sys-net2
$ qubes-prefs clockvm sys-net2
@ -173,7 +173,7 @@ Deleting disposables
While working in a disposable, you may want to open a document in another disposable. For this reason, the property ``default_dispvm`` may be set to the name of your disposable in a number of qubes:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-prefs <QUBE> | grep default_dispvm
default_dispvm - <DISPOSABLE_TEMPLATE>
@ -181,14 +181,14 @@ While working in a disposable, you may want to open a document in another dispos
This will prevent the deletion of the disposable template. In order to fix this, you need to unset the ``default_dispvm`` property:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-prefs <QUBE> default_dispvm ""
You can then delete the disposable template:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-remove <DISPOSABLE_TEMPLATE>
This will completely remove the selected VM(s)
@ -197,7 +197,7 @@ You can then delete the disposable template:
If you still encounter a problem, you may have forgotten to clean an entry. Looking at the system logs will help you:
.. code:: bash
.. code:: console
[user@dom0 ~]$ journalctl | tail

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

@ -14,19 +14,19 @@ 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
$ qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
$ qvm-features dom0 gui-videoram-overhead 0
Where ``$WIDTH`` × ``$HEIGHT`` is the maximum desktop size that you anticipate needing. For example, if you expect to use a 1080p display and a 4k display side-by-side, that is ``(1920 + 3840) × 2160 × 4 / 1024 = 48600``, or slightly more than 48 MiB per qube. After making these adjustments, the qubes need to be restarted.
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}')
$ qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e 's/.*current //' -e 's/\,.*//' | awk '{print $1*$3*4/1024}')
The amount of memory allocated per qube is the maximum of:
@ -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"

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

@ -20,24 +20,24 @@ 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
$ sudo qubesctl top.enable qvm.sys-gui
$ sudo qubesctl top.enable qvm.sys-gui pillar=True
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
$ sudo qubesctl --all state.highstate
You can now disable the ``sys-gui`` formula:
.. code:: bash
.. code:: console
sudo qubesctl top.disable qvm.sys-gui
$ sudo qubesctl top.disable qvm.sys-gui
At this point, you need to shutdown all your running qubes as the ``default_guivm`` qubes global property has been set to ``sys-gui``. In order to use ``sys-gui`` as GUI domain, you need to logout and, in the top right corner, select ``lightdm`` session type to **GUI domain (sys-gui)**. Once logged, you are running ``sys-gui`` as fullscreen window and you can perform any operation as if you would be in ``dom0`` desktop.
@ -56,31 +56,31 @@ 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
$ sudo qubesctl top.enable qvm.sys-gui-gpu
$ sudo qubesctl top.enable qvm.sys-gui-gpu pillar=True
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
$ 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
$ 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
$ sudo qubesctl state.sls qvm.sys-gui-gpu-attach-gpu
The latter option assumes Intel graphics card (it has hardcoded PCI address). If you don’t have Intel graphics card, please use the former method with ``qvm-pci`` (see :doc:`How to use PCI devices </user/how-to-guides/how-to-use-pci-devices>`).
@ -103,31 +103,31 @@ 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
$ sudo qubesctl top.enable qvm.sys-gui-vnc
$ sudo qubesctl top.enable qvm.sys-gui-vnc pillar=True
then, execute it:
.. code:: bash
.. code:: console
sudo qubesctl --all state.highstate
$ 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
$ 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
$ qvm-start sys-gui-vnc
A VNC server session is running on ``localhost:5900`` in ``sys-gui-vnc``. In order to reach the ``VNC`` server, we encourage to not connect ``sys-gui-vnc`` to a ``NetVM`` but rather to use another qube for remote access, say ``sys-remote``. First, you need to bind port 5900 of ``sys-gui-vnc`` into a ``sys-remote`` local port (you may want to use another port than 5900 to reach ``sys-remote`` from the outside). For that, use ``qubes.ConnectTCP`` RPC service (see :doc:`Firewall </user/security-in-qubes/firewall>`. Then, you can use any ``VNC`` client to connect to you ``sys-remote`` on the chosen local port (5900 if you kept the default one). For the first connection, you will reach ``lightdm`` for which you can log as ``user`` where ``user`` refers to the first ``dom0`` user in ``qubes`` group and with corresponding ``dom0`` password.
@ -186,30 +186,30 @@ 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
$ 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
$ qvm-remove -f sys-gui-gpu
.. |sys-gui| image:: /attachment/posts/guivm-hybrid.png
.. |sys-gui-gpu| image:: /attachment/posts/guivm-gpu.png
.. |sys-gui-vnc| image:: /attachment/posts/guivm-vnc.png

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

@ -30,7 +30,7 @@ How to install a specific package
To install additional packages in dom0 (usually not recommended):
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update anti-evil-maid
@ -46,9 +46,9 @@ 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
$ sudo qubes-dom0-update --action=downgrade package-version
@ -58,9 +58,9 @@ How to re-install a package
To re-install a package in dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --action=reinstall package
$ sudo qubes-dom0-update --action=reinstall package
@ -70,9 +70,9 @@ 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
$ sudo dnf remove anti-evil-maid
@ -94,11 +94,11 @@ 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
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable
@ -152,9 +152,9 @@ 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
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm
@ -166,9 +166,9 @@ 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
$ 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,9 +176,9 @@ Grub2
^^^^^
.. code:: bash
.. code:: console
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
@ -192,14 +192,25 @@ 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:: console
$ sudo nano /etc/default/grub
Update the following two lines, add if needed:
.. code:: bash
sudo nano /etc/default/grub
[update the following two lines, add if needed]
GRUB_DISABLE_SUBMENU=false
GRUB_SAVEDEFAULT=true
[save and exit nano]
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
Save and exit nano. Regenerate the GRUB 2 configuration.
.. code:: console
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
@ -213,8 +224,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
:menuselection:`Qubes VM Manager --> System --> Global Settings --> UpdateVM --> sys-whonix`

14
user/advanced-topics/i3.rst
View file

@ -8,7 +8,7 @@ i3 (window manager)
i3 is part of the stable repository (as of Qubes R3.1) and can be installed by using the :doc:`dom0 update mechanism </user/advanced-topics/how-to-install-software-in-dom0>`. To install the i3 window manager and the its Qubes specific configuration:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update i3 i3-settings-qubes
@ -47,7 +47,7 @@ Getting the code
Clone the i3-qubes repository here:
.. code:: bash
.. code:: console
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
@ -62,14 +62,14 @@ Building
You’ll need to install the build dependencies, which are listed in build-deps.list. You can verify them and then install them with:
.. code:: bash
.. code:: console
$ sudo dnf install -y $(cat build-deps.list)
This used to be more complicated, but I finally redid this and use the same buildsystem that’s used by Qubes OS for XFCE. It’s just a Makefile that helps you get the sources and start off the build:
.. code:: bash
.. code:: console
$ make get-sources
$ make verify-sources
@ -86,14 +86,14 @@ You should now have your i3 rpm in ``./rpm/x86_64/i3-4.8-3.fc20.x86_64.rpm``. Pr
Now in dom0, copy in the rpm:
.. code:: bash
.. code:: console
$ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm
Now that the rpm is in dom0 we can proceed with installing it. i3 has some dependencies that we can easily install with:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
@ -102,7 +102,7 @@ Now that the rpm is in dom0 we can proceed with installing it. i3 has some depen
After that you can just install the generated rpm like any other local package:
.. code:: bash
.. code:: console
$ sudo yum localinstall i3.rpm

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

@ -20,32 +20,32 @@ In dom0, use ``qubes-dom0-update``:
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-repo-contrib
$ sudo qubes-dom0-update qubes-repo-contrib
In a Fedora-based template, use ``dnf``:
.. code:: bash
.. code:: console
sudo dnf install qubes-repo-contrib
$ sudo dnf install qubes-repo-contrib
In a Debian-based template, use ``apt``:
.. code:: bash
.. code:: console
sudo apt update && sudo apt install qubes-repo-contrib
$ 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,9 +63,9 @@ For example, to install ``qvm-screenshot-tool`` in dom0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --clean qvm-screenshot-tool
$ sudo qubes-dom0-update --clean qvm-screenshot-tool
Please see the package’s README for specific installation and setup instructions.

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

@ -12,7 +12,7 @@ Installation
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with R3.2, however, :doc:`XFCE is the new default desktop environment </developer/releases/3_2/release-notes>`. Nonetheless, it is still possible to install KDE by issuing this command in dom0:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update kde-settings-qubes
@ -26,7 +26,7 @@ KDE is very customisable, and there is a range of widgets to use. If you want to
.. code:: bash
#!/usr/bin/sh
# Use Qubes provided menu instead of default XFCE one
if [ "$XDG_SESSION_DESKTOP" = "KDE" ]; then
XDG_MENU_PREFIX="kf5-"
@ -47,7 +47,7 @@ You can also change your default login manager (lightdm) to the new KDE default:
- first you need to edit the ``/etc/sddm.conf`` to make sure if the custom X parameter is set according to Qubes needs:
.. code:: bash
.. code:: kconfig
[XDisplay]
ServerArguments=-nolisten tcp -background none
@ -56,7 +56,7 @@ You can also change your default login manager (lightdm) to the new KDE default:
- disable the lightdm service:
.. code:: bash
.. code:: console
$ sudo systemctl disable lightdm
@ -64,7 +64,7 @@ You can also change your default login manager (lightdm) to the new KDE default:
- enable the sddm service:
.. code:: bash
.. code:: console
$ sudo systemctl enable sddm
@ -85,11 +85,11 @@ You can set each window’s position and size like this:
.. code:: text
Right click title bar --> More actions --> Special window settings...
Window matching tab
Window class (application): Exact Match: <vm_name>
Window title: Substring Match: <partial or full program name>
Size & Position tab
[x] Position: Apply Initially: x,y
[x] Size: Apply Initially: x,y
@ -97,7 +97,7 @@ You can set each window’s position and size like this:
You can also use ``kstart`` to control virtual desktop placement like this:
.. code:: bash
.. code:: console
kstart --desktop 3 --windowclass <vm_name> -q --tray -a <vm_name> '<run_program_command>'
@ -115,8 +115,8 @@ 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
$ sudo dnf remove kdelibs plasma-workspace

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

@ -22,7 +22,7 @@ By default, VMs kernels are provided by dom0. (See :ref:`here <user/advanced-top
To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the ``qvm-prefs`` tool:
.. code:: text
.. code:: console
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel
Missing kernel version argument!
@ -40,7 +40,7 @@ To select which kernel a given VM will use, you can either use Qubes Manager (VM
To check/change the default kernel you can either go to “Global settings” in Qubes Manager, or use the ``qubes-prefs`` tool:
.. code:: text
.. code:: console
[user@dom0 ~]$ qubes-prefs
clockvm : sys-net
@ -54,7 +54,7 @@ To check/change the default kernel you can either go to “Global settings” in
To view kernel options, you can use the GUI VM Settings tool; to view and change them, use ``qvm-prefs`` commandline tool:
.. code:: text
.. code:: console
[user@dom0 ~]$ qvm-prefs -g work kernelopts
nopat
@ -67,7 +67,7 @@ Installing different kernel using Qubes kernel package
VM kernels are packaged by the Qubes team in the ``kernel-qubes-vm`` packages. Generally, the system will keep the three newest available versions. You can list them with the ``rpm`` command:
.. code:: text
.. code:: console
[user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*'
kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64
@ -79,7 +79,7 @@ If you want a more recent version, you can check the ``qubes-dom0-unstable`` rep
To check available versions in the ``qubes-dom0-unstable`` repository:
.. code:: text
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
@ -100,7 +100,7 @@ To check available versions in the ``qubes-dom0-unstable`` repository:
Installing a new version from ``qubes-dom0-unstable`` repository:
.. code:: text
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
@ -108,7 +108,7 @@ Installing a new version from ``qubes-dom0-unstable`` repository:
Loaded plugins: langpacks, post-transaction-actions, yum-qubes-hooks
Resolving Dependencies
(...)
===========================================================================================
Package Arch Version Repository Size
===========================================================================================
@ -116,12 +116,12 @@ Installing a new version from ``qubes-dom0-unstable`` repository:
kernel-qubes-vm x86_64 1000:4.1.12-6.pvops.qubes qubes-dom0-cached 40 M
Removing:
kernel-qubes-vm x86_64 1000:3.18.10-2.pvops.qubes @anaconda/R3.0 134 M
Transaction Summary
===========================================================================================
Install 1 Package
Remove 1 Package
Total download size: 40 M
Is this ok [y/d/N]: y
Downloading packages:
@ -136,13 +136,13 @@ Installing a new version from ``qubes-dom0-unstable`` repository:
Error in PREUN scriptlet in rpm package 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64
Verifying : 1000:kernel-qubes-vm-4.1.12-6.pvops.qubes.x86_64 1/2
Verifying : 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64 2/2
Installed:
kernel-qubes-vm.x86_64 1000:4.1.12-6.pvops.qubes
Failed:
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes
Complete!
[user@dom0 ~]$
@ -165,7 +165,7 @@ It is possible to package a kernel installed in dom0 as a VM kernel. This makes
To prepare such a VM kernel, you need to install the ``qubes-kernel-vm-support`` package in dom0 and also have matching kernel headers installed (``kernel-devel`` package in the case of a Fedora kernel package). You can install requirements using ``qubes-dom0-update``:
.. code:: text
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
@ -174,17 +174,17 @@ To prepare such a VM kernel, you need to install the ``qubes-kernel-vm-support``
Package 1000:kernel-devel-4.1.9-6.pvops.qubes.x86_64 already installed and latest version
Resolving Dependencies
(...)
================================================================================
Package Arch Version Repository Size
================================================================================
Installing:
qubes-kernel-vm-support x86_64 3.1.2-1.fc20 qubes-dom0-cached 9.2 k
Transaction Summary
================================================================================
Install 1 Package
Total download size: 9.2 k
Installed size: 13 k
Is this ok [y/d/N]: y
@ -194,22 +194,22 @@ To prepare such a VM kernel, you need to install the ``qubes-kernel-vm-support``
Transaction test succeeded
Running transaction (shutdown inhibited)
Installing : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1
Creating symlink /var/lib/dkms/u2mfn/3.1.2/source ->
/usr/src/u2mfn-3.1.2
DKMS: add completed.
Verifying : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1
Installed:
qubes-kernel-vm-support.x86_64 0:3.1.2-1.fc20
Complete!
Then you can call the ``qubes-prepare-vm-kernel`` tool to actually package the kernel. The first parameter is kernel version (exactly as seen by the kernel), the second one (optional) is short name. This is visible in Qubes Manager and the ``qvm-prefs`` tool.
.. code:: text
.. code:: console
[user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes
--> Building files for 4.1.9-6.pvops.qubes.x86_64 in /var/lib/qubes/vm-kernels/4.1.qubes
@ -246,8 +246,8 @@ Both debian-9 and fedora-26 templates already have grub and related tools preins
.. code:: console
qvm-prefs <clonetemplatename> virt_mode hvm
qvm-prefs <clonetemplatename> kernel ''
$ qvm-prefs <clonetemplatename> virt_mode hvm
$ qvm-prefs <clonetemplatename> kernel ''
@ -263,7 +263,7 @@ If you are using a distribution kernel package (``kernel`` package), the initram
.. code:: console
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
$ sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
@ -271,7 +271,7 @@ Once the kernel is installed, you need to setup ``grub2`` by running:
.. code:: console
sudo grub2-install /dev/xvda
$ sudo grub2-install /dev/xvda
@ -279,13 +279,13 @@ Finally, you need to create a GRUB configuration. You may want to adjust some se
.. code:: console
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
You can safely ignore this error message:
.. code:: output
.. code:: console
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
@ -321,7 +321,7 @@ Install distribution kernel image, kernel headers and the grub.
.. code:: console
sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support
$ sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support
@ -329,7 +329,7 @@ If you are doing that on a qube based on “Debian Minimal” template, a grub g
.. code:: console
sudo grub-install /dev/xvda
$ sudo grub-install /dev/xvda
@ -383,7 +383,7 @@ Run DKMS. Replace this with actual kernel version.
.. code:: console
sudo dkms autoinstall -k <kernel-version>
$ sudo dkms autoinstall -k <kernel-version>
For example.
@ -392,7 +392,7 @@ For example.
.. code:: console
sudo dkms autoinstall -k 4.19.0-6-amd64
$ sudo dkms autoinstall -k 4.19.0-6-amd64
Update initramfs.
@ -401,24 +401,24 @@ Update initramfs.
.. code:: console
sudo update-initramfs -u
$ sudo update-initramfs -u
The output should look like this:
.. code:: text
.. code:: console
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64

8
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:: output
sda 8:0 0 111.8G 0 disk
├─sda1 8:1 0 200M 0 part /boot/efi
@ -90,8 +90,8 @@ Mounting the disk
.. list-table::
:widths: 28 28 28
.. list-table::
:widths: 28 28 28
:align: center
:header-rows: 1
@ -110,7 +110,7 @@ Mounting the disk
* - other_install/pool00_tmeta
- LVM Metadata
- The metadata LV of this disk.
6. Mount the disk using the command ``mount /dev/other_install/<lv name> <mountpoint>``. *Note:* Any compromised data which exists in the volume to be mounted will be accessible here. Do not mount untrusted partitions in dom0.

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>

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

@ -40,17 +40,17 @@ 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>
$ qvm-volume extend <vm_name>:root <size>
OR
.. code:: bash
.. code:: console
qvm-volume extend <vm_name>:private <size>
$ 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,10 +115,10 @@ 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
$ qvm-shutdown qube1
$ sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private

2
user/advanced-topics/rpc-policy.rst
View file

@ -12,7 +12,7 @@ This document explains the basics of RPC policies in Qubes. For more information
Here’s an example of an RPC policy file in dom0:
.. code:: bash
.. code:: console
[user@dom0 user ~]$ cat /etc/qubes-rpc/policy/qubes.FileCopy
(...)

56
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).*)$:
@ -139,7 +139,7 @@ Enabling Top Files and Applying the States
Now, because we use custom extensions to manage top files (instead of just enabling them all), to enable a particular top file you should issue command:
.. code:: bash
.. code:: console
$ qubesctl top.enable my-new-vm
@ -147,7 +147,7 @@ Now, because we use custom extensions to manage top files (instead of just enabl
To list all enabled top files:
.. code:: bash
.. code:: console
$ qubesctl top.enabled
@ -155,7 +155,7 @@ To list all enabled top files:
And to disable one:
.. code:: bash
.. code:: console
$ qubesctl top.disable my-new-vm
@ -163,7 +163,7 @@ And to disable one:
To apply the states to dom0 and all VMs:
.. code:: bash
.. code:: console
$ qubesctl --all state.apply
@ -193,15 +193,15 @@ Configuring a qube's System from Dom0
Salt can be used to configure qubes from dom0. Simply set the qube name as the target minion name in the top file. You can also use the ``qubes`` pillar module to select qubes with a particular property (see below). If you do so, then you need to pass additional arguments to the ``qubesctl`` tool:
.. code:: bash
.. code:: output
usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0]
[--targets TARGETS | --templates | --app | --all]
...
positional arguments:
command Salt command to execute (e.g., state.apply)
optional arguments:
-h, --help show this help message and exit
--show-output Show output of management commands
@ -233,7 +233,7 @@ Writing Your Own Configurations
Let’s start with a quick example:
.. code:: bash
.. code:: yaml
my new and shiny VM:
qvm.present:
@ -267,7 +267,7 @@ As you will notice, the options are the same (or very similar) to those used in
This should be put in ``/srv/salt/my-new-vm.sls`` or another ``.sls`` file. A separate ``*.top`` file should be also written:
.. code:: bash
.. code:: yaml
base:
dom0:
@ -279,7 +279,7 @@ This should be put in ``/srv/salt/my-new-vm.sls`` or another ``.sls`` file. A se
To enable the particular top file you should issue the command:
.. code:: bash
.. code:: console
$ qubesctl top.enable my-new-vm
@ -287,7 +287,7 @@ To enable the particular top file you should issue the command:
To apply the state:
.. code:: bash
.. code:: console
$ qubesctl state.apply
@ -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:
@ -319,7 +319,7 @@ Then the appropriate top file (``/srv/salt/mc-everywhere.top``):
Now you need to enable the top file:
.. code:: bash
.. code:: console
$ qubesctl top.enable mc-everywhere
@ -327,7 +327,7 @@ Now you need to enable the top file:
And apply the configuration:
.. code:: bash
.. code:: console
$ qubesctl --all state.apply
@ -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:: text
.. code:: yaml
my preferences:
qvm.prefs:
@ -364,7 +364,7 @@ You can set properties of an existing qube:
^^^^^^^^^^^^^^^
.. code:: text
.. 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:: text
.. 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:: text
/srv/pillar/base/qvm/init.sls
@ -540,7 +540,7 @@ Whonix Workstation template
Updates dom0. Example (executed in dom0):
.. code:: bash
.. code:: console
$ sudo qubesctl --show-output state.sls update.qubes-dom0
@ -552,7 +552,7 @@ Updates dom0. Example (executed in dom0):
Updates domUs. Example to update all templates (executed in dom0):
.. code:: bash
.. code:: console
$ sudo qubesctl --show-output --skip-dom0 --templates state.sls update.qubes-vm
@ -644,7 +644,7 @@ If the log does not contain useful information:
.. code:: bash
.. code:: console
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command
@ -668,7 +668,7 @@ Using fedora-24-minimal
The fedora-24-minimal package is missing the ``sudo`` package. You can install it via:
.. code:: bash
.. code:: console
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
@ -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:

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

@ -22,7 +22,7 @@ You can query qvm-pool to list available storage drivers:
.. code:: console
qvm-pool --help-drivers
$ qvm-pool --help-drivers
qvm-pool driver explanation:
@ -48,20 +48,17 @@ 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
$ sudo pvs
$ sudo lvs
Take note of the VG and thin pool names for your second drive., then register it with Qubes:
Take note of the VG and thin pool names for your second drive, then register it with Qubes, where ``<pool_name>`` is a freely chosen pool name, ``<vg_name>`` is LVM volume group name and ``<thin_pool_name>`` is LVM thin pool name:
.. code:: bash
.. code:: console
# <pool_name> is a freely chosen pool name
# <vg_name> is LVM volume group name
# <thin_pool_name> is LVM thin pool name
qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
$ qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
@ -73,19 +70,17 @@ 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
To register the storage to qubes:
To register the storage to qubes use the following command where ``<pool_name>`` is a freely chosen pool name adn ``<dir_path>`` is the mounted path to the second btrfs storage:
.. code:: bash
.. code:: console
# <pool_name> is a freely chosen pool name
# <dir_path> is the mounted path to the second btrfs storage
qvm-pool --add <pool_name> file-reflink -o dir_path=<dir_path>,revisions_to_keep=2
$ qvm-pool --add <pool_name> file-reflink -o dir_path=<dir_path>,revisions_to_keep=2
Using the new pool
@ -94,24 +89,24 @@ Using the new pool
Now, you can create qubes in that pool:
.. code:: bash
.. code:: console
qvm-create -P <pool_name> --label red <vmname>
$ 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>
$ qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
$ qvm-remove <sourceVMname>
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>
$ qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
Example setup of second drive.
@ -120,10 +115,10 @@ 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
$ sudo cryptsetup luksFormat --sector-size=512 /dev/sdb
$ sudo blkid /dev/sdb
@ -131,7 +126,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,30 +139,30 @@ For LVM
First create the physical volume:
.. code:: bash
.. code:: console
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
$ 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
$ 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
$ 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
$ qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
For Btrfs
@ -176,57 +171,55 @@ 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
$ sudo mkfs.btrfs -L <label> /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
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
$ sudo mkdir -p /mnt/new_qube_storage
$ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /mnt/new_qube_storage
Create a subvolume to hold the data:
.. code:: bash
.. code:: console
sudo btrfs subvolume create /mnt/new_qube_storage/qubes
$ sudo btrfs subvolume create /mnt/new_qube_storage/qubes
Unmount the temporary Btrfs filesystem:
.. code:: bash
.. code:: console
sudo umount /mnt/new_qube_storage
rmdir /mnt/new_qube_storage
$ sudo umount /mnt/new_qube_storage
$ rmdir /mnt/new_qube_storage
Mount the subvolume with compression enabled if desired:
Mount the subvolume with compression enabled if desired, where ``<compression>`` can take the values ``zlib|lzo|zstd``. ``<subvol>`` is a btrfs subvolume "qubes" in this example.
.. code:: bash
.. code:: console
# <compression> zlib|lzo|zstd
# <subvol> btrfs subvolume "qubes" in this example
sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes
$ sudo mount /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde /var/lib/qubes_newpool -o compress=<compression>,subvol=qubes
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
$ 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
$ qvm-create -P poolhd0_qubes --label red unstrusted-hdd
Verify that corresponding lines were added to /etc/fstab and /etc/cryptab to enable auto mounting of the new pool.

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

@ -44,17 +44,17 @@ 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>
$ qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm <NEW_STANDALONE_NAME>
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>
$ qvm-create --class StandaloneVM --label <YOUR_COLOR> --property virt_mode=hvm --template <TEMPLATE_QUBE_NAME> <NEW_STANDALONE_NAME>
@ -88,15 +88,15 @@ 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
$ qvm-create my-new-vm --class StandaloneVM --property virt_mode=hvm --property kernel='' --label=green
If you receive an error like this one, then you must first enable VT-x in your BIOS:
.. code:: bash
.. code:: output
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
@ -112,25 +112,25 @@ 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
$ qvm-start <YOUR_HVM> --cdrom=/dev/cdrom
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>
$ qvm-start <YOUR_HVM> --cdrom=dom0:/usr/local/iso/<YOUR_INSTALLER.ISO>
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>
$ qvm-start <YOUR_HVM> --cdrom=<YOUR_OTHER_QUBE>:/home/user/<YOUR_INSTALLER.ISO>
@ -172,8 +172,6 @@ Every guest operating system has its own way of handling networking, and the use
.. figure:: /attachment/doc/EndeavourOS_Network.png
:alt: Image of Qube Settings
Image of Qube Settings
In this example, Network Manager on KDE, the network had the following values:
1. IPv4 networking
@ -191,8 +189,6 @@ In this example, Network Manager on KDE, the network had the following values:
.. figure:: /attachment/doc/Network_Manager.png
:alt: Image of Network Manager, annotated by numbers for reference below
Image of Network Manager, annotated by numbers for reference below
The network was set up by entering Network Manager, selecting the Wi-Fi & Networking tab, clicking on the Wired Ethernet item, and selecting tab IPv4 (1). The Manual method was selected (2), which revealed areas for data entry. The DNS Servers section takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3). At the bottom of the tab (4), the ‘+ Add’ button was selected, and the IP address of 10.137.0.17 entered in the ‘Address’ column, the Netmask of 255.255.255.0 entered in the ‘Netmask’ column, and the Gateway of 10.138.24.248 under ‘Gateway’. Selecting the “Apply” button stored these changes
Using template-based HVMs
@ -203,9 +199,9 @@ 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>
$ qvm-create --class TemplateVM <YOUR_HVM_TEMPLATE_NAME> --property virt_mode=HVM --property kernel='' -l <YOUR_COLOR>
@ -223,7 +219,7 @@ Just like normal app qubes, HVMs can also be cloned either using the command ``q
The cloned qube will get identical root and private images and will essentially be identical to the original qube, except that it will get a different MAC address for the networking interface:
.. code:: bash
.. code:: console
[joanna@dom0 ~]$ qvm-prefs my-new-vm
autostart D False
@ -264,11 +260,11 @@ The cloned qube will get identical root and private images and will essentially
visible_ip6 D fd09:24ef:4179::a89:7a
visible_netmask D 255.255.255.255
xid D -1
[joanna@dom0 ~]$ qvm-clone my-new-vm my-new-vm-copy
/.../
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
autostart D False
backup_timestamp U
@ -313,10 +309,10 @@ The cloned qube will get identical root and private images and will essentially
Note that the MAC addresses differ between those two otherwise identical qubes. The IP addresses assigned by Qubes will also be different, of course, to allow networking to function properly:
.. code:: bash
.. code:: console
[joanna@dom0 ~]$ qvm-ls -n
NAME STATE NETVM IP IPBACK GATEWAY
my-new-hvm Halted sys-firewall 10.137.0.122 - 10.137.0.14
my-new-hvm-clone Halted sys-firewall 10.137.0.137 - 10.137.0.14
@ -325,7 +321,7 @@ Note that the MAC addresses differ between those two otherwise identical qubes.
If, for any reason, you would like to make sure that the two qubes have the same MAC address, you can use ``qvm-prefs`` to set a fixed MAC address:
.. code:: bash
.. code:: console
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
@ -379,23 +375,23 @@ 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
$ sudo apt install qemu-utils unzip
In a Fedora app qube:
.. code:: bash
.. code:: console
sudo dnf install qemu-img
$ sudo dnf install qemu-img
Unzip VirtualBox zip file:
.. code:: bash
.. code:: console
unzip *.zip
@ -403,7 +399,7 @@ Unzip VirtualBox zip file:
Extract OVA tar archive:
.. code:: bash
.. code:: console
tar -xvf *.ova
@ -411,7 +407,7 @@ Extract OVA tar archive:
Convert vmdk to raw:
.. code:: bash
.. code:: console
qemu-img convert -O raw *.vmdk win10.raw
@ -419,25 +415,25 @@ 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
$ qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /home/user/win10-root.img
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
$ qvm-create --property=virt_mode=hvm --property=memory=4096 --property=kernel='' --label red --standalone --root-move-from /home/user/win10-root.img win10
Start ``win10``:
.. code:: bash
.. code:: console
qvm-start win10
$ qvm-start win10
@ -447,7 +443,7 @@ Optional ways to get more information
Filetype of OVA file:
.. code:: bash
.. code:: console
file *.ova
@ -455,7 +451,7 @@ Filetype of OVA file:
List files of OVA tar archive:
.. code:: bash
.. code:: console
tar -tf *.ova
@ -463,7 +459,7 @@ List files of OVA tar archive:
List filetypes supported by qemu-img:
.. code:: bash
.. code:: console
qemu-img -h | tail -n1

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

@ -28,9 +28,9 @@ 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
$ 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,9 +146,9 @@ 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
$ sudo qubesctl state.sls qvm.sys-usb

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

@ -12,24 +12,24 @@ 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
$ qvm-volume info vmname:private
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
$ qvm-volume config vmname:private revisions_to_keep 2
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>
$ qvm-volume revert vmname:private <revision>

2
user/downloading-installing-upgrading/installation-guide-4.1.rst
View file

@ -51,7 +51,7 @@ Linux ISO to USB
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using ``dd``:
.. code:: bash
.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync

2
user/downloading-installing-upgrading/installation-guide.rst
View file

@ -51,7 +51,7 @@ Linux ISO to USB
On Linux, if you choose to use a USB drive, copy the ISO onto the USB device, e.g. using ``dd``:
.. code:: bash
.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 conv=fsync

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

@ -62,10 +62,10 @@ 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>
$ qvm-template --enablerepo=qubes-templates-itl-testing list --available
$ qvm-template --enablerepo=qubes-templates-itl-testing install <template_name>
@ -78,4 +78,4 @@ Providing feedback
Since the whole point of testing software is to discover and fix bugs, your feedback is an essential part of this process. We use an `automated build process <https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md>`__. For every package that is uploaded to a testing repository, a GitHub issue is created in the `updates-status <https://github.com/QubesOS/updates-status/issues>`__ repository for tracking purposes. We welcome any kind of feedback on any package in any testing repository. Even a simple |thumbsup| “thumbs up” or |thumbsdown| “thumbs down” reaction on the package’s associated issue would help us to decide whether the package is ready to be migrated to a stable repository. If you :doc:`report a bug </introduction/issue-tracking>` in a package that is in a testing repository, please reference the appropriate issue in `updates-status <https://github.com/QubesOS/updates-status/issues>`__.
.. |thumbsup| image:: /attachment/doc/like.png
.. |thumbsdown| image:: /attachment/doc/dislike.png
.. |thumbsdown| image:: /attachment/doc/dislike.png

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

@ -31,9 +31,9 @@ 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
$ sudo qubes-dom0-update
@ -49,10 +49,10 @@ 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
$ sudo qubes-dom0-update qubes-dom0-dist-upgrade
$ sudo qubes-dom0-update
@ -64,9 +64,9 @@ 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
$ sudo qubes-dom0-update qubes-template-fedora-20-x64

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

@ -19,22 +19,22 @@ 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
$ sudo yum install qubes-upgrade-vm
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
$ sudo yum update
The installer (yum) will prompt to accept the new Qubes R2 signing key:
.. code:: bash
.. code:: output
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
@ -70,18 +70,18 @@ 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
$ sudo qubes-dom0-update qubes-release
This should install ``qubes-release-1-6`` in your Dom0.
3. Install R2 packages:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=2
$ sudo qubes-dom0-update --releasever=2

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

@ -17,22 +17,22 @@ 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
$ sudo yum install qubes-upgrade-vm
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
$ sudo yum update
The installer (yum) will prompt to accept the new Qubes R2 signing key:
.. code:: bash
.. code:: output
Importing GPG key 0x0A40E458:
Userid : "Qubes OS Release 2 Signing Key"
@ -64,7 +64,7 @@ Installing new template
Qubes R2 Beta2 brings new fedora-18-x64 template (based on Fedora 18). You can install it from Qubes installation DVD. Insert installation DVD into your drive and issue following commands:
.. code:: bash
.. code:: console
$ sudo -s
# mkdir -p /mnt/cdrom
@ -86,26 +86,26 @@ 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
$ sudo qubes-dom0-update qubes-release
This should install ``qubes-release-1-6`` in your Dom0.
3. Install R2 upgrade package:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
$ sudo qubes-dom0-update --releasever=1 qubes-dist-upgrade
4. Start upgrade process:
.. code:: bash
.. code:: console
sudo qubes-dist-upgrade
$ sudo qubes-dist-upgrade
@ -115,9 +115,9 @@ 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
$ sudo qubes-dist-upgrade
again. This will start second stage of upgrade, here most packages will be upgraded, so this will take a while.

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

@ -21,15 +21,15 @@ 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
$ sudo yum update
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,9 +37,9 @@ 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
$ sudo yum --enablerepo=qubes-vm-r2b3-current update
@ -57,18 +57,18 @@ 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
$ sudo qubes-dom0-update qubes-release
This should install ``qubes-release-2-3.1`` in your Dom0.
3. Upgrade dom0 to R2 beta3:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-r2b3-current
@ -76,9 +76,9 @@ 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
$ qvm-shutdown --all --wait

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

@ -27,17 +27,17 @@ Upgrade Fedora template:
2. Install ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
$ sudo yum install qubes-upgrade-vm
3. Proceed with normal update in the template:
.. code:: bash
.. code:: console
sudo yum update
$ sudo yum update
You’ll need to accept “Qubes Release 3 Signing Key” - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don’t need to manually verify it.
@ -54,20 +54,19 @@ 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
sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
$ sudo cp /etc/apt/sources.list.d/qubes-r2.list /etc/apt/sources.list.d/qubes-r3-upgrade.list
$ sudo sed -i 's/r2/r3.0/' /etc/apt/sources.list.d/qubes-r3-upgrade.list
3. Proceed with normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
$ sudo apt-get update
$ sudo apt-get dist-upgrade
There will be some error messages during the process, but our tests does not revealed any negative consequences. Update of ``qubesdb-vm`` package will restart the service, which will fail (after 3min timeout), but you can ignore this problem for now. After completing the whole upgrade the service will be properly restarted.
@ -86,18 +85,18 @@ 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
$ sudo qubes-dom0-update qubes-release
This should install ``qubes-release-2-12`` in your Dom0.
3. Upgrade dom0 to R3.0:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=3.0
$ sudo qubes-dom0-update --releasever=3.0
After this step, until you reboot the system, most of the qvm-* tools will not work.
@ -106,9 +105,9 @@ 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
$ sudo systemctl enable xenconsoled.service xenstored.service
@ -124,9 +123,9 @@ 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
$ sudo qubes-dom0-update qubes-template-fedora-21
@ -150,7 +149,7 @@ Because of above limitations, you will need to configure some of those manually.
1. Check the VM network parameters, you will need them later:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-ls -n custom-template
-------------------+----+--------+-------+------+-------------+-------+-------------+---------+-------------+
@ -161,7 +160,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,19 +176,19 @@ 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
ip route add via 10.137.1.1
echo nameserver 10.137.1.1 > /etc/resolv.conf
$ ip addr add 10.137.1.53/32 dev eth0
$ ip route add 10.137.1.1/32 dev eth0
$ ip route add via 10.137.1.1
$ echo nameserver 10.137.1.1 > /etc/resolv.conf

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

@ -21,17 +21,17 @@ Upgrade Fedora templates:
2. Install the ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo yum install qubes-upgrade-vm
$ sudo yum install qubes-upgrade-vm
3. Proceed with a normal upgrade in the template:
.. code:: bash
.. code:: console
sudo yum upgrade
$ sudo yum upgrade
@ -47,27 +47,27 @@ 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
$ 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
3. Proceed with a normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
$ sudo apt-get update
$ sudo apt-get dist-upgrade
4. Remove unnecessary now file:
.. code:: bash
.. code:: console
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
$ sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
@ -85,9 +85,9 @@ Upgrading dom0
2. Upgrade dom0 to R3.1:
.. code:: bash
.. code:: console
sudo qubes-dom0-update --releasever=3.1
$ sudo qubes-dom0-update --releasever=3.1
At this point, most of the ``qvm-*`` tools will stop working until after you reboot the system.
@ -108,8 +108,8 @@ 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
$ sudo qubes-dom0-update qubes-template-fedora-23

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

@ -17,9 +17,9 @@ 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
$ sudo qubes-dom0-update --releasever=3.2 qubes-release
@ -29,15 +29,15 @@ 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
$ 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
(...)
Transaction Summary
===============================================================
Install 16 Packages (+ 31 Dependent packages)
Upgrade 4 Packages (+200 Dependent packages)
Total download size: 173 M
Is this ok [y/d/N]: n
Exiting on user command
@ -48,9 +48,9 @@ Upgrading dom0
4. Upgrade dom0 to R3.2:
.. code:: bash
.. code:: console
sudo qubes-dom0-update
$ sudo qubes-dom0-update
@ -66,7 +66,7 @@ Upgrading dom0
.. code:: bash
.. code:: output
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,25 +116,25 @@ Upgrade Fedora templates:
2. Install the ``qubes-upgrade-vm`` package:
.. code:: bash
.. code:: console
sudo dnf install --refresh qubes-upgrade-vm
$ sudo dnf install --refresh qubes-upgrade-vm
3. Proceed with a normal upgrade in the template:
.. code:: bash
.. code:: console
sudo dnf upgrade --refresh
$ sudo dnf upgrade --refresh
4. Add new packages (only needed in default template):
.. code:: bash
.. code:: console
sudo dnf install qubes-mgmt-salt-vm-connector
$ sudo dnf install qubes-mgmt-salt-vm-connector
@ -150,35 +150,35 @@ 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
$ 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
3. Proceed with a normal update in the template:
.. code:: bash
.. code:: console
sudo apt-get update
sudo apt-get dist-upgrade
$ sudo apt-get update
$ sudo apt-get dist-upgrade
4. Add new packages (only needed in default template):
.. code:: bash
.. code:: console
sudo apt-get install qubes-mgmt-salt-vm-connector
$ sudo apt-get install qubes-mgmt-salt-vm-connector
5. Remove unnecessary now file:
.. code:: bash
.. code:: console
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
$ sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list

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

@ -63,9 +63,9 @@ 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
$ sudo qubes-dom0-update

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

@ -39,7 +39,7 @@ In place upgrade is a complex operation. For this reason, we provide a ``qubes-d
.. code:: console
sudo qubes-dom0-update -y qubes-dist-upgrade
$ sudo qubes-dom0-update -y qubes-dist-upgrade
@ -50,9 +50,9 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
.. code:: output
Usage: qubes-dist-upgrade [OPTIONS]...
This script is used for updating current QubesOS R4.0 to R4.1.
Options:
--double-metadata-size, -d (STAGE 0) Double current LVM thin pool metadata size.
--update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM.
@ -61,7 +61,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
--dist-upgrade, -s (STAGE 4) Upgrade to Qubes R4.1 and Fedora 32 repositories.
--setup-efi-grub, -g (STAGE 5) Setup EFI Grub.
--all, -a Execute all the above stages in one call.
--assumeyes, -y Automatically answer yes for all questions.
--usbvm, -u Current UsbVM defined (default 'sys-usb').
--netvm, -n Current NetVM defined (default 'sys-net').
@ -74,7 +74,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
Can be useful if multiple updates proxy VMs are configured.
--max-concurrency How many TemplateVM/StandaloneVM to update in parallel in STAGE 1
(default 4).
--resync-appmenus-features Resync applications and features. To be ran individually
after reboot.
@ -84,7 +84,7 @@ After installing the tool, upgrade can be performed all at once with:
.. code:: console
sudo qubes-dist-upgrade --all
$ sudo qubes-dist-upgrade --all
@ -96,7 +96,7 @@ After completing “STAGE 0” through “STAGE 5”, restart the system. Then p
.. code:: console
sudo qubes-dist-upgrade --resync-appmenus-features
$ sudo qubes-dist-upgrade --resync-appmenus-features

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

@ -21,15 +21,15 @@ 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
$ sudo qubes-dom0-update -y qubes-dist-upgrade
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
@ -58,7 +58,7 @@ In place upgrade is a complex operation. For this reason, we provide a ``qubes-d
.. code:: console
sudo qubes-dom0-update -y qubes-dist-upgrade
$ sudo qubes-dom0-update -y qubes-dist-upgrade
@ -69,9 +69,9 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
.. code:: output
Usage: qubes-dist-upgrade [OPTIONS]...
This script is used for updating current QubesOS R4.1 to R4.2.
Options:
--update, -t (STAGE 1) Update of dom0, TemplatesVM and StandaloneVM.
--release-upgrade, -r (STAGE 2) Update 'qubes-release' for Qubes R4.2.
@ -84,7 +84,7 @@ Full list of options can be obtained with ``qubes-dist-upgrade --help``:
to the new format in /etc/qubes/policy.d.
--all-pre-reboot Execute stages 1 to 3
--all-post-reboot Execute stages 4 to 6
--assumeyes, -y Automatically answer yes for all questions.
--usbvm, -u Current UsbVM defined (default 'sys-usb').
--netvm, -n Current NetVM defined (default 'sys-net').
@ -104,7 +104,7 @@ After installing the tool, before-reboot stages can be performed at once with:
.. code:: console
sudo qubes-dist-upgrade --all-pre-reboot
$ sudo qubes-dist-upgrade --all-pre-reboot
@ -116,7 +116,7 @@ After completing “STAGE 1” through “STAGE 3”, restart the system. Then p
.. code:: console
sudo qubes-dist-upgrade --all-post-reboot
$ sudo qubes-dist-upgrade --all-post-reboot

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

@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2013-12-26-123456
backup-header
@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``private.img`` file which houses your data.
.. code:: bash
.. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@ -59,7 +59,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Decrypt the ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -in private.img.000 -out private.img.dec.000
@ -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
@ -84,7 +84,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Decompress the decrypted ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ zforce private.img.dec.*
[user@restore vm1]$ gunzip private.img.dec.000.gz
@ -99,7 +99,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Untar the decrypted and decompressed ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ tar -M -xvf private.img.dec.000
vm1/private.img
@ -126,7 +126,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Mount the private.img file and access your data.
.. code:: bash
.. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/

20
user/how-to-guides/backup-emergency-restore-v3.rst
View file

@ -11,7 +11,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
1. Untar the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2015-06-05T123456
backup-header
@ -33,7 +33,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -41,7 +41,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
3. Verify the integrity of the ``backup-header`` file, which contains basic information about your backup.
.. code:: bash
.. code:: console
[user@restore ~]$ openssl dgst -sha512 -hmac "$backup_pass" backup-header
HMAC-SHA512(backup-header)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
@ -58,7 +58,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
4. Read the ``backup-header``. You’ll need some of this information later. The file will look similar to this:
.. code:: bash
.. code:: console
[user@restore ~]$ cat backup-header
version=3
@ -73,7 +73,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
5. Verify the integrity of the ``private.img`` file which houses your data.
.. code:: bash
.. code:: console
[user@restore ~]$ cd vm1/
[user@restore vm1]$ openssl dgst -sha512 -hmac "$backup_pass" private.img.000
@ -91,7 +91,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
6. Decrypt the ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ find -name 'private.img.*[0-9]' | sort -V | xargs cat | openssl enc -d -md MD5 -pass pass:"$backup_pass" -aes-256-cbc -out private.img.dec
@ -100,7 +100,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
7. Decompress the decrypted ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ zforce private.img.dec
private.img.dec -- replaced with private.img.dec.gz
@ -109,7 +109,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
**Note:** If your backup was compressed with a program other than ``gzip``, you must substitute the correct compression program. This information is contained in the ``backup-header`` file (see step 4). For example, if you used ``bzip2``, then you should do this:
.. code:: bash
.. code:: console
[user@restore vm1]$ mv private.img.dec private.img.dec.bz2
[user@restore vm1]$ bunzip2 private.img.dec.bz2
@ -118,7 +118,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
8. Untar the decrypted and decompressed ``private.img`` file.
.. code:: bash
.. code:: console
[user@restore vm1]$ tar -xvf private.img.dec
vm1/private.img
@ -127,7 +127,7 @@ The Qubes backup system has been designed with emergency disaster recovery in mi
9. Mount the private.img file and access your data.
.. code:: bash
.. code:: console
[user@restore vm1]$ sudo mkdir /mnt/img
[user@restore vm1]$ sudo mount -o loop vm1/private.img /mnt/img/

32
user/how-to-guides/backup-emergency-restore-v4.rst
View file

@ -19,7 +19,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
1. If you’re not on Qubes 4.X, :ref:`import and authenticate the Release 4 Signing Key <project-security/verifying-signatures:how to import and authenticate release signing keys>`.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
@ -27,14 +27,14 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
2. Download the ``scrypt`` RPM.
.. code:: bash
.. code:: console
[user@restore ~]$ dnf download scrypt
Or, if that doesn’t work:
.. code:: bash
.. code:: console
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
@ -42,7 +42,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
3. Verify the signature on the ``scrypt`` RPM.
.. code:: bash
.. code:: console
[user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK
@ -52,7 +52,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
4. Install ``rpmdevtools``.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo dnf install rpmdevtools
@ -60,7 +60,7 @@ Here are instructions for obtaining a compiled ``scrypt`` binary. This example u
5. Extract the ``scrypt`` binary from the RPM and make it conveniently available.
.. code:: bash
.. code:: console
[user@restore ~]$ rpmdev-extract scrypt-*.rpm
[user@restore ~]$ alias scrypt="$PWD/scrypt-*/usr/bin/scrypt"
@ -77,7 +77,7 @@ Emergency recovery instructions
1. Untar the backup metadata from the main backup file.
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 \
backup-header backup-header.hmac qubes.xml.000.enc
@ -89,7 +89,7 @@ Emergency recovery instructions
2. Set the backup passphrase environment variable. While this isn’t strictly required, it will be handy later and will avoid saving the passphrase in the shell’s history.
.. code:: bash
.. code:: console
[user@restore ~]$ read -r backup_pass
@ -98,7 +98,7 @@ Emergency recovery instructions
3. Verify the integrity of ``backup-header`` using ``backup-header.hmac`` (an encrypted *and integrity protected* version of ``backup-header``).
.. code:: bash
.. code:: console
[user@restore ~]$ set +H
[user@restore ~]$ echo "backup-header!$backup_pass" |\
@ -117,7 +117,7 @@ Emergency recovery instructions
4. Read ``backup-header``.
.. code:: bash
.. code:: console
[user@restore ~]$ cat backup-header
version=4
@ -131,7 +131,7 @@ Emergency recovery instructions
5. Set ``backup_id`` to the value in the last line of ``backup-header``. (Note that there is a hyphen in ``backup-id`` in the file, whereas there is an underscore in ``backup_id`` in the variable you’re setting.)
.. code:: bash
.. code:: console
[user@restore ~]$ backup_id=20230405T123455-1234
@ -139,7 +139,7 @@ Emergency recovery instructions
6. Verify and decrypt, decompress, and extract the ``qubes.xml`` file.
.. code:: bash
.. code:: console
[user@restore ~]$ echo "$backup_id!qubes.xml.000!$backup_pass" |\
scrypt dec -P qubes.xml.000.enc | gzip -d | tar -xv
@ -155,7 +155,7 @@ Emergency recovery instructions
7. Search inside of the ``qubes.xml`` file for the ``backup-path`` of the qube whose data you wish to restore. If you install the ``xmlstarlet`` package, the following command will convert ``qubes.xml`` to a friendlier listing for this purpose:
.. code:: bash
.. code:: console
[user@restore ~]$ xmlstarlet sel -T -t -m //domain \
-v 'concat(.//property[@name="name"], " ", .//feature[@name="backup-path"])' \
@ -182,7 +182,7 @@ Emergency recovery instructions
The example output above shows that the backup file includes a qube named ``personal`` and a qube named ``vault``, with ``backup-path`` values of ``vm123/`` and ``vm321/`` respectively. (Every other listed qube was not selected to be included in the backup file.) Use the corresponding value to untar the necessary data files of the qube:
.. code:: bash
.. code:: console
[user@restore ~]$ tar -i -xvf qubes-backup-2023-04-05T123456 vm123/
@ -190,7 +190,7 @@ Emergency recovery instructions
8. Verify and decrypt the backed up data, decompress it, and extract it.
.. code:: bash
.. code:: console
[user@restore ~]$ find vm123/ -name 'private.img.*.enc' | sort -V | while read f_enc; do \
f_dec=${f_enc%.enc}; \
@ -204,7 +204,7 @@ Emergency recovery instructions
9. Mount ``private.img`` and access your data.
.. code:: bash
.. code:: console
[user@restore ~]$ sudo mkdir /mnt/img
[user@restore ~]$ sudo mount -o loop vm123/private.img /mnt/img/

2
user/how-to-guides/how-to-back-up-restore-and-migrate.rst
View file

@ -15,7 +15,7 @@ Backing up changes to dom0
When backing up dom0 using the Qubes backup tool (explained below), only the home directory is backed up. Therefore, if there are files outside of the home directory you wish to save, you should copy them into the home directory prior to creating a backup. Here is an example of how to back up Qubes config files and RPC policies:
.. code:: bash
.. code:: console
$ mkdir -p ~/backup/etc/qubes/
$ cp -a /etc/qubes/* ~/backup/etc/qubes/

10
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,15 +28,15 @@ 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]+
$ qvm-copy [--without-progress] file [file]+
.. code:: bash
.. code:: console
qvm-move [--without-progress] file [file]+
$ qvm-move [--without-progress] file [file]+

14
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:: text
/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,9 +66,9 @@ 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
$ qvm-service --enable VMNAME gui-agent-clipboard-wipe
@ -78,10 +78,10 @@ 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'
$ qvm-features dom0 gui-default-secure-copy-sequence 'Mod4-c'
$ qvm-features dom0 gui-default-secure-paste-sequence 'Mod4-v'

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

@ -15,9 +15,9 @@ 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>
$ qvm-copy-to-vm <target_vm> <file>
@ -71,15 +71,15 @@ 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
$ qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
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:: text
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

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

@ -34,9 +34,9 @@ Installing software from default repositories
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
:alt: The Applications tab in Qube Settings
Installing software from other sources
--------------------------------------
@ -52,7 +52,7 @@ If you are still using the distribution package manager, updates will likely sti
If you are using another installation method fetching remote resources, you might still be able to use the updates proxy by making the tools aware of the proxy. For many tools, it is enough to export the following environment variables in your shell session before proceeding:
.. code:: bash
.. code:: console
$ export HTTP_PROXY=http://127.0.0.1:8082 http_proxy=$HTTP_PROXY \
HTTPS_PROXY=$HTTP_PROXY https_proxy=$HTTPS_PROXY \
@ -89,9 +89,9 @@ This method assumes that you are trying to follow instructions to install some p
.. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png
:alt: `The Applications tab in Qube Settings </attachment/doc/r4.1-dom0-appmenu-select.png>`__
:alt: The Applications tab in Qube Settings
Troubleshooting
---------------
@ -155,11 +155,11 @@ 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
sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
$ sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing
$ sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing
$ sudo dnf upgrade --enablerepo=qubes-vm-*-unstable
@ -193,13 +193,13 @@ 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
sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
sudo dnf upgrade --refresh
$ sudo dnf config-manager setopt rpmfusion-free.enabled=1
$ sudo dnf config-manager setopt rpmfusion-free-updates.enabled=1
$ sudo dnf config-manager setopt rpmfusion-nonfree.enabled=1
$ sudo dnf config-manager setopt rpmfusion-nonfree-updates.enabled=1
$ sudo dnf upgrade --refresh
@ -229,9 +229,9 @@ Root revert
2. In a dom0 terminal:
.. code:: bash
.. code:: console
qvm-volume revert <template>:root
$ qvm-volume revert <template>:root
@ -281,12 +281,12 @@ 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
@tag:whonix-updatevm @anyvm deny
# other templates use sys-net
@type:TemplateVM @default allow,target=sys-net
@anyvm @anyvm deny
@ -300,7 +300,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
1. In the **template** you must install ``snapd`` and ``qubes-snapd-helper``. Open a terminal in the template and run:
.. code:: bash
.. code:: console
[user@fedora-36-snap-demo ~]$ sudo dnf install snapd qubes-snapd-helper
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
@ -313,15 +313,15 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
qubes-snapd-helper noarch 1.0.4-1.fc36 qubes-vm-r4.1-current 10 k
Installing dependencies:
[...]
Transaction Summary
========================================================================================================
Install 19 Packages
Total download size: 27 M
Installed size: 88 M
Is this ok [y/N]: y
Downloading Packages:
[..]
Failed to resolve booleanif statement at /var/lib/selinux/targeted/tmp/modules/200/snappy/cil:1174
@ -329,7 +329,7 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
[...]
Last metadata expiration check: 0:33:05 ago on Thu 03 Nov 2022 04:34:06.
Notifying dom0 about installed applications
Installed:
snapd-2.56.2-4.fc36.x86_64 qubes-snapd-helper-1.0.4-1.fc36.noarch
[...]
@ -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!
@ -346,14 +346,14 @@ Snap packages do not use the normal update channels for Debian and Fedora (apt a
This is expected and you can safely continue.
Shutdown the template:
.. code:: bash
.. code:: console
[user@fedora-36-snap-demo ~]$ sudo shutdown -h now
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
.. code:: bash
.. code:: console
[user@snap-demo-app qube ~]$ snap install <package>
@ -377,7 +377,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
2. List the names of the available desktop shortcuts by running the command ``ls /usr/share/applications`` and find the exact name of the shortcut to the app you want to autostart:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop
@ -390,7 +390,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
3. Create the autostart directory:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ mkdir -p ~/.config/autostart
@ -398,7 +398,7 @@ If you want a desktop app to start automatically every time a qube starts you ca
4. Make a link to the desktop app file you’d like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
.. code:: bash
.. code:: console
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop

18
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
@ -89,7 +89,7 @@ Carol, the investor
Carol works hard and lives below her means so that she can save money and invest it for her future. She hopes to become financially independent and maybe even retire early someday, and she’s decided that her best bet for achieving this is by investing for the long term and allow compounding to do its work. However, after doing some research into her country’s consumer financial protection laws, she learned that there’s no legal guarantee that customers will be made whole in the event of theft or fraud. The various insurance and protection organizations only guarantee recovery in the case of a financial institution *failing*, which is quite different from an individual customer being hacked. Moreover, even though many financial institutions have their own cybercrime policies, rarely, if ever, do they explicitly guarantee reimbursement in the event that a *customer* gets hacked (rather than the institution itself).
.. warning::
Carol looked into how thieves might actually try to steal her hard-earned wealth and was surprised to learn that they have all sorts of ploys that she had never even considered. For example, she had assumed that any theft would, at the bare minimum, have to involve transferring money out of her account. That seems like a safe assumption. But then she read about “pump and dump” attacks, where thieves buy up some penny stock, hack into innocent people’s brokerage accounts, then use the victims’ funds to buy that same penny stock, “pumping” up its price so that the thieves can “dump” their shares on the market, leaving the victims with worthless shares. No money is ever transferred into or out of the victims’ account; it’s just used to buy and sell securities. So, all the safeguards preventing new bank accounts from being added or requiring extra approval for outbound transfers do nothing to protect victims’ funds in cases like these. And this is just one example! Carol realized that she couldn’t assume that existing safeguards against specific, known attacks were enough. She had to think about security at a more fundamental level and design it into her digital life from the ground up.
After learning about all this, Carol decided that it was ultimately up to her to take care of her own cybersecurity. She couldn’t rely on anyone else to do it for her. Sure, most people just use regular consumer tech and will probably end up fine, but, she reminded herself, most people also don’t have as much to lose. It’s not a risk that she was willing to take with her future, especially knowing that there’s probably no government bailout waiting for her and that all the brokerage firms’ vaguely reassuring marketing language about cybersecurity isn’t legally binding. So, Carol started reading more about computer security and eventually stumbled upon Qubes OS after searching the web for “most secure operating system.” She read about how it’s designed and why. Although she didn’t immediately understand all of the technical details, the fundamental principle of :doc:`security-by-compartmentalization </developer/system/architecture>` made intuitive sense to her, and the more she learned about the technical aspects, the more she realized that this is what she’d been looking for. Today, her setup looks like this:
@ -119,7 +119,7 @@ Bonus: Carol explores new financial technology
The vast majority of Carol’s assets are in broad-based, low-cost, passively-managed indexed funds. Lately, however, she’s started getting interested in cryptocurrency. She’s still committed to staying the course with her tried-and-true investments, and she’s always been skeptical of new asset classes, especially those that don’t generate cash flows or that often seem to be associated with scams or wild speculation. However, she finds the ability to self-custody a portion of her assets appealing from a long-term risk management perspective, particularly as a hedge against certain types of political risk.
.. DANGER::
Some of Carol’s friends warned her that cryptocurrency is extremely volatile and that hacking and theft are common occurrences. Carol agreed and reassured them that she’s educated herself about the risks and will make sure she never invests more than she can afford to lose.
Carol has added the following to her Qubes setup:
@ -169,7 +169,7 @@ Conclusion
The characters we’ve met today may be fictional, but they represent the needs of real users like you. You may find that your own needs overlap with more than one of them, in which case you may find it useful to model certain subsets of your overall Qubes system on different examples. You probably also noticed that there are commonalities among them. Most people need to use email, for example, so most people will need at least one email qube and a suitable template to base it on. But not everyone will need :doc:`Split GPG </user/security-in-qubes/split-gpg>`, and not everyone will want to use the same email client. On the other hand, almost everyone will need a password manager, and it pretty much always makes sense to keep it in an offline, network-isolated vault.
.. note::
As you gain experience with Qubes, you may find yourself disagreeing with some of the decisions our fictional friends made. That’s okay! There are many different ways to organize a Qubes system, and the most important criterion is that it serves the needs of its owner. Since everyone’s needs are different, it’s perfectly normal to find yourself doing things a bit differently. Nonetheless, there are some general principles that almost all users find helpful, especially when they’re first starting out.
As you’re designing your own Qubes system, keep in mind some of the following lessons from our case studies:
@ -189,16 +189,16 @@ As you’re designing your own Qubes system, keep in mind some of the following
.. |Alice’s system: diagram 1| image:: /attachment/doc/howto_use_qubes_alice_1.png
.. |Alice’s system: diagram 2| image:: /attachment/doc/howto_use_qubes_alice_2.png
.. |A diagram of Bob’s system| image:: /attachment/doc/howto_use_qubes_bob.png
.. |A diagram of Carol’s system| image:: /attachment/doc/howto_use_qubes_carol.png
.. |Simple VM setup| image:: /attachment/doc/Simple_Setup.png

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

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

@ -36,7 +36,7 @@ By default, the **Qubes Update** tool will appear as an icon in the Notification
However, you can also start the tool manually by selecting it in the Applications Menu under “Qubes Tools.” Even if no updates have been detected, you can use this tool to check for updates manually at any time by selecting all desired items from the list and clicking “Update”.
.. note::
For information about how templates download updates, please see :ref:`Why don’t templates have normal network access? <user/how-to-guides/how-to-install-software:why don't templates have normal network access?>` and the :ref:`Updates proxy <user/how-to-guides/how-to-install-software:updates proxy>` .
By default, most qubes that are connected to the internet will periodically check for updates for their parent templates. You can check the date of the last update check in the “last checked” column. If updates are available for any qube, you will receive a notification as described above, and in the “Updates available” column you will see “YES” for that qube(s). If the update check did not find any new updates, “NO” will appear in the column. Respectively, for qubes that are no longer supported, “OBSOLETE” will be displayed. However, if you have any templates that do *not* have any online child qubes, you will *not* receive update notifications for them. By default, after a week, if updates for a given qube have not been checked, the value in the “Updates available” column will be set to “MAYBE”.
@ -82,7 +82,7 @@ Command-line interface
.. DANGER::
**Warning:** Updating with direct commands such as dnf update and apt update is not recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the **Qubes Update** tool or its command-line equivalents, as described below. (By contrast, :doc:`installing </user/how-to-guides/how-to-install-software>` packages using direct package manager commands is fine.)
Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
@ -159,7 +159,7 @@ First, ensure that your UpdateVM contains the ``fwupd-qubes-vm`` package. This p
In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update fwupd-qubes-dom0
@ -167,7 +167,7 @@ In a dom0 terminal, install the ``fwupd-qubes-dom0`` package:
Once the package is installed:
.. code:: bash
.. code:: console
$ sudo qubes-fwupdmgr get-devices
@ -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:: output
WARNING: UEFI capsule updates not available or enabled
@ -185,7 +185,7 @@ If so, `adjust your BIOS settings <https://github.com/fwupd/fwupd/wiki/PluginFla
Once resolved, in a dom0 terminal:
.. code:: bash
.. code:: console
$ sudo qubes-fwupdmgr get-devices
$ sudo qubes-fwupdmgr refresh
@ -212,7 +212,7 @@ Computers without fwupd support
For computers that do not have firmware update support via ``fwupd``, follow the firmware update instructions on the manufacturer’s website. Verify the authenticity of any firmware updates you apply.
.. |Qube Updates Available| image:: /attachment/doc/r4.2-qube-updates-available.png
.. |Qubes Update| image:: /attachment/doc/r4.2-software-update.png

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

@ -27,11 +27,11 @@ 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
sudo mount /dev/xvdi2 mnt
$ cd ~
$ mkdir mnt
$ sudo mount /dev/xvdi2 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
$ 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,9 +71,9 @@ 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
$ qvm-block attach work sys-usb:sdb
@ -85,11 +85,11 @@ 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
sudo mount /dev/xvdi mnt
$ cd ~
$ mkdir mnt
$ sudo mount /dev/xvdi mnt
@ -99,17 +99,17 @@ In case of a USB-drive, make sure it’s attached to your computer. If you don
.. code:: bash
.. code:: console
sudo umount mnt
$ sudo umount mnt
5. In a dom0 console, detach the device
.. code:: bash
.. code:: console
qvm-block detach work sys-usb:sdb
$ 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,9 +175,9 @@ 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
$ sudo losetup -f --show /path/to/file
`This command <https://linux.die.net/man/8/losetup>`__ will create the device node ``/dev/loop0`` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found.
@ -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,17 +199,17 @@ 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
$ qvm-block a targetVM sourceVM:loop0
4. After detaching, destroy the loop-device inside the sourceVM as follows:
.. code:: bash
.. code:: console
sudo losetup -d /dev/loop0
$ sudo losetup -d /dev/loop0
@ -229,9 +229,9 @@ 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
$ qvm-block a work sys-usb:sda1 -o frontend-dev=xvdz
@ -247,17 +247,17 @@ 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
$ qvm-block a work sys-usb:sda1 -o read-only=true
There exists a shortcut to set read-only ``true``, ``--ro``:
.. code:: bash
.. code:: console
qvm-block a work sys-usb:sda1 --ro
$ qvm-block a work sys-usb:sda1 --ro
@ -271,9 +271,9 @@ 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
$ qvm-block a work sys-usb:sda1 -o devtype=cdrom

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

@ -63,9 +63,9 @@ 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
$ qvm-prefs <APP_QUBE> template_for_dispvms True
@ -73,9 +73,9 @@ 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>
$ qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
@ -89,17 +89,17 @@ 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
$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
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>
$ 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
@ -235,4 +235,4 @@ Customizing disposables
You can change the template used to generate the disposables, and change settings used in the disposable savefile. These changes will be reflected in every new disposable based on that template. Full instructions can be found :doc:`here </user/advanced-topics/disposable-customization>`.
.. |disposablevm-example.png| image:: /attachment/doc/disposablevm-example.png

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

@ -53,17 +53,17 @@ 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
$ qvm-pci
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
$ qvm-pci attach targetVM sourceVM:[BDF] --persistent
@ -71,9 +71,9 @@ 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
$ qvm-pci attach work dom0:00_1a.0 --persistent
@ -99,9 +99,9 @@ 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
$ qvm-pci a work dom0:00_1a.0 --persistent -o no-strict-reset=true
@ -113,9 +113,9 @@ 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
$ qvm-pci a work dom0:00_1a.0 --persistent -o permissive=true
@ -139,12 +139,12 @@ 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`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
$ echo <BDF> > /sys/bus/pci/drivers/pciback/unbind
$ MODALIAS=`cat /sys/bus/pci/devices/<BDF>/modalias`
$ MOD=`modprobe -R $MODALIAS | head -n 1`
$ echo <BDF> > /sys/bus/pci/drivers/$MOD/bind

30
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,17 +102,17 @@ 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
$ sudo dnf install qubes-usb-proxy
- Debian/Ubuntu:
.. code:: bash
.. code:: console
sudo apt-get install qubes-usb-proxy
$ sudo apt-get install qubes-usb-proxy
@ -136,15 +136,15 @@ 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
$ lsusb
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:: output
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:: output
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
@ -172,15 +172,15 @@ 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
$ qvm-pci attach --persistent personal dom0:00_1a.0
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:: output
../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1

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

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

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

@ -53,7 +53,7 @@ These instructions assume that there is a ``sys-usb`` qube that holds the USB st
In dom0:
.. code:: bash
.. code:: console
$ sudo qubes-dom0-update qubes-ctap-dom0
$ qvm-service --enable work qubes-ctap-proxy
@ -64,7 +64,7 @@ The above assumes a ``work`` qube in which you would like to enable ctap. Repeat
In Fedora templates:
.. code:: bash
.. code:: console
$ sudo dnf install qubes-ctap
@ -72,7 +72,7 @@ In Fedora templates:
In Debian templates:
.. code:: bash
.. code:: console
$ sudo apt install qubes-ctap
@ -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,10 +104,10 @@ 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
$ systemctl enable qubes-ctapproxy@USB_QUBE.service
$ systemctl disable qubes-ctapproxy@sys-usb.service
@ -122,4 +122,4 @@ Template and browser support
The large number of possible combinations of template (Fedora 37, 38; Debian 10, 11) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes CTAP Proxy. In some cases, you may be the first person to try a particular combination. Consequently, (and as with any new feature), users will inevitably encounter bugs. We ask for your patience and understanding in this regard. As always, please :doc:`report any bugs you encounter </introduction/issue-tracking>`.
.. |Qubes CTAP Proxy diagram| image:: /attachment/doc/ctap.svg

90
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,17 +61,17 @@ 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>
$ qvm-prefs <vm> netvm <netvm>
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
$ 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,9 +121,9 @@ 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
$ 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,9 +131,9 @@ 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
$ sudo nft add rule qubes custom-input ip saddr <IP address of A> ct state new,established,related counter accept
@ -143,7 +143,7 @@ In order to allow networking from qube A (client) to qube B (server) follow thes
.. code:: bash
.. code:: console
[user@sys-firewall ~]$ sudo -i
[root@sys-firewall user]# echo "nft add rule ip qubes custom-forward ip saddr 10.137.2.25 ip daddr 10.137.2.6 ct state new,established,related counter accept" >> /rw/config/qubes-firewall-user-script
@ -154,7 +154,7 @@ In order to allow networking from qube A (client) to qube B (server) follow thes
.. code:: bash
.. code:: console
[user@B ~]$ sudo -i
[root@B user]# echo "nft add rule qubes custom-input ip saddr 10.137.2.25 accept" >> /rw/config/rc.local
@ -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
@ -181,7 +181,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In untrusted, use the Qubes tool ``qvm-connect-tcp``:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
@ -195,7 +195,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
Here ``@default`` is used to hide the destination qube which is specified in the Qubes RPC policy by ``target=mytcp-service``. Equivalent call is to use the tool as follow:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::444
@ -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
@ -215,7 +215,7 @@ Consider now the case where someone prefers to specify the destination qube and
in ``/etc/qubes/policy.d/30-user-networking.policy`` and in untrusted, use the tool as follow:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp 10444:mytcp-service:444
@ -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
@ -235,7 +235,7 @@ One can go further than the previous examples by redirecting different ports to
In that case, calling ``qvm-connect-tcp`` like previous examples, will still bind TCP port ``444`` of ``mytcp-service`` to ``untrusted`` but now, calling it with port ``445``
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::445
@ -247,15 +247,15 @@ will restrict the binding to only the corresponding TCP port of ``mytcp-service-
For creating a permanent port bind between two qubes, ``systemd`` can be used. We use the case of the first example. In ``/rw/config`` (or any place you find suitable) of qube ``untrusted``, create ``my-tcp-service.socket`` with content:
.. code:: bash
.. code:: systemd
[Unit]
Description=my-tcp-service
[Socket]
ListenStream=127.0.0.1:444
Accept=true
[Install]
WantedBy=sockets.target
@ -263,11 +263,11 @@ For creating a permanent port bind between two qubes, ``systemd`` can be used. W
and ``my-tcp-service@.service`` with content:
.. code:: bash
.. code:: systemd
[Unit]
Description=my-tcp-service
[Service]
ExecStart=qrexec-client-vm '' qubes.ConnectTCP+444
StandardInput=socket
@ -353,7 +353,7 @@ When writing rules in sys-net, you can use ``iif`` or ``iifname``. ``iif`` is fa
In the sys-net VM’s Terminal, the first step is to define an nftables chain that will receive DNAT rules to relay the network traffic on a given port to the qube NetVM, we recommend to define a new chain for each destination qube to ease rules management:
.. code:: bash
.. code:: console
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@ -367,7 +367,7 @@ In the sys-net VM’s Terminal, the first step is to define an nftables chain th
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
.. code:: bash
.. code:: console
nft add rule qubes custom-dnat-qubeDEST iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
@ -375,7 +375,7 @@ Second step, code a natting firewall rule to route traffic on the outside interf
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
.. code:: bash
.. code:: console
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
@ -389,7 +389,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
Verify the rules on the sys-net firewall correctly match the packets you want by looking at the counters: check for the counter lines in the chains ``custom-forward`` and ``custom-dnat-qubeDEST``:
.. code:: bash
.. code:: console
nft list table ip qubes
@ -397,12 +397,12 @@ Verify the rules on the sys-net firewall correctly match the packets you want by
In this example, we can see 7 packets in the forward rule, and 3 packets in the dnat rule:
.. code:: bash
.. code:: output
chain custom-forward {
iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter packets 7 bytes 448 accept
}
chain custom-dnat-qubeDEST {
type nat hook prerouting priority filter + 1; policy accept;
iifname ens6 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter packets 3 bytes 192 dnat to 10.138.33.59
@ -412,7 +412,7 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
(Optional) You can send a test packet by trying to connect to the service from an external device using the following command:
.. code:: bash
.. code:: console
telnet 192.168.x.n 443
@ -420,7 +420,7 @@ In this example, we can see 7 packets in the forward rule, and 3 packets in the
Once you have confirmed that the counters increase, store the commands used in the previous steps in ``/rw/config/qubes-firewall-user-script`` so they get set on sys-net start-up:
.. code:: bash
.. code:: console
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
@ -432,13 +432,13 @@ Content of ``/rw/config/qubes-firewall-user-script`` in ``sys-net``:
.. code:: bash
#!/bin/sh
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iifname ens6 saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.1.z
# allow forwarded traffic
nft add rule qubes custom-forward iifname ens6 ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept
fi
@ -451,7 +451,7 @@ For the following example, we use the fact that the interface of sys-firewall fa
In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
.. code:: bash
.. code:: console
nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
@ -459,7 +459,7 @@ In the sys-firewall Terminal, add a DNAT chain that will contain routing rules:
Second step, code a natting firewall rule to route traffic on the outside interface for the service to the destination qube
.. code:: bash
.. code:: console
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 ip saddr 192.168.x.y/24 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
@ -467,7 +467,7 @@ Second step, code a natting firewall rule to route traffic on the outside interf
Third step, code the appropriate new filtering firewall rule to allow new connections for the service
.. code:: bash
.. code:: console
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
@ -479,7 +479,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec
Once you have confirmed that the counters increase, store these commands in the script ``/rw/config/qubes-firewall-user-script``
.. code:: bash
.. code:: console
[user@sys-net user]$ sudo -i
[root@sys-net user]# nano /rw/config/qubes-firewall-user-script
@ -491,13 +491,13 @@ Content of ``/rw/config/qubes-firewall-user-script`` in ``sys-firewall``:
.. code:: bash
#!/bin/sh
# create the dnat chain for qubeDEST if it doesn't already exist
if nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }'
then
# create the dnat rule
nft add rule qubes custom-dnat-qubeDEST iifgroup 1 tcp dport 443 ct state new,established,related counter dnat 10.137.0.xx
# allow forwarded traffic
nft add rule qubes custom-forward iifgroup 1 ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept
fi
@ -514,7 +514,7 @@ For the following example, we assume that the target VM running the web server h
The according rule to allow the traffic is:
.. code:: bash
.. code:: console
nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept
@ -522,7 +522,7 @@ The according rule to allow the traffic is:
To make it persistent, you need to add this command in the script ``/rw/config/rc.local``:
.. code:: bash
.. code:: console
[user@qubeDEST user]$ sudo -i
[root@qubeDEST user]# echo 'nft add rule qubes custom-input tcp dport 443 ip daddr 10.137.0.xx ct state new,established,related counter accept' >> /rw/config/rc.local
@ -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

162
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,9 +109,9 @@ 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
$ sudo iptables -I FORWARD 2 -s <IP address of A> -d <IP address of B> -j ACCEPT
@ -119,9 +119,9 @@ 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
$ sudo iptables -I INPUT -s <IP address of A> -j ACCEPT
@ -131,7 +131,7 @@ In order to allow networking between qubes A and B follow these steps:
.. code:: bash
.. code:: console
[user@sys-firewall ~]$ sudo bash
[root@sys-firewall user]# echo "iptables -I FORWARD 2 -s 10.137.2.25 -d 10.137.2.6 -j ACCEPT" >> /rw/config/qubes-firewall-user-script
@ -143,7 +143,7 @@ In order to allow networking between qubes A and B follow these steps:
.. code:: bash
.. code:: console
[user@B ~]$ sudo bash
[root@B user]# echo "iptables -I INPUT -s 10.137.2.25 -j ACCEPT" >> /rw/config/rc.local
@ -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
@ -171,7 +171,7 @@ Consider the following example. ``mytcp-service`` qube has a TCP service running
- In untrusted, use the Qubes tool ``qvm-connect-tcp``:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
@ -185,7 +185,7 @@ The service of ``mytcp-service`` running on port ``444`` is now accessible in ``
Here ``@default`` is used to hide the destination qube which is specified in the Qubes RPC policy by ``target=mytcp-service``. Equivalent call is to use the tool as follow:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::444
@ -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
@ -205,7 +205,7 @@ Consider now the case where someone prefers to specify the destination qube and
in ``/etc/qubes/policy.d/30-user-networking.policy`` and in untrusted, use the tool as follow:
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp 10444:mytcp-service:444
@ -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
@ -225,7 +225,7 @@ One can go further than the previous examples by redirecting different ports to
In that case, calling ``qvm-connect-tcp`` like previous examples, will still bind TCP port ``444`` of ``mytcp-service`` to ``untrusted`` but now, calling it with port ``445``
.. code:: bash
.. code:: console
[user@untrusted #]$ qvm-connect-tcp ::445
@ -237,15 +237,15 @@ will restrict the binding to only the corresponding TCP port of ``mytcp-service-
For creating a permanent port bind between two qubes, ``systemd`` can be used. We use the case of the first example. In ``/rw/config`` (or any place you find suitable) of qube ``untrusted``, create ``my-tcp-service.socket`` with content:
.. code:: bash
.. code:: systemd
[Unit]
Description=my-tcp-service
[Socket]
ListenStream=127.0.0.1:444
Accept=true
[Install]
WantedBy=sockets.target
@ -253,11 +253,11 @@ For creating a permanent port bind between two qubes, ``systemd`` can be used. W
and ``my-tcp-service@.service`` with content:
.. code:: bash
.. code:: systemd
[Unit]
Description=my-tcp-service
[Service]
ExecStart=qrexec-client-vm '' qubes.ConnectTCP+444
StandardInput=socket
@ -327,7 +327,7 @@ For the following example, we assume that the physical interface eth0 in sys-net
In the sys-net VM’s Terminal, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM
.. code:: bash
.. code:: console
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT --to-destination 10.137.1.z
@ -335,7 +335,7 @@ In the sys-net VM’s Terminal, code a natting firewall rule to route traffic on
Code the appropriate new filtering firewall rule to allow new connections for the service
.. code:: bash
.. code:: console
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
@ -351,7 +351,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2)
.. code:: bash
.. code:: console
iptables -t nat -L -v -n
iptables -L -v -n
@ -362,7 +362,7 @@ Verify you are cutting through the sys-net VM firewall by looking at its counter
.. code:: bash
.. code:: console
nft list table ip qubes-firewall
@ -370,7 +370,7 @@ Verify you are cutting through the sys-net VM firewall by looking at its counter
Send a test packet by trying to connect to the service from an external device
.. code:: bash
.. code:: console
telnet 192.168.x.y 443
@ -378,54 +378,54 @@ 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
$ sudo nano /rw/config/rc.local
.. code:: bash
#!/bin/sh
####################
# My service routing
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.1.z
fi
# If no prerouting rule exist for my service
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
fi
# If no forward rule exist for my service
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 2 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
@ -438,13 +438,13 @@ Once you have confirmed that the counters increase, store these command in ``/rw
#############
# In Qubes R4
# If not already present
if nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept
fi
@ -455,7 +455,7 @@ For the following example, we use the fact that the physical interface of sys-fi
In the sys-firewall VM’s Terminal, code a natting firewall rule to route traffic on its outside interface for the service to the qube
.. code:: bash
.. code:: console
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j DNAT --to-destination 10.137.0.xx
@ -463,7 +463,7 @@ In the sys-firewall VM’s Terminal, code a natting firewall rule to route traff
Code the appropriate new filtering firewall rule to allow new connections for the service
.. code:: bash
.. code:: console
iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
@ -475,7 +475,7 @@ Code the appropriate new filtering firewall rule to allow new connections for th
.. code:: bash
.. code:: console
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
@ -483,74 +483,74 @@ 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
$ sudo nano /rw/config/qubes-firewall-user-script
.. code:: bash
#!/bin/sh
####################
# My service routing
# Create a new firewall natting chain for my service
if iptables -w -t nat -N MY-HTTPS; then
# Add a natting rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -t nat -A MY-HTTPS -j DNAT --to-destination 10.137.0.xx
fi
# If no prerouting rule exist for my service
if ! iptables -w -t nat -n -L PREROUTING | grep --quiet MY-HTTPS; then
# add a natting rule for the traffic (same reason)
iptables -w -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 10.137.1.z -j MY-HTTPS
fi
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -s 192.168.x.0/24 -j ACCEPT
fi
# If no forward rule exist for my service
if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I FORWARD 4 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi
################
# In Qubes OS R4
# If not already present
if ! nft -nn list table ip qubes-firewall | grep "tcp dport 443 ct state new"; then
# Add a filtering rule
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
fi
Finally make this file executable (so it runs at every Firewall VM update)
.. code:: bash
.. code:: console
sudo chmod +x /rw/config/qubes-firewall-user-script
$ sudo chmod +x /rw/config/qubes-firewall-user-script
@ -560,9 +560,9 @@ 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
$ sudo nano /rw/config/rc.local
@ -570,21 +570,21 @@ Here no routing is required, only filtering. Proceed in the same way as above bu
######################
# My service filtering
# Create a new firewall filtering chain for my service
if iptables -w -N MY-HTTPS; then
# Add a filtering rule if it did not exist (to avoid clutter if script executed multiple times)
iptables -w -A MY-HTTPS -j ACCEPT
fi
# If no input rule exists for my service
if ! iptables -w -n -L INPUT | grep --quiet MY-HTTPS; then
# add a forward rule for the traffic (same reason)
iptables -w -I INPUT 5 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j MY-HTTPS
fi

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

@ -25,15 +25,15 @@ 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
$ sudo qubes-dom0-update google-authenticator
2. Run google authenticator:
.. code:: bash
.. code:: console
google-authenticator
@ -41,14 +41,14 @@ As the name implies, this generates authentication code that is time-dependent.
3. Walk through the setup instructions which will also generate your QR code for your auth app of choice:
.. code:: bash
.. code:: output
Do you want me to update your “/home/user/.google_authenticator” file (y/n) y
Do you want to disallow multiple uses of the same authentication token? This restricts you to one login about every 30s, but it increases your chances to notice or even prevent man-in-the-middle attacks (y/n)
By default, tokens are good for 30 seconds, and to compensate for possible time-skew between the client and the server, we allow an extra token before and after the current time. If you experience problems with poor time synchronization, you can increase the window from its default size of 1:30min to about 4min. Do you want to do so (y/n)
If the computer that you are logging into isn’t hardened against brute-force login attempts, you can enable rate-limiting for the authentication module. By default, this limits attackers to no more than 3 login attempts every 30s. Do you want to enable rate-limiting (y/n)
@ -66,14 +66,14 @@ Now we are going to add the authenticator as a login requirement:
2. Edit the custom system authentication template in ``/etc/authselect/custom/mfa/system-auth``.
Add the following line right after ``auth required pam_faildelay.so delay=2000000``:
.. code:: bash
.. code:: text
auth required pam_google_authenticator.so
After the change, the top of the file should look like this:
.. code:: bash
.. code:: text
{imply "with-smartcard" if "with-smartcard-required"}
auth required pam_env.so
@ -84,9 +84,9 @@ 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
$ sudo authselect select custom/mfa
@ -108,9 +108,9 @@ 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
$ sudo authselect select sssd
@ -168,9 +168,9 @@ All these requirements are described below, step by step, for the YubiKey and Ni
.. code:: bash
.. code:: console
sudo dnf install ykpers
$ sudo dnf install ykpers
@ -178,9 +178,9 @@ All these requirements are described below, step by step, for the YubiKey and Ni
.. code:: bash
.. code:: console
sudo apt-get install yubikey-personalization
$ sudo apt-get install yubikey-personalization
@ -202,9 +202,9 @@ 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
$ 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,9 +289,9 @@ 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 ' '
$ 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,15 +361,15 @@ In dom0:
2. Then make ``/etc/qubes-rpc/custom.LockScreen`` executable.
.. code:: bash
.. code:: console
sudo chmod +x /etc/qubes-rpc/custom.LockScreen
$ sudo chmod +x /etc/qubes-rpc/custom.LockScreen
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,17 +398,17 @@ In your USB VM:
3. Then make ``/rw/config/rc.local`` executable.
.. code:: bash
.. code:: console
sudo chmod +x /rw/config/rc.local
$ sudo chmod +x /rw/config/rc.local
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
$ 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:

20
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,12 +71,12 @@ Restart the client domain.
Export the **public** part of your keys and import them in the client domain. Also import/set proper “ownertrust” values. For example:
.. code:: bash
.. code:: console
gpg-server-vm$ gpg --export > public-keys-export
gpg-server-vm$ gpg --export-ownertrust > ownertrust-export
gpg-server-vm$ qvm-copy public-keys-export ownertrust-export
gpg-client-vm$ gpg --import ~/QubesIncoming/gpg-server-vm/public-keys-export
gpg-client-vm$ gpg --import-ownertrust ~/QubesIncoming/gpg-server-vm/ownertrust-export
@ -84,7 +84,7 @@ Export the **public** part of your keys and import them in the client domain. Al
This should be enough to have it running:
.. code:: bash
.. code:: console
gpg-client-vm$ gpg -K
/home/user/.gnupg/pubring.kbx
@ -140,4 +140,4 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.. |split-gpg-diagram.png| image:: /attachment/doc/split-gpg-diagram.png

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

@ -4,7 +4,7 @@ Split GPG
.. warning::
**Note:** This information concerns split-gpg. The implementation has been updated to provide more features in split-gpg-2. Some incomplete information on split-gpg-2 is available :doc:`here </user/security-in-qubes/split-gpg-2>`.
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the “smart card” is played by another Qubes app qube. This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations – such as encryption/decryption and signing – to another, more trusted, network-isolated domain. This way the compromise of your domain where Thunderbird or another client app is running – arguably a not-so-unthinkable scenario – does not allow the attacker to automatically also steal all your keys. (We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
@ -29,7 +29,7 @@ Configuring Split GPG
In dom0, make sure the ``qubes-gpg-split-dom0`` package is installed.
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-gpg-split-dom0
@ -38,7 +38,7 @@ Make sure you have the ``qubes-gpg-split`` package installed in the template you
For Debian or Whonix:
.. code:: bash
.. code:: console
[user@debian-10 ~]$ sudo apt install qubes-gpg-split
@ -46,7 +46,7 @@ For Debian or Whonix:
For Fedora:
.. code:: bash
.. code:: console
[user@fedora-32 ~]$ sudo dnf install qubes-gpg-split
@ -60,7 +60,7 @@ First, create a dedicated app qube for storing your keys (we will be calling it
Make sure that gpg is installed there. At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later. To check which private keys are in your GPG keyring, use:
.. code:: bash
.. code:: console
[user@work-gpg ~]$ gpg -K
/home/user/.gnupg/secring.gpg
@ -73,7 +73,7 @@ Make sure that gpg is installed there. At this stage you can add the private key
This is pretty much all that is required. However, you might want to modify the default timeout: this tells the backend for how long the user’s approval for key access should be valid. (The default is 5 minutes.) You can change this via the ``QUBES_GPG_AUTOACCEPT`` environment variable. You can override it e.g. in ``~/.profile``:
.. code:: bash
.. code:: console
[user@work-gpg ~]$ echo "export QUBES_GPG_AUTOACCEPT=86400" >> ~/.profile
@ -88,7 +88,7 @@ Configuring the client apps to use Split GPG backend
Normally it should be enough to set the ``QUBES_GPG_DOMAIN`` to the GPG backend domain name and use ``qubes-gpg-client`` in place of ``gpg``, e.g.:
.. code:: bash
.. code:: console
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ gpg -K
@ -99,7 +99,7 @@ Normally it should be enough to set the ``QUBES_GPG_DOMAIN`` to the GPG backend
uid Qubes OS Security Team <security@qubes-os.org>
ssb 4096R/30498E2A 2012-11-15
(...)
[user@work-email ~]$ qubes-gpg-client secret_message.txt.asc
(...)
@ -116,7 +116,7 @@ Advanced Configuration
The ``qubes-gpg-client-wrapper`` script sets the ``QUBES_GPG_DOMAIN`` variable automatically based on the content of the file ``/rw/config/gpg-split-domain``, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
.. code:: bash
.. code:: console
[user@work-email ~]$ sudo bash
[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
@ -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
@ -158,7 +158,7 @@ In ``work-email``, use the Thunderbird config editor (found at the bottom of pre
You need to obtain your key ID which should be **exactly 16 characters**. Enter the command ``qubes-gpg-client-wrapper -K --keyid-format long``:
.. code:: bash
.. code:: console
[user@work-email ~]$ qubes-gpg-client-wrapper -K --keyid-format long
/home/user/.gnupg/pubring.kbx
@ -170,7 +170,7 @@ You need to obtain your key ID which should be **exactly 16 characters**. Enter
.. code:: bash
.. code:: console
[user@work-email ~]$ qubes-gpg-client-wrapper --armor --export 777402E6D301615C > 777402E6D301615C.asc
@ -218,7 +218,7 @@ The Keybase service does not preserve/pass the ``QUBES_GPG_DOMAIN`` environment
The following command will configure Keybase to use ``/usr/bin/qubes-gpg-client-wrapper`` instead of its built-in GPG client:
.. code:: bash
.. code:: console
$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
@ -232,13 +232,13 @@ Using Git with Split GPG
Git can be configured to utilize Split GPG, something useful if you would like to contribute to the Qubes OS Project as every commit is required to be signed. The most basic ``~/.gitconfig`` file enabling Split GPG looks something like this.
.. code:: bash
.. code:: ini
[user]
name = <YOUR_NAME>
email = <YOUR_EMAIL_ADDRESS>
signingKey = <YOUR_KEY_ID>
[gpg]
program = qubes-gpg-client-wrapper
@ -246,7 +246,7 @@ Git can be configured to utilize Split GPG, something useful if you would like t
Your key id is the public id of your signing key, which can be found by running ``qubes-gpg-client --list-keys``. In this instance, the key id is E142F75A6B1B610E0E8F874FB45589245791CACB.
.. code:: bash
.. code:: console
[user@work-email ~]$ qubes-gpg-client --list-keys
/home/user/.gnupg/pubring.kbx
@ -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
@ -276,7 +276,7 @@ Importing public keys
Use ``qubes-gpg-import-key`` in the client app qube to import the key into the GPG backend VM.
.. code:: bash
.. code:: console
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
[user@work-email ~]$ qubes-gpg-import-key ~/Downloads/marmarek.asc
@ -300,8 +300,8 @@ Setup Description
In this example, the following keys are stored in the following locations (see below for definitions of these terms):
.. list-table::
:widths: 10 10
.. list-table::
:widths: 10 10
:align: center
:header-rows: 1
@ -313,7 +313,7 @@ In this example, the following keys are stored in the following locations (see b
- ``work-gpg``
* - ``pub``
- ``work-email``
- ``sec`` (master secret key)
@ -395,50 +395,50 @@ Current limitations
- The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase. It will give an ``Inappropriate ioctl for device`` error. Do not set passphrases for the private keys in the GPG backend domain. Doing so won’t provide any extra security anyway, as explained in the introduction and in `using Split GPG with subkeys <#advanced-using-split-gpg-with-subkeys>`__. If you are generating a new key pair, or if you have a private key that already has a passphrase, you can use ``gpg2 --edit-key <key_id>`` then ``passwd`` to set an empty passphrase. Note that ``pinentry`` might show an error when you try to set an empty passphrase, but it will still make the change. (See `this StackExchange answer <https://unix.stackexchange.com/a/379373>`__ for more information.) **Note:** The error shows only if you **do not** have graphical pinentry installed.
.. [1]
.. [1]
In order to gain access to the ``vault`` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a :ref:`signed, compromised package which is already installed in the template <user/templates/templates:trusting your templates>` upon which the ``vault`` VM is based.
.. |split-gpg-diagram.png| image:: /attachment/doc/split-gpg-diagram.png
.. |r2-split-gpg-1.png| image:: /attachment/doc/r2-split-gpg-1.png
.. |r2-split-gpg-3.png| image:: /attachment/doc/r2-split-gpg-3.png
.. |tb78-1.png| image:: /attachment/doc/tb78-1.png
.. |tb78-2.png| image:: /attachment/doc/tb78-2.png
.. |tb78-3.png| image:: /attachment/doc/tb78-3.png
.. |tb78-4.png| image:: /attachment/doc/tb78-4.png
.. |tb78-5.png| image:: /attachment/doc/tb78-5.png
.. |tb78-6.png| image:: /attachment/doc/tb78-6.png
.. |tb78-7.png| image:: /attachment/doc/tb78-7.png
.. |tb78-8.png| image:: /attachment/doc/tb78-8.png
.. |tb78-9.png| image:: /attachment/doc/tb78-9.png
.. |tb78-10.png| image:: /attachment/doc/tb78-10.png
.. |tb-enigmail-split-gpg-settings-2.png| image:: /attachment/doc/tb-enigmail-split-gpg-settings-2.png
.. |r2-split-gpg-5.png| image:: /attachment/doc/r2-split-gpg-5.png

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

@ -5,10 +5,10 @@ Passwordless root access in qubes
The background to passswordless root access is summarised in this statement, that used to be found at ``/etc/sudoers.d/qubes`` in each qube:
.. code:: bash
.. code:: text
user ALL=(ALL) NOPASSWD: ALL
# WTF?! Have you lost your mind?!
#
# In Qubes VMs there is no point in isolating the root account from

22
user/templates/debian/debian-upgrade.rst
View file

@ -18,7 +18,7 @@ Summary instructions for Debian templates
**Important:** The prompt on each line indicates where each command should be entered: ``dom0``, ``debian-<old>``, or ``debian-<new>``, where ``<old>`` is the Debian version number *from* which you are upgrading, and ``<new>`` is the Debian version number *to* which you are upgrading. The instructions may differ for certain releases. See `release-specific notes <#release-specific-notes>`__ for any instructions specific to your particular release.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
@ -42,14 +42,14 @@ These instructions will show you how to upgrade Debian templates. The same gener
1. Ensure the existing template is not running.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-shutdown debian-<old>
2. Clone the existing template and start a terminal in the new template.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
@ -57,7 +57,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
3. Update your ``apt`` repositories to use the new release’s code name instead of the old release’s code name. (This can be done manually with a text editor, but ``sed`` can be used to automatically update the files.)
.. code:: bash
.. code:: console
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
@ -66,7 +66,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
4. Update the package lists and upgrade. During the process, it may prompt you to overwrite the file ``qubes-r4.list``. You should overwrite this file.
.. code:: bash
.. code:: console
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
@ -76,7 +76,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
5. (Optional) Remove unnecessary packages that were previously installed.
.. code:: bash
.. code:: console
[user@debian-<new> ~]$ sudo apt-get autoremove
@ -84,7 +84,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
6. (Optional) Clean cached packages from ``/var/cache/apt``.
.. code:: bash
.. code:: console
[user@debian-<new> ~]$ sudo apt-get clean
@ -92,7 +92,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
7. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have `reported <https://github.com/QubesOS/qubes-issues/issues/5055>`__ that it makes a difference.)
.. code:: bash
.. code:: console
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
@ -102,7 +102,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
8. Shut down the new template.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-shutdown debian-<new>
@ -111,7 +111,7 @@ These instructions will show you how to upgrade Debian templates. The same gener
10. (Optional) Make the new template the global default.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qubes-prefs --set default_template debian-<new>
@ -140,7 +140,7 @@ Please see `Debian’s Bullseye upgrade instructions <https://www.debian.org/rel
This means that, when upgrading from Buster to Bullseye, an additional ``sed`` command is required:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone debian-10 debian-11
[user@dom0 ~]$ qvm-run -a debian-11 gnome-terminal

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

@ -11,7 +11,7 @@ Installing
To :ref:`install <user/templates/templates:installing>` a specific Debian template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
.. code:: bash
.. code:: console
$ qvm-template install XX
@ -73,11 +73,11 @@ 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
sudo apt upgrade
$ sudo apt-mark hold salt-common salt-ssh
$ sudo apt update
$ sudo apt upgrade

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

@ -7,7 +7,7 @@ How to upgrade a Fedora template in-place
This page is intended for advanced users.
.. DANGER::
**Warning:** This page is intended for advanced users only. Most users seeking to upgrade should instead :ref:`install a new Fedora template <user/templates/fedora/fedora:installing>` . Learn more about the two options :ref:`here <user/templates/fedora/fedora:upgrading>` .
This page provides instructions for performing an in-place upgrade of an installed :doc:`Fedora Template </user/templates/fedora/fedora>`. If you wish to install a new, unmodified Fedora template instead of upgrading a template that is already installed in your system, please see the :doc:`Fedora Template </user/templates/fedora/fedora>` page instead. (:ref:`Learn more about the two options. <user/templates/fedora/fedora:upgrading>`)
@ -18,7 +18,7 @@ Summary instructions for standard Fedora templates
**Note:** The prompt on each line indicates where each command should be entered: ``dom0``, ``fedora-<old>``, or ``fedora-<new>``, where ``<old>`` is the Fedora version number *from* which you are upgrading, and ``<new>`` is the Fedora version number *to* which you are upgrading.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone fedora-<old> fedora-<new>
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
@ -47,14 +47,14 @@ These instructions will show you how to upgrade the standard Fedora template. Th
1. Ensure the existing template is not running.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-shutdown fedora-<old>
2. Clone the existing template and start a terminal in the new template.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone fedora-<old> fedora-<new>
[user@dom0 ~]$ qvm-run -a fedora-<new> gnome-terminal
@ -62,7 +62,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
3. Attempt the upgrade process in the new template.
.. code:: bash
.. code:: console
[user@fedora-<new> ~]$ sudo dnf clean all
[user@fedora-<new> ~]$ sudo dnf --releasever=<new> distro-sync --best --allowerasing
@ -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:: output
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:
@ -86,7 +86,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
- If ``dnf`` reports that you do not have enough free disk space to proceed with the upgrade process, create an empty file in dom0 to use as a cache and attach it to the template as a virtual disk.
.. code:: bash
.. code:: console
[user@dom0 ~]$ truncate -s 5GB /var/tmp/template-upgrade-cache.img
[user@dom0 ~]$ dev=$(sudo losetup -f --show /var/tmp/template-upgrade-cache.img)
@ -94,7 +94,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
Then reattempt the upgrade process, but this time use the virtual disk as a cache.
.. code:: bash
.. code:: console
[user@fedora-<new> ~]$ sudo mkfs.ext4 /dev/xvdi
[user@fedora-<new> ~]$ sudo mount /dev/xvdi /mnt/removable
@ -111,7 +111,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
4. Check that you are on the correct (new) Fedora release. Do this check only after completing the upgrade process. This is *not* a troubleshooting procedure for fixing download issues from the repository. This check simply verifies that your clone has successfully been upgraded.
.. code:: bash
.. code:: console
[user@fedora-<new> ~]$ cat /etc/fedora-release
@ -119,7 +119,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
5. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/templates:important notes>`, but it does not hurt. Some users have `reported <https://github.com/QubesOS/qubes-issues/issues/5055>`__ that it makes a difference.)
.. code:: bash
.. code:: console
[user@fedora-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown fedora-<new>
@ -129,14 +129,14 @@ These instructions will show you how to upgrade the standard Fedora template. Th
6. Shut down the new template.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-shutdown fedora-<new>
7. Remove the cache file, if you created one.
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo losetup -d $dev
[user@dom0 ~]$ rm /var/tmp/template-upgrade-cache.img
@ -144,7 +144,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
8. Set the template-name, which is used by the Qubes updater.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-features fedora-<new> template-name fedora-<new>
@ -153,7 +153,7 @@ These instructions will show you how to upgrade the standard Fedora template. Th
10. (Optional) Make the new template the global default.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qubes-prefs --set default_template fedora-<new>
@ -168,7 +168,7 @@ Summary instructions for Fedora Minimal templates
**Note:** The prompt on each line indicates where each command should be entered: ``dom0``, ``fedora-<old>``, or ``fedora-<new>``, where ``<old>`` is the Fedora version number *from* which you are upgrading, and ``<new>`` is the Fedora version number *to* which you are upgrading.
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-clone fedora-<old>-minimal fedora-<new>-minimal
[user@dom0 ~]$ qvm-run -u root -a fedora-<new>-minimal xterm
@ -206,7 +206,7 @@ Additional information
As mentioned above, you may encounter the following ``dnf`` error:
.. code:: bash
.. code:: output
At least X MB more space needed on the / filesystem.

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

@ -11,7 +11,7 @@ Installing
To :ref:`install <user/templates/templates:installing>` a specific Fedora template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
.. code:: bash
.. code:: console
$ qvm-template install XX

12
user/templates/minimal-templates.rst
View file

@ -44,21 +44,21 @@ Installation
The minimal templates can be installed with the following type of command:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>-minimal
If your desired version is not found, it may still be in :doc:`testing </user/downloading-installing-upgrading/testing>`. You may wish to try again with the testing repository enabled:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>-minimal
If you would like to install a community distribution, try the install command by enabling the community repository:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-<DISTRO_NAME>-<RELEASE_NUMBER>-minimal
@ -71,7 +71,7 @@ Passwordless root
It is an intentional design choice for :doc:`Passwordless Root Access in VMs </user/security-in-qubes/vm-sudo>` to be optional in minimal templates. Since the minimal templates are *minimal*, they are not configured for passwordless root by default. To update or install packages, execute the following command in dom0:
.. code:: bash
.. code:: console
[user@dom0 ~]$ qvm-run -u root <DISTRO_NAME>-<RELEASE_NUMBER>-minimal xterm
@ -102,7 +102,7 @@ Fedora
The following list provides an overview of which packages are needed for which purpose. As usual, the required packages are to be installed in the running template with the following command (replace ``packages`` with a space-delimited list of packages to be installed):
.. code:: bash
.. code:: console
[user@your-new-clone ~]$ sudo dnf install packages
@ -188,7 +188,7 @@ Debian
The following list provides an overview of which packages are needed for which purpose. As usual, the required packages are to be installed in the running template with the following command (replace ``packages`` with a space-delimited list of packages to be installed):
.. code:: bash
.. code:: console
[user@your-new-clone ~]$ sudo apt install packages

22
user/templates/templates.rst
View file

@ -103,7 +103,7 @@ You can manage your templates using the ``Qubes Template Manager``, a GUI tool a
At the command line in dom0, ``qvm-template list --available`` will show available templates. To install a template, use:
.. code:: bash
.. code:: console
$ qvm-template install <template_name>
@ -113,7 +113,7 @@ You can also use ``qvm-template`` to upgrade or reinstall templates.
Repository (repo) definitions are stored in dom0 in ``/etc/qubes/repo-templates`` and associated keys in ``/etc/qubes/repo-templates/keys``. There are additional repos for testing releases and community templates. To temporarily enable any of these repos, use the ``--enablerepo=<repo-name>`` option. E.g. :
.. code:: bash
.. code:: console
$ qvm-template --enablerepo qubes-templates-community install <template_name>
@ -164,7 +164,7 @@ To remove a template, the graphical ``Qube Manager`` (Qubes Menu > Qubes Tools >
Alternatively, to remove a template via the command line in dom0:
.. code:: bash
.. code:: console
$ qvm-template remove <TEMPLATE_NAME>
@ -172,7 +172,7 @@ Alternatively, to remove a template via the command line in dom0:
<TEMPLATE_NAME> is the first column from the output of:
.. code:: bash
.. code:: console
$ qvm-template list --installed
@ -204,16 +204,16 @@ When you install a new template or :ref:`upgrade <user/how-to-guides/how-to-upda
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>
$ 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
$ qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb
@ -239,8 +239,8 @@ Whenever an app qube is created, the contents of the ``/home`` directory of its
Once an app qube has been created, any changes in its ``/home``, ``/usr/local``, or ``/rw/config`` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the app qube. No changes in any other directories in app qubes persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent template.
.. list-table::
:widths: 44 44 44
.. list-table::
:widths: 44 44 44
:align: center
:header-rows: 1
@ -256,7 +256,7 @@ Once an app qube has been created, any changes in its ``/home``, ``/usr/local``,
* - :ref:`disposable <user/reference/glossary:disposable>`
- ``/rw`` (includes ``/home``, ``/usr/local``, and ``bind-dirs``)
- nothing
| :superscript:`1` Upon creation
| :superscript:`2` Following shutdown

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

@ -21,8 +21,8 @@ Qubes Windows Tools are a set of programs and drivers that provide integration o
Below is a breakdown of the feature availability depending on the windows version:
.. list-table::
:widths: 39 39 39
.. list-table::
:widths: 39 39 39
:align: center
:header-rows: 1
@ -59,7 +59,7 @@ Below is a breakdown of the feature availability depending on the windows versio
* - Audio
- n
- n
Qubes Windows Tools are open source and are distributed under a GPL license.
@ -102,7 +102,7 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
6. Check the integrity of the file ``qubes-tools-4.0.1.3.exe``by comparing its hash checksum. This can be done using the Windows command ``certutil`` on the windows command prompt (``cmd.exe``) and specifying an appropriate hash algorithm like:
.. code:: bash
.. code:: doscon
certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256
@ -120,10 +120,10 @@ 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
$ qvm-features <VMname> gui 1
$ qvm-prefs <VMname> qrexec_timeout 300
@ -133,9 +133,9 @@ 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>
$ qvm-prefs <VMname> default_user <username>
@ -157,9 +157,9 @@ 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
$ sudo qubes-dom0-update qubes-windows-tools
@ -167,9 +167,9 @@ 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
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
@ -189,9 +189,9 @@ 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
$ qvm-start lab-win7 --install-windows-tools
@ -201,17 +201,17 @@ 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>
$ qvm-prefs <your-appvm-name>
**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
$ qvm-prefs <vm-name> qrexec_timeout 300
@ -245,9 +245,9 @@ 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
$ qvm-prefs -s win7new debug false
@ -259,9 +259,9 @@ 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
$ qvm-run -a my-win7-appvm explorer.exe
@ -269,13 +269,13 @@ Once you start a Windows-based AppVM with Qubes Tools installed, you can easily
Also, the inter-VM services work as usual – e.g. to request opening a document or URL in the Windows AppVM from another VM:
.. code:: bash
.. code:: console
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
.. code:: bash
.. code:: console
[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com
@ -303,9 +303,9 @@ 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
$ qvm-create --class TemplateVM win-template --property virt_mode=HVM --property kernel='' -l green
@ -333,9 +333,9 @@ 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>
$ qvm-create --property virt_mode=hvm <new windows appvm name> --template <name of template vm> --label <label color>
@ -389,8 +389,8 @@ Configuration
Starting from version 2.2.* various aspects of Qubes Windows Tools can be configured through registry. Main configuration key is located in ``HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools``. Configuration values set on this level are global to all QWT components. It’s possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
.. list-table::
:widths: 14 14 14 14
.. list-table::
:widths: 14 14 14 14
:align: center
:header-rows: 1
@ -410,13 +410,13 @@ Starting from version 2.2.* various aspects of Qubes Windows Tools can be config
- DWORD
- Maximum age of log files (in seconds), older logs are automatically deleted
- 604800 (7 days)
Possible log levels:
.. list-table::
:widths: 11 11 11
.. list-table::
:widths: 11 11 11
:align: center
:header-rows: 1
@ -438,7 +438,7 @@ Possible log levels:
* - 5
- Verbose
- Trace most function calls
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
@ -449,8 +449,8 @@ To override global settings for a specific component, create a new key under the
Component-specific settings currently available:
.. list-table::
:widths: 11 11 11 11 11
.. list-table::
:widths: 11 11 11 11 11
:align: center
:header-rows: 1
@ -464,7 +464,7 @@ Component-specific settings currently available:
- DWORD
- Disable cursor in the VM. Useful for integration with Qubes desktop so you don’t see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).
- 1
Troubleshooting
@ -485,8 +485,8 @@ Safe Mode should at least give you access to logs (see above).
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
.. list-table::
:widths: 18 18
.. list-table::
:widths: 18 18
:align: center
:header-rows: 1
@ -524,13 +524,13 @@ When we publish new QWT version, it’s usually pushed to the ``current-testing`
That command will download a new QWT .iso from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.
.. |windows-seamless-4.png| image:: /attachment/doc/windows-seamless-4.png
.. |windows-seamless-1.png| image:: /attachment/doc/windows-seamless-1.png
.. |windows-seamless-7.png| image:: /attachment/doc/windows-seamless-7.png
.. |qtw-log-level.png| image:: /attachment/doc/qtw-log-level.png

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

@ -37,17 +37,17 @@ 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
$ sudo qubes-dom0-update qubes-windows-tools-4.1.68
for Qubes R4.1.2, or
.. code:: bash
.. code:: console
sudo qubes-dom0-update qubes-windows-tools-4.1.69
$ sudo qubes-dom0-update qubes-windows-tools-4.1.69
@ -63,8 +63,8 @@ If you prefer to download the corresponding .rpm files for manual QWT installati
Below is a breakdown of the feature availability depending on the windows version:
.. list-table::
:widths: 38 38 38
.. list-table::
:widths: 38 38 38
:align: center
:header-rows: 1
@ -101,7 +101,7 @@ Below is a breakdown of the feature availability depending on the windows versio
* - Audio
- y
- y
Qubes Windows Tools are open source and are distributed under a GPL license.
@ -136,7 +136,7 @@ The Xen PV Drivers bundled with QWT are signed by a Linux Foundation certificate
**Warning:** it is recommended to increase the default value of Windows VM’s ``qrexec_timeout`` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM’s virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when ``qrexec`` is not yet running, so timeout may occur with the default value. To change the property use this command in ``dom0``: *(where* ``<VMname>`` *is the name of your Windows VM)*
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-prefs <VMname> qrexec_timeout 7200
@ -160,31 +160,31 @@ 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
$ sudo qubes-dom0-update qubes-windows-tools
(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
$ 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
$ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing --action=upgrade qubes-windows-tools
This package brings the ISO with Qubes Windows Tools that is passed to the VM when ``--install-windows-tools`` is specified for the ``qvm-start`` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
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,9 +193,9 @@ 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
$ qvm-start <VMname> --install-windows-tools
Once the Windows VM boots, a CDROM should appear in the ‘My Computer’ menu (typically as ``D:`` or ``E:``) with the setup program ``qubes-tools-x64.msi`` in its main directory.
@ -215,14 +215,14 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as ``qrexec_installed``, ``guiagent_installed``, and ``default_user``. This can be verified (but is not required) using the ``qvm-prefs`` command *(where* ``<VMname>`` *is the name of your Windows VM)*:
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-prefs <VMname>
It is advisable to set some other parameters in order to enable audio and USB block device access, synchronize the Windows clock with the Qubes clock, and so on:
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-features <VMname> audio-model ich9
[user@dom0 ~] $ qvm-features <VMname> stubdom-qrexec 1
@ -231,7 +231,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa
For audio, the parameter ``audio-model`` can be selected as ``ich6`` or ``ich9``; select the value that gives the best audio quality. Audio quality may also be improved by setting the following parameters, but this can depend on the Windows version and on your hardware:
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-features <VMname> timer-period 1000
[user@dom0 ~] $ qvm-features <VMname> out.latency 10000
@ -295,7 +295,7 @@ Using Windows AppVMs in seamless mode
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the ``-a`` switch used here, which will auto-start the VM if it is not running):
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-run -a my-win-appvm explorer.exe
@ -305,10 +305,10 @@ Once you start a Windows-based AppVM with Qubes Tools installed, you can easily
Also, the inter-VM services work as usual – e.g. to request opening a document or URL in the Windows AppVM from another VM:
.. code:: bash
.. code:: console
[user@dom0 ~] $ qvm-open-in-vm my-win-appvm roadmap.pptx
[user@dom0 ~]$ qvm-open-in-vm my-win-appvm https://invisiblethingslab.com
@ -418,8 +418,8 @@ Configuration
Various aspects of Qubes Windows Tools (QWT) can be configured through the registry. The main configuration key is located in ``HKEY_LOCAL_MACHINE\SOFTWARE\Invisible Things Lab\Qubes Tools``. Configuration values set on this level are global to all QWT components. It’s possible to override global values with component-specific keys, this is useful mainly for setting log verbosity for troubleshooting. Possible configuration values are:
.. list-table::
:widths: 14 14 14 14
.. list-table::
:widths: 14 14 14 14
:align: center
:header-rows: 1
@ -439,13 +439,13 @@ Various aspects of Qubes Windows Tools (QWT) can be configured through the regis
- DWORD
- Maximum age of log files (in seconds), older logs are automatically deleted
- 604800 (7 days)
Possible log levels:
.. list-table::
:widths: 11 11 11
.. list-table::
:widths: 11 11 11
:align: center
:header-rows: 1
@ -467,7 +467,7 @@ Possible log levels:
* - 5
- Verbose
- Trace most function calls
Debug and Verbose levels can generate large volume of logs and are intended for development/troubleshooting only.
@ -476,8 +476,8 @@ To override global settings for a specific component, create a new key under the
Component-specific settings currently available:
.. list-table::
:widths: 11 11 11 11 11
.. list-table::
:widths: 11 11 11 11 11
:align: center
:header-rows: 1
@ -491,7 +491,7 @@ Component-specific settings currently available:
- DWORD
- Disable cursor in the VM. Useful for integration with Qubes desktop so you don’t see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).
- 1
Troubleshooting
@ -514,8 +514,8 @@ Xen logs in dom0 (``/var/log/xen/console/guest-*``) are also useful as they cont
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
.. list-table::
:widths: 32 32
.. list-table::
:widths: 32 32
:align: center
:header-rows: 1
@ -554,7 +554,7 @@ Updates
When we publish a new QWT version, it’s usually pushed to the ``current-testing`` or ``unstable`` repository first. To use versions from current-testing, run this in dom0:
.. code:: bash
.. code:: console
[user@dom0 ~] $ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
@ -563,22 +563,22 @@ When we publish a new QWT version, it’s usually pushed to the ``current-testin
That command will download a new QWT ``iso`` file from the testing repository. It goes without saying that you should **backup your VMs** before installing anything from testing repos.
.. |QWT_install_select| image:: /attachment/doc/QWT_install_select.png
.. |QWT_install_driver| image:: /attachment/doc/QWT_install_driver.png
.. |QWT_install_no_restart| image:: /attachment/doc/QWT_install_no_restart.png
.. |windows-seamless-4.png| image:: /attachment/doc/windows-seamless-4.png
.. |windows-seamless-1.png| image:: /attachment/doc/windows-seamless-1.png
.. |windows-seamless-7.png| image:: /attachment/doc/windows-seamless-7.png
.. |QWT_no_PV_network| image:: /attachment/doc/QWT_no_PV_network.png

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

@ -125,10 +125,10 @@ 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
$ qvm-features VMNAME linux-stubdom ''
$ qvm-prefs VMNAME virt_mode hvm
@ -147,26 +147,40 @@ An unofficial, third-party tool for automating this process is available `here <
Summary
^^^^^^^
.. code:: console
.. code:: bash
$ qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
$ qvm-prefs win7new memory 4096
$ qvm-prefs win7new maxmem 4096
$ qvm-prefs win7new kernel ''
$ qvm-volume extend win7new:root 25g
$ qvm-prefs win7new debug true
$ qvm-features win7new video-model cirrus
$ qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
qvm-prefs win7new kernel ''
qvm-volume extend win7new:root 25g
qvm-prefs win7new debug true
qvm-features win7new video-model cirrus
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start win7new
# once Windows is installed and working
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
qvm-features --unset win7new video-model
qvm-prefs win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs win7new debug false
Restart after the first part of the windows installation process ends:
.. code:: console
$ qvm-start win7new
Once Windows is installed and working:
.. code:: console
$ qvm-prefs win7new memory 2048
$ qvm-prefs win7new maxmem 2048
$ qvm-features --unset win7new video-model
$ qvm-prefs win7new qrexec_timeout 300
With Qubes Windows Tools installed:
.. code:: console
$ qvm-prefs win7new debug false
@ -188,9 +202,9 @@ 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
$ qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
@ -198,7 +212,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
@ -208,40 +222,40 @@ 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
$ qvm-prefs win7new memory 4096
$ qvm-prefs win7new maxmem 4096
Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence:
.. code:: bash
.. code:: console
qvm-prefs win7new kernel ''
$ qvm-prefs win7new kernel ''
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
$ qvm-volume extend win7new:root 25g
Set the debug flag in order to have a graphical console:
.. code:: bash
.. code:: console
qvm-prefs win7new debug true
$ qvm-prefs win7new debug true
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.
@ -249,17 +263,17 @@ 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
$ qvm-features win7new video-model 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
$ qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
@ -267,7 +281,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 \
@ -281,26 +295,26 @@ 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
$ qvm-prefs win7new memory 2048
$ qvm-prefs win7new maxmem 2048
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
$ qvm-features --unset win7new video-model
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
$ qvm-prefs win7new qrexec_timeout 300
@ -312,9 +326,9 @@ 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
$ qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template
@ -330,9 +344,9 @@ 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>
$ qvm-create --class=AppVM --template=<VMname>

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

@ -130,16 +130,16 @@ 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
$ 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
$ qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew
@ -147,13 +147,13 @@ 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
qvm-prefs WindowsNew maxmem 4096
qvm-prefs WindowsNew kernel ''
qvm-prefs WindowsNew qrexec_timeout 7200
$ qvm-volume extend WindowsNew:root 60g
$ qvm-prefs WindowsNew memory 4096
$ qvm-prefs WindowsNew maxmem 4096
$ qvm-prefs WindowsNew kernel ''
$ qvm-prefs WindowsNew qrexec_timeout 7200
@ -167,10 +167,10 @@ 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:: output
/var/log/xen/console/hypervisor.log:
p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
(XEN) domain_crash called from p2m-pod.c:1218
(XEN) Domain 120 (vcpu#0) crashed on cpu#3:
@ -182,9 +182,9 @@ 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
$ qvm-prefs WindowsNew qrexec_timeout 7200
@ -213,9 +213,9 @@ 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
$ qvm-start --cdrom=untrusted:/home/user/windows_install.iso WindowsNew
@ -244,7 +244,7 @@ These parameters are set for the following reasons:
- You will then return to the setup, which will continue normally and install Windows 11 without TPM 2.0.
.. warning::
Caution: This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
- The installation of Windows 11 may require an internet connection to grab a Microsoft ID. Previously, this was true only for the home edition, but since version 24H2, it extends to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that works for version 21H2 but may be blocked for newer versions:
@ -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:: console
tailf /var/log/qubes/vm-WindowsNew.log \
/var/log/xen/console/hypervisor.log \
@ -394,9 +394,9 @@ 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>
$ qvm-create --class=AppVM --template=<VMname>
@ -406,9 +406,9 @@ 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
$ qvm-prefs WindowsNew ip 10.137.0.x

8
user/templates/xfce-templates.rst
View file

@ -13,28 +13,28 @@ Installation
The Fedora Xfce templates can be installed with the following command (where ``X`` is your desired distro and version number):
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
If your desired version is not found, it may still be in :doc:`testing </user/downloading-installing-upgrading/testing>`. You may wish to try again with the testing repository enabled:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl-testing qubes-template-X-xfce
If you would like to install a community distribution such as Gentoo, try the install command by enabling the community repository:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-X-xfce
If your desired version is not found, it may still be in :doc:`testing </user/downloading-installing-upgrading/testing>`. You may wish to try again with the testing repository enabled:
.. code:: bash
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community-testing qubes-template-X-xfce

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

@ -27,7 +27,7 @@ With the command-line interface
To update the list of available applications, use the ``qvm-sync-appmenus`` command in dom0, replacing ``<QUBE_NAME>`` by the qube name:
.. code:: bash
.. code:: console
$ qvm-sync-appmenus <QUBE_NAME>
@ -35,7 +35,7 @@ To update the list of available applications, use the ``qvm-sync-appmenus`` comm
When using the *Refresh Applications* button in a qube’s settings, the command ``qvm-sync-appmenus`` is used at least one time. When refreshing an AppVM application, it is also run against the template. So the console equivalent of clicking the *Refresh button* is the following (always in dom0):
.. code:: bash
.. code:: console
$ qvm-sync-appmenus <APPVM_NAME>
$ qvm-sync-appmenus <TEMPLATE_NAME>
@ -44,7 +44,7 @@ When using the *Refresh Applications* button in a qube’s settings, the command
In dom0, the ``qvm-appmenus`` tool allows the user to see the list of available applications (unstable feature), the whitelist of currently show application (unstable feature) and to change this list:
.. code:: bash
.. code:: console
$ qvm-appmenus --set-whitelist <FILE_PATH> <QUBE_NAME>
@ -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:: text
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>
@ -152,7 +152,7 @@ What if a removed application is still in the app menu?
First, try this in dom0:
.. code:: bash
.. code:: console
$ qvm-appmenus --update --force <QUBE_NAME>
@ -160,7 +160,7 @@ First, try this in dom0:
You can also try:
.. code:: bash
.. code:: console
$ qvm-appmenus --remove <QUBE_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>
@ -186,7 +186,7 @@ The line starting with ``Exec=`` points out the exact command run by dom0 to sta
It’s possible to run the command to check the output, by copying this line without ``Exec=``, and remove ``-q`` (quiet option). But it could be more useful to run it in the qube, with the ``qubes.StartApp`` service:
.. code:: bash
.. code:: console
$ /etc/qubes-rpc/qubes.StartApp <APPLICATION_NAME>
@ -206,18 +206,18 @@ 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
$ qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox
$ qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager
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
$ qvm-run -q -a --service -- personal qubes.StartApp+firefox
@ -226,7 +226,7 @@ While this works well for standard applications, creating a menu entry for Windo
**Note:** Applications installed under *wine* are installed in AppVMs, not in the template on which these AppVMs are based, as the file structure used by *wine* is stored under ``~/.wine``, which is part of the persistent data of the AppVM and not inherited from its template.
.. |image1| image:: /attachment/doc/r4.0-dom0-menu.png
.. |image2| image:: /attachment/doc/r4.0-dom0-appmenu-select.png

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

@ -15,22 +15,22 @@ 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
$ sudo apt-get update && sudo apt-get dist-upgrade
However, if you see something like the following, then something went wrong.
.. code:: bash
.. code:: output
W: Failed to fetch http://ftp.us.debian.org/debian/dist/jessie/contrib/binary-i386/Packages 404 Not Found
W: Failed to fetch http://ftp.us.debian.org/debian/dist/jessie/non-free/binary-i386/Packages 404 Not Found
E: Some index files failed to download. They have been ignored, or old ones used instead.
Err http://ftp.us.debian.org jessie Release.gpg
Could not resolve 'ftp.us.debian.org'
Err http://deb.torproject.org jessie Release.gpg
@ -39,11 +39,11 @@ However, if you see something like the following, then something went wrong.
Could not resolve 'security.debian.org'
Reading package lists... Done
W: Failed to fetch http://security.debian.org/dists/jessie/updates/Release.gpg Could not resolve 'security.debian.org'
W: Failed to fetch http://ftp.us.debian.org/debian/dists/jessie/Release.gpg Could not resolve 'ftp.us.debian.org'
W: Failed to fetch http://deb.torproject.org/torproject.org/dists/jessie/Release.gpg Could not resolve 'deb.torproject.org'
W: Some index files failed to download. They have been ignored, or old ones used instead.
@ -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:: output
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,9 +76,9 @@ 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
$ 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:: output
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:: text
.. code:: output
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,10 +120,10 @@ In past various apt repositories were signed with expired key: `The Tor Project
You saw the following warning:
.. code:: text
.. code:: output
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
W: Failed to fetch http://deb.torproject.org/torproject.org/dists/stable/Release
W: Some index files failed to download. They have been ignored, or old ones used instead.
@ -139,7 +139,7 @@ Changed Configuration Files
If you see something like the following.
.. code:: text
.. code:: output
Setting up ifupdown ...
Configuration file /etc/network/interfaces

30
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:: output
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,26 +28,26 @@ 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
$ sudo dnf clean all
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>
$ qvm-remove <VMname>
With this method, you lose the data of one VM, but it’ll work more reliably.
3. Decrease the filesystem safety margin (5% by default).
.. code:: bash
.. code:: console
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
$ sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
@ -67,7 +67,7 @@ The above steps applies to old VM disks format. These steps may work on Qubes 4.
For example:
.. code:: bash
.. code:: console
$ sudo lvs
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
@ -96,10 +96,10 @@ 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>
$ qvm-start <VMname>
$ qvm-console-dispvm <VMname>
@ -115,9 +115,9 @@ 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
$ 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

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

@ -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,17 +54,17 @@ 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>
$ qvm-start <VMname> # Make sure the VM is started
$ qvm-console-dispvm <VMname>
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
$ systemctl status -l qubes-gui-agent
@ -78,10 +78,10 @@ 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"
$ previous_kernel_parameters=$(qvm-prefs --get <VMname> kernelopts) # Get current kernel parameters
$ qvm-prefs --set <VMname> kernelopts "<previous_kernel_parameters> audit=0"
Then, restart your VM.

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

@ -9,9 +9,9 @@ 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
$ sudo qubes-dom0-update kernel-latest

16
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:: output
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,9 +75,9 @@ 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 ""
$ qvm-prefs <HVMname> kernel ""
HVM crashes when booting from ISO
@ -90,9 +90,9 @@ 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
$ qvm-prefs <HVMname> memory 2000
Attached devices in Windows HVM stop working on suspend/resume

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

@ -31,7 +31,7 @@ There are a variety of other problems that could arise when using a USB installa
This error message is related to the faulty creation of the USB installation medium. If you receive this error message during installation, please make sure you have followed the instructions on :ref:`how to write your ISO to a USB key <user/downloading-installing-upgrading/installation-guide:copying the iso onto the installation medium>`. Specifically, the ``dd`` command listed on that page has been verified to solve this issue on multiple Qubes installation versions.
.. code:: bash
.. code:: console
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
@ -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

22
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:: output
0000:03:00.0 Audio device: Intel Corporation Haswell-ULT HD Audio Controller (rev 0b)
@ -64,33 +64,33 @@ 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:: output
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
$ sudo su
$ echo -n "1" > /sys/bus/pci/devices/0000:03:00.0/remove
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
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo -n "1" > /sys/bus/pci/devices/0000:03:00.0/remove'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
@ -107,9 +107,9 @@ 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>
$ qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>

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

@ -21,7 +21,7 @@ First, determine which kernel module corresponds to your wireless card. There ar
The easiest is via the output of ``lspci -k`` in your sys-net VM:
.. code:: bash
.. code:: console
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
@ -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:: output
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
@ -64,7 +64,7 @@ You can check which drivers are currently loaded with ``lsmod``, and view detail
For example, we list what modules we have loaded:
.. code:: bash
.. code:: console
[user@sys-net ~]$ lsmod
Module Size Used by
@ -78,7 +78,7 @@ For example, we list what modules we have loaded:
and check one:
.. code:: bash
.. code:: console
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
@ -91,7 +91,7 @@ Hey, it’s our wireless driver!
Now, check if reloading the module makes wireless work again:
.. code:: bash
.. code:: console
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
@ -102,7 +102,7 @@ and try reconnecting to a network that is known to work.
If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi:
.. code:: bash
.. code:: console
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
@ -111,7 +111,7 @@ If that is successful, see below about having Qubes automatically reload the dri
.. code:: bash
.. code:: console
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
@ -128,7 +128,7 @@ If reloading the driver (which resets the hardware into a known-state) resolves
In the above example, it would look like this:
.. code:: bash
.. code:: console
[user@sys-net config]$ cat /rw/config/suspend-module-blacklist
# You can list here modules you want to be unloaded before going to sleep. This

12
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
@ -102,7 +102,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
@ -145,9 +145,9 @@ 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
$ cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi
@ -165,7 +165,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

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

@ -41,9 +41,9 @@ 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
$ 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:: output
(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:: output
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
@ -72,17 +72,17 @@ 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>
$ qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0:<BDF>
- In Qubes R3.x, by modifying the VM’s properties:
.. code:: bash
.. code:: console
qvm-prefs usbVM -s pci_strictreset false
$ qvm-prefs usbVM -s pci_strictreset false

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

@ -33,7 +33,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
1. Check the state of ``installed_by_rpm``
.. code:: bash
.. code:: console
$ qvm-prefs template-vm-name
@ -41,7 +41,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
2. If ``installed_by_rpm - True``, mark the template as not installed by package manager
.. code:: bash
.. code:: console
$ qvm-prefs template-vm-name installed_by_rpm false
@ -53,7 +53,7 @@ When a template is marked as ‘installed by package manager’, but cannot be u
- If ``installed_by_rpm - False``, remove the template like you would a regular qube:
.. code:: bash
.. code:: console
$ qvm-remove template-vm-name
@ -95,7 +95,7 @@ If the error occurs as a result of too little initial memory, increase the initi
For example:
.. code:: text
.. code:: console
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
Using sys-whonix as UpdateVM to download updates for Dom0; this may take some time...

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

@ -9,9 +9,9 @@ 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
$ 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:: output
Failed to execute child process “dbus-launch” (No such file or directory)
@ -53,9 +53,9 @@ 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
$ sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
You should see the ``info`` message appear on the top of your screen. If that is the case then ``notify-send`` is not the issue. If it is not, and you have an error of some sort you can: