Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-07-29 17:49:11 -04:00
Code Issues Projects Releases Packages Wiki Activity

Convert to RST

Browse source 
This is done using tools at
https://github.com/maiska/qubes-translation-utilz, commit
4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
This commit is contained in:
Marek Marczykowski-Górecki 2025-07-04 14:23:09 +02:00
parent e3db139fe3
commit 7e464d0f40
No known key found for this signature in database
GPG key ID: F32894BE9684938A
428 changed files with 32833 additions and 29703 deletions
Download patch file Download diff file Expand all files Collapse all files

185
user/troubleshooting/app-menu-shortcut-troubleshooting.md
View file

@ -1,185 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/app-menu-shortcut-troubleshooting/
redirect_from:
- /doc/managing-appvm-shortcuts/
- /en/doc/managing-appvm-shortcuts/
- /doc/ManagingAppVmShortcuts/
- /wiki/ManagingAppVmShortcuts/
ref: 202
title: App menu shortcut troubleshooting
---
For ease of use Qubes aggregates shortcuts to applications that are installed in app qubes and shows them in one application menu (aka "app menu" or "start menu") in dom0.
Clicking on such shortcut runs the assigned application in its app qube.
[![](/attachment/doc/r4.0-dom0-menu.png)](/attachment/doc/r4.0-dom0-menu.png)
## How-to add a shortcut
### With the graphical user interface
To make applications newly installed show up in the menu, you can use the qube's *Settings*. Under the *Applications* tab, use the *Refresh Applications* button. Linux qubes do this automatically, if the *Settings* are opened after the installation of the package.
[![](/attachment/doc/r4.0-dom0-appmenu-select.png)](/attachment/doc/r4.0-dom0-appmenu-select.png)
After that, use the directional buttons (`>`, `>>`, `<` or `<<`) to customize which applications are shown, by moving them to the *Applications shown in App Menu* part (on the right side). Use the *Apply* (or *Ok*) button to see the changes in the app menu.
### 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:
```
$ qvm-sync-appmenus <QUBE_NAME>
```
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):
```
$ qvm-sync-appmenus <APPVM_NAME>
$ qvm-sync-appmenus <TEMPLATE_NAME>
```
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:
```
$ qvm-appmenus --set-whitelist <FILE_PATH> <QUBE_NAME>
```
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:
```
qubes-open-file-manager.desktop
qubes-run-terminal.desktop
[...]
```
You can replace the file path by a single hyphen (`-`) to read it from standard input.
## What if my application has not been automatically included in the list of available apps?
### Missing desktop entry
Sometimes applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`.
Other times, you may want to make a web shortcut available from the Qubes start menu.
You can manually create new entries in the "available applications" list of shortcuts for all app qubes based on a template.
To do this:
1. Open a terminal window to the template.
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:
```
[Desktop Entry]
Type=Application
Name=VueScan
Exec=vuescan
```
3. Follow the instructions in [How-to add a shortcut](#how-to-add-a-shortcut)
If you only want to create a shortcut for a single app qube:
1. Open a terminal window to the template.
2. Create a custom `.desktop` file in either `~/.local/share/applications` or `/usr/local/share/applications` (you may need to first create the subdirectory). See the previous instructions about the desktop entry format.
3. Follow the instructions in [How-to add a shortcut](#how-to-add-a-shortcut)
To add a custom menu entry instead:
1. Open a terminal window to Dom0.
2. Create a custom `.desktop` file in `~/.local/share/applications`.
Look in the same directory for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
You may use `qvm-run` inside the `.desktop` file; see [Behind the scenes](/doc/app-menu-shortcut-troubleshooting/#behind-the-scenes) for more details.
3. Edit the `~/.config/menus/applications-merged/<vmname>-vm.menu` file for the app qube.
4. Add a custom menu entry referring to your newly created `.desktop` file.
~~~
<Menu>
<Name>Webmail</Name>
<Include>
<Filename>custom.desktop</Filename>
</Include>
</Menu>
~~~
### Unavailable desktop entry
If you created a desktop entry but it doesn't show up, there are some steps to run inside the qube, to identify the problem:
1. make sure the name is a valid name (only ASCII letters, numbers, hyphens and point)
2. if this program is available, run `desktop-file-validate <DESKTOP_FILE_PATH>`
3. run it through `gtk-launch`
4. run `/etc/qubes-rpc/qubes.GetAppmenus` and check that your desktop entry is listed in the output
## What about applications in disposables?
See [Adding programs to the app menu in Disposable customization](/doc/disposable-customization/#adding-programs-to-the-app-menu).
## What if a removed application is still in the app menu?
First, try this in dom0:
```
$ qvm-appmenus --update --force <QUBE_NAME>
```
You can also try:
```
$ qvm-appmenus --remove <QUBE_NAME>
```
If that doesn't work, you can manually modify the files in `~/.local/share/applications/` or in `~/.local/share/qubes-appmenus/<QUBE_NAME>`.
For example, suppose you've deleted `my-old-vm`, but there is a leftover Application Menu shortcut, and you find a related file in `~/.local/share/applications/`, try to delete it. The hyphens in the name of the qube are replaced by an underscore and the letter, so instead of looking for `my-old-vm`, try `my_dold_dvm`.
## What if my application is shown in app menu, but doesn't run anything?
First, check in the corresponding `.desktop` file in `~/.local/share/qubes-appmenus/<QUBE_NAME>/`, inside dom0.
The line starting with `Exec=` points out the exact command run by dom0 to start the application. It should be something like:
```
Exec=qvm-run -q -a --service -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
```
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:
```
$ /etc/qubes-rpc/qubes.StartApp <APPLICATION_NAME>
```
## Behind the scenes
`qvm-sync-appmenus` works by invoking the *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain.
This service enumerates applications installed in that qube and sends formatted info back to dom0 which creates `.desktop` files in the app qube/template directory of dom0.
For Linux qubes the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`.
In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus/<QUBE_NAME>/apps.templates`.
Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<QUBE_NAME>/apps` and in `~/.local/share/applications/`.
The whitelist given to `qvm-appmenu --set-whitelist` is stored as a feature called `menu-items`, where each desktop entry is separated by a space.
Actual command lines for the menu shortcuts involve the `qvm-run` command which starts a process in another domain.
Examples:
```
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.:
```
qvm-run -q -a --service -- personal qubes.StartApp+firefox
```
While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed `.desktop` file in the target Linux qube in the directory `~/.local/share/applications/wine/Programs/` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the `qvm-run` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the `.desktop` file accordingly, e.g. by renaming `Microsoft Excel.desktop` to `Excel.desktop`. Refreshing the menu structure will then build working menu entries.
**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.

232
user/troubleshooting/app-menu-shortcut-troubleshooting.rst Normal file
View file

@ -0,0 +1,232 @@
=================================
App menu shortcut troubleshooting
=================================
For ease of use Qubes aggregates shortcuts to applications that are installed in app qubes and shows them in one application menu (aka “app menu” or “start menu”) in dom0. Clicking on such shortcut runs the assigned application in its app qube.
|image1|
How-to add a shortcut
---------------------
With the graphical user interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To make applications newly installed show up in the menu, you can use the qube’s *Settings*. Under the *Applications* tab, use the *Refresh Applications* button. Linux qubes do this automatically, if the *Settings* are opened after the installation of the package.
|image2|
After that, use the directional buttons (``>``, ``>>``, ``<`` or ``<<``) to customize which applications are shown, by moving them to the *Applications shown in App Menu* part (on the right side). Use the *Apply* (or *Ok*) button to see the changes in the app menu.
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
$ qvm-sync-appmenus <QUBE_NAME>
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
$ qvm-sync-appmenus <APPVM_NAME>
$ qvm-sync-appmenus <TEMPLATE_NAME>
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
$ qvm-appmenus --set-whitelist <FILE_PATH> <QUBE_NAME>
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
qubes-open-file-manager.desktop
qubes-run-terminal.desktop
[...]
You can replace the file path by a single hyphen (``-``) to read it from standard input.
What if my application has not been automatically included in the list of available apps?
-----------------------------------------------------------------------------------------
Missing desktop entry
^^^^^^^^^^^^^^^^^^^^^
Sometimes applications may not have included a ``.desktop`` file and may not be detected by ``qvm-sync-appmenus``. Other times, you may want to make a web shortcut available from the Qubes start menu.
You can manually create new entries in the “available applications” list of shortcuts for all app qubes based on a template. To do this:
1. Open a terminal window to the template.
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
[Desktop Entry]
Type=Application
Name=VueScan
Exec=vuescan
3. Follow the instructions in `How-to add a shortcut <#how-to-add-a-shortcut>`__
If you only want to create a shortcut for a single app qube:
1. Open a terminal window to the template.
2. Create a custom ``.desktop`` file in either ``~/.local/share/applications`` or ``/usr/local/share/applications`` (you may need to first create the subdirectory). See the previous instructions about the desktop entry format.
3. Follow the instructions in `How-to add a shortcut <#how-to-add-a-shortcut>`__
To add a custom menu entry instead:
1. Open a terminal window to Dom0.
2. Create a custom ``.desktop`` file in ``~/.local/share/applications``. Look in the same directory for existing examples, or see the full `file specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. You may use ``qvm-run`` inside the ``.desktop`` file; see :ref:`Behind the scenes <user/troubleshooting/app-menu-shortcut-troubleshooting:behind the scenes>` for more details.
3. Edit the ``~/.config/menus/applications-merged/<vmname>-vm.menu`` file for the app qube.
4. Add a custom menu entry referring to your newly created ``.desktop`` file.
.. code:: bash
<Menu>
<Name>Webmail</Name>
<Include>
<Filename>custom.desktop</Filename>
</Include>
</Menu>
Unavailable desktop entry
^^^^^^^^^^^^^^^^^^^^^^^^^
If you created a desktop entry but it doesn’t show up, there are some steps to run inside the qube, to identify the problem:
1. make sure the name is a valid name (only ASCII letters, numbers, hyphens and point)
2. if this program is available, run ``desktop-file-validate <DESKTOP_FILE_PATH>``
3. run it through ``gtk-launch``
4. run ``/etc/qubes-rpc/qubes.GetAppmenus`` and check that your desktop entry is listed in the output
What about applications in disposables?
---------------------------------------
See :ref:`Adding programs to the app menu in Disposable customization <user/advanced-topics/disposable-customization:adding programs to the app menu>`.
What if a removed application is still in the app menu?
-------------------------------------------------------
First, try this in dom0:
.. code:: bash
$ qvm-appmenus --update --force <QUBE_NAME>
You can also try:
.. code:: bash
$ qvm-appmenus --remove <QUBE_NAME>
If that doesn’t work, you can manually modify the files in ``~/.local/share/applications/`` or in ``~/.local/share/qubes-appmenus/<QUBE_NAME>``.
For example, suppose you’ve deleted ``my-old-vm``, but there is a leftover Application Menu shortcut, and you find a related file in ``~/.local/share/applications/``, try to delete it. The hyphens in the name of the qube are replaced by an underscore and the letter, so instead of looking for ``my-old-vm``, try ``my_dold_dvm``.
What if my application is shown in app menu, but doesn't run anything?
----------------------------------------------------------------------
First, check in the corresponding ``.desktop`` file in ``~/.local/share/qubes-appmenus/<QUBE_NAME>/``, inside dom0.
The line starting with ``Exec=`` points out the exact command run by dom0 to start the application. It should be something like:
.. code:: bash
Exec=qvm-run -q -a --service -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
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
$ /etc/qubes-rpc/qubes.StartApp <APPLICATION_NAME>
Behind the scenes
-----------------
``qvm-sync-appmenus`` works by invoking the *GetAppMenus* :doc:`Qubes service </developer/services/qrexec>` in the target domain. This service enumerates applications installed in that qube and sends formatted info back to dom0 which creates ``.desktop`` files in the app qube/template directory of dom0.
For Linux qubes the service script is in ``/etc/qubes-rpc/qubes.GetAppMenus``. In Windows it’s a PowerShell script located in ``c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1`` by default.
The list of installed applications for each app qube is stored in dom0’s ``~/.local/share/qubes-appmenus/<QUBE_NAME>/apps.templates``. Each menu entry is a file that follows the `.desktop file format <https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__ with some wildcards (*%VMNAME%*, *%VMDIR%*). Applications selected to appear in the menu are stored in ``~/.local/share/qubes-appmenus/<QUBE_NAME>/apps`` and in ``~/.local/share/applications/``.
The whitelist given to ``qvm-appmenu --set-whitelist`` is stored as a feature called ``menu-items``, where each desktop entry is separated by a space.
Actual command lines for the menu shortcuts involve the ``qvm-run`` command which starts a process in another domain. Examples:
.. code:: bash
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
qvm-run -q -a --service -- personal qubes.StartApp+firefox
While this works well for standard applications, creating a menu entry for Windows applications running under *wine* may need an additional step in order to establish the necessary environment in *wine*. Installing software under *wine* will create the needed ``.desktop`` file in the target Linux qube in the directory ``~/.local/share/applications/wine/Programs/`` or a subdirectory thereof, depending on the Windows menu structure seen under *wine*. If the name of this file contains spaces, it will not be found, because the ``qvm-run`` command is falsely seen as terminating at this space. The solution is to remove these spaces by renaming the ``.desktop`` file accordingly, e.g. by renaming ``Microsoft Excel.desktop`` to ``Excel.desktop``. Refreshing the menu structure will then build working menu entries.
**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/autostart-troubleshooting.md
View file

@ -1,36 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/autostart-troubleshooting/
title: Autostart troubleshooting
---
The following instructions are valid for **Qubes OS R4.0 legacy mode** and
**Qubes OS R4.1 legacy and UEFI modes**. For **Qubes OS R4.0 in UEFI mode**,
there is no GRUB, so manual boot from another operating system is needed.
In several cases, there is a need to prevent `autostart=True` for qubes on
boot. For example:
* `sys-usb` was enabled, but the only keyboard is attached via USB, and the
`qubes.InputKeyboard` service is disabled.
* A PCI device assigned to an autostarting qube crashes the system (e.g., a GPU
or RAID controller card).
To address this, there is a `qubes.skip_autostart` option for the kernel
command line. You can use it at the grub boot menu.
[![grub1.png](/attachment/doc/grub1.png)](/attachment/doc/grub1.png)
Press the `E` key on the first prompt (or your custom prompt). Then, press the
down arrow key multiple times to reach the line starting with `module2`.
[![grub2.png](/attachment/doc/grub2.png)](/attachment/doc/grub2.png)
Append `qubes.skip_autostart` to the end of this line (generally after the
`rhgb quiet` options).
[![grub3.png](/attachment/doc/grub3.png)](/attachment/doc/grub3.png)
Press `Ctrl+X` to boot with the edited GRUB entry. The boot will proceed as
usual from here, except that no qube will be autostarted.

37
user/troubleshooting/autostart-troubleshooting.rst Normal file
View file

@ -0,0 +1,37 @@
=========================
Autostart troubleshooting
=========================
The following instructions are valid for **Qubes OS R4.0 legacy mode** and **Qubes OS R4.1 legacy and UEFI modes**. For **Qubes OS R4.0 in UEFI mode**, there is no GRUB, so manual boot from another operating system is needed.
In several cases, there is a need to prevent ``autostart=True`` for qubes on boot. For example:
- ``sys-usb`` was enabled, but the only keyboard is attached via USB, and the ``qubes.InputKeyboard`` service is disabled.
- A PCI device assigned to an autostarting qube crashes the system (e.g., a GPU or RAID controller card).
To address this, there is a ``qubes.skip_autostart`` option for the kernel command line. You can use it at the grub boot menu.
|grub1.png|
Press the ``E`` key on the first prompt (or your custom prompt). Then, press the down arrow key multiple times to reach the line starting with ``module2``.
|grub2.png|
Append ``qubes.skip_autostart`` to the end of this line (generally after the ``rhgb quiet`` options).
|grub3.png|
Press ``Ctrl+X`` to boot with the edited GRUB entry. The boot will proceed as usual from here, except that no qube will be autostarted.
.. |grub1.png| image:: /attachment/doc/grub1.png
.. |grub2.png| image:: /attachment/doc/grub2.png
.. |grub3.png| image:: /attachment/doc/grub3.png

138
user/troubleshooting/debian-and-whonix-update-troubleshooting.md
View file

@ -1,138 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/debian-and-whonix-update-troubleshooting/
redirect_from:
- /doc/troubleshooting/updating-debian-and-whonix/
ref: 98
title: Updating Debian and Whonix
---
Despite Qubes shipping with [Debian Templates](/doc/templates/debian/), most of Qubes core components run on Fedora and thus our documentation has better coverage for Fedora. However, Qubes has been working closely with the [Whonix](https://whonix.org) project which is based on Debian.
This troubleshooting guide is collection of tips about updating Whonix that also pertain to updating the normal Debian package manager. If you plan to use Debian heavily, **we highly recommend you install the Whonix templates and use them to update your normal Debian template.**
*Note: some of the links on this page go to documentation on Whonix's website*
### Updating Error Messages
After running the commands to update Debian or Whonix, hopefully everything will complete perfectly.
~~~
sudo apt-get update && sudo apt-get dist-upgrade
~~~
However, if you see something like the following, then something went wrong.
~~~
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
Could not resolve 'deb.torproject.org'
Err http://security.debian.org jessie/updates Release.gpg
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.
~~~
This could be a temporary Tor exit relay or server failure that should fix itself. Here are some simple things to try:
- Check if your network connection is functional
- Try to [change your Tor circuit](https://www.whonix.org/wiki/Arm), then try again
- Running [whonixcheck](https://www.whonix.org/wiki/Whonixcheck) might also help diagnose the problem
Sometimes if you see a message such as:
~~~
Could not resolve 'security.debian.org'
~~~
It helps to run the following command:
~~~
nslookup security.debian.org
~~~
And then trying running the `update` and `upgrade` commands again.
~~~
sudo apt-get update && sudo apt-get dist-upgrade
~~~
*Please note: if you [disabled the Whonix APT Repository](https://www.whonix.org/wiki/Whonix-APT-Repository#Disable_Whonix_APT_Repository) you'll have to manually check for new Whonix releases and [manually install them from source code](https://www.whonix.org/wiki/Dev/Build_Documentation).*
### Never Install Unsigned Packages
If you see something like this:
~~~
WARNING: The following packages cannot be authenticated!
icedove
Install these packages without verification [y/N]?
~~~
Don't proceed! Press `N` and `<enter>`. Running `apt-get update` again should fix it. If not, something is broken or it's a [Man in the middle attack](https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks), which isn't that unlikely, since we are updating over Tor exit relays and some of them are malicious. Try to [change your Tor circuit](https://www.whonix.org/wiki/Arm#Arm).
### Signature Verification Warnings
There should be none at the moment. If there was such a warning, it would look like this:
~~~
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
~~~
Even though, `apt-get` will automatically ignore repositories with expired keys or signatures, you will not receive upgrades from that repository. Unless the issue is already known/documented, it should be reported so it can be further investigated.
There are two possible reasons why this could happen, either there is an issue with the repository that the maintainers have to fix, or you are victim of a [Man-in-the-middle_attacks](https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks). The latter would not be a big issue and might go away after a while automatically or try to [change your Tor circuit](https://www.whonix.org/wiki/Arm#Arm).
In past various apt repositories were signed with expired key: [The Tor Project's apt repository key was expired](https://trac.torproject.org/projects/tor/ticket/12994).
You saw the following warning:
~~~
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.
~~~
It had already been [reported](https://trac.torproject.org/projects/tor/ticket/12994). There was no immediate danger. You could have just ignored it. Just make sure, you never install unsigned packages as explained above.
If you were to see other signature verification errors, those should be reported, but it shouldn't happen at this time.
### Changed Configuration Files
If you see something like the following.
~~~
Setting up ifupdown ...
Configuration file /etc/network/interfaces
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer's version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : background this process to examine the situation
The default action is to keep your current version.
*** interfaces (Y/I/N/O/D/Z) [default=N] ? N
~~~
Be careful. If the updated file isn't coming from Whonix specific package (some are called `whonix-...`), then press `n`. Otherwise anonymity/privacy/security settings deployed with Whonix might get lost. If you are an advanced user and know better, you can of course manually check the difference and merge them.
How could you find out if the file is coming from a Whonix specific package or not?
- Whonix specific packages are sometimes called `whonix-...`. In the example above it's saying `Setting up ifupdown ...`, so the file isn't coming from a Whonix specific package. In this case, you should press `n` as advised in the paragraph above.
- If the package name does include `whonix-...`, it's a Whonix specific package. In that case, your safest bet should be pressing `y`, but then you would lose your customized settings. You can re-add them afterwards. Such conflicts will hopefully rarely happen, if you use [Whonix modular flexible .d style configuration folders](https://www.whonix.org/wiki/Whonix_Configuration_Files).

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

@ -0,0 +1,166 @@
==========================
Updating Debian and Whonix
==========================
Despite Qubes shipping with :doc:`Debian Templates </user/templates/debian/debian>`, most of Qubes core components run on Fedora and thus our documentation has better coverage for Fedora. However, Qubes has been working closely with the `Whonix <https://whonix.org>`__ project which is based on Debian.
This troubleshooting guide is collection of tips about updating Whonix that also pertain to updating the normal Debian package manager. If you plan to use Debian heavily, **we highly recommend you install the Whonix templates and use them to update your normal Debian template.**
**Note: some of the links on this page go to documentation on Whonix’s website**
Updating Error Messages
-----------------------
After running the commands to update Debian or Whonix, hopefully everything will complete perfectly.
.. code:: bash
sudo apt-get update && sudo apt-get dist-upgrade
However, if you see something like the following, then something went wrong.
.. code:: bash
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
Could not resolve 'deb.torproject.org'
Err http://security.debian.org jessie/updates Release.gpg
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.
This could be a temporary Tor exit relay or server failure that should fix itself. Here are some simple things to try:
- Check if your network connection is functional
- Try to `change your Tor circuit <https://www.whonix.org/wiki/Arm>`__, then try again
- Running `whonixcheck <https://www.whonix.org/wiki/Whonixcheck>`__ might also help diagnose the problem
Sometimes if you see a message such as:
.. code:: bash
Could not resolve 'security.debian.org'
It helps to run the following command:
.. code:: bash
nslookup security.debian.org
And then trying running the ``update`` and ``upgrade`` commands again.
.. code:: bash
sudo apt-get update && sudo apt-get dist-upgrade
*Please note: if you* `disabled the Whonix APT Repository <https://www.whonix.org/wiki/Whonix-APT-Repository#Disable_Whonix_APT_Repository>`__ *you’ll have to manually check for new Whonix releases and* `manually install them from source code <https://www.whonix.org/wiki/Dev/Build_Documentation>`__ *.*
Never Install Unsigned Packages
-------------------------------
If you see something like this:
.. code:: bash
WARNING: The following packages cannot be authenticated!
icedove
Install these packages without verification [y/N]?
Don’t proceed! Press ``N`` and ``<enter>``. Running ``apt-get update`` again should fix it. If not, something is broken or it’s a `Man in the middle attack <https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks>`__, which isn’t that unlikely, since we are updating over Tor exit relays and some of them are malicious. Try to `change your Tor circuit <https://www.whonix.org/wiki/Arm#Arm>`__.
Signature Verification Warnings
-------------------------------
There should be none at the moment. If there was such a warning, it would look like this:
.. code:: bash
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
Even though, ``apt-get`` will automatically ignore repositories with expired keys or signatures, you will not receive upgrades from that repository. Unless the issue is already known/documented, it should be reported so it can be further investigated.
There are two possible reasons why this could happen, either there is an issue with the repository that the maintainers have to fix, or you are victim of a `Man-in-the-middle_attacks <https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks>`__. The latter would not be a big issue and might go away after a while automatically or try to `change your Tor circuit <https://www.whonix.org/wiki/Arm#Arm>`__.
In past various apt repositories were signed with expired key: `The Tor Project’s apt repository key was expired <https://trac.torproject.org/projects/tor/ticket/12994>`__.
You saw the following warning:
.. code:: bash
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.
It had already been `reported <https://trac.torproject.org/projects/tor/ticket/12994>`__. There was no immediate danger. You could have just ignored it. Just make sure, you never install unsigned packages as explained above.
If you were to see other signature verification errors, those should be reported, but it shouldn’t happen at this time.
Changed Configuration Files
---------------------------
If you see something like the following.
.. code:: bash
Setting up ifupdown ...
Configuration file /etc/network/interfaces
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer's version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : background this process to examine the situation
The default action is to keep your current version.
*** interfaces (Y/I/N/O/D/Z) [default=N] ? N
Be careful. If the updated file isn’t coming from Whonix specific package (some are called ``whonix-...``), then press ``n``. Otherwise anonymity/privacy/security settings deployed with Whonix might get lost. If you are an advanced user and know better, you can of course manually check the difference and merge them.
How could you find out if the file is coming from a Whonix specific package or not?
- Whonix specific packages are sometimes called ``whonix-...``. In the example above it’s saying ``Setting up ifupdown ...``, so the file isn’t coming from a Whonix specific package. In this case, you should press ``n`` as advised in the paragraph above.
- If the package name does include ``whonix-...``, it’s a Whonix specific package. In that case, your safest bet should be pressing ``y``, but then you would lose your customized settings. You can re-add them afterwards. Such conflicts will hopefully rarely happen, if you use `Whonix modular flexible .d style configuration folders <https://www.whonix.org/wiki/Whonix_Configuration_Files>`__.

145
user/troubleshooting/disk-troubleshooting.md
View file

@ -1,145 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/disk-troubleshooting/
redirect_from:
- /en/doc/out-of-memory/
- /doc/OutOfmemory/
- /wiki/OutOfmemory/
- /doc/out-of-memory/
ref: 231
title: Disk troubleshooting
---
## "Out of disk space" error ##
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:
~~~
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
pool00 qubes_dom0 twi-aotz-- 453.17g 89.95 69.78
root qubes_dom0 Vwi-aotz-- 453.17g pool00 5.87
swap qubes_dom0 -wi-ao---- 7.57g
~~~
If you run `df -h`, it only shows the information in the `root` line (which is already included in the `pool00` line).
As you can see, the `sudo lvs | head` command includes additional important columns `Data%` and `Meta%`, shown in the above example to have the values 89% and 69% respectively.
If your system is able to boot, but cannot load a desktop environment, it is possible to login to dom0 terminal with Alt + Ctrl + F2.
If this does not work, check the size of `/var/lib/qubes/qubes.xml`.
If it is zero, you'll need to use one of the file backup (stored in `/var/lib/qubes/backup`), hopefully you have the current data there.
Find the most recent one and place in `/var/lib/qubes/qubes.xml` instead of the empty file.
In any case you'll need some disk space to start the VM. Check `df -h` output if you have some.
If not, here are some hints how to free some disk space:
1. Clean yum cache.
~~~
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.
~~~
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).
~~~
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
~~~
4. Remove some unneeded files in dom0 home (if you have any, most likely not). Also look for unneeded files in `/var/log` in dom0, and `/var/log/qubes`.
The above steps applies to old VM disks format. These steps may work on Qubes 4.0, but are not default anymore. By default, Qubes 4.0 now uses LVM. The equivalent steps are:
1. Get a list of VM disks using `sudo lvs`.
2. Use `sudo lvremove qubes_dom0/<name>` to remove backup copies of some less important VMs -- entries with `-back` in their name.
3. If that isn't enough, remove actual disks of less important VMs. NOTE: You will lose the data of that VM, but your system will resume working.
For example:
~~~
$ sudo lvs
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
pool00 qubes_dom0 twi-aotz-- 453.17g 89.95 69.78
root qubes_dom0 Vwi-aotz-- 453.17g pool00 5.87
swap qubes_dom0 -wi-ao---- 7.57g
(...)
vm-d10test-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 vm-d10test-private-1600961860-back 29.27
vm-d10test-private-1600961860-back qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.87
vm-d10test-standalone-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 vm-d10test-standalone-private-1580772439-back 4.90
vm-d10test-standalone-private-1580772439-back qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.87
vm-d10test-standalone-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-d10test-standalone-root-1580772439-back 43.37
vm-d10test-standalone-root-1580772439-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 42.05
vm-debian-10-my-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.96
vm-debian-10-my-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-debian-10-my-root-1565013689-back 57.99
vm-debian-10-my-root-1565013689-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 56.55
vm-debian-10-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.94
vm-debian-10-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-debian-10-root-1601126126-back 93.44
vm-debian-10-root-1601126126-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 88.75
(...)
$ sudo lvremove qubes_dom0/vm-d10test-standalone-root-1580772439-back
Do you really want to remove and DISCARD active logical volume qubes_dom0/vm-d10test-standalone-root-1580772439-back? [y/n]: y
Logical volume "vm-d10test-standalone-root-1580772439-back" successfully removed
~~~
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:
~~~
qvm-start <VMname>
qvm-console-dispvm <VMname>
~~~
Since `qvm-console-dispvm` requires working graphical user interface login, you must first free enough space to be able to start a VM and login to graphical UI.
## Can't resize VM storage / "resize2fs: Permission denied" error ##
[Resizing a volume](/doc/resize-disk-image/) in the Qubes interface should be a straightforward process.
But sometimes, an attempt to resize will look like it worked, when it in fact fails silently.
If you then try the same operation in the dom0 console using the `qvm-volume extend` command, it fails with the error message: `resize2fs: Permission denied to resize filesystem`.
This error indicates that a `resize2fs` will not work, unless `fsck` is run first.
Qubes OS utilities cannot yet handle this case.
To fix this issue:
1. In the dom0 terminal get a root console on the vm (eg. sys-usb) with:
~~~
qvm-console-dispvm sys-usb
~~~
2. Unmount everything mounted on the private volume `/dev/xvdb partition`.
There are typically several mounts listed in `/etc/mtab`.
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:
~~~
fuser -m /home
~~~
Kill these process until they are all gone using `kill <process ID>`.
4. Finally, run:
~~~
umount /home
fsck /dev/xvdb
resize2fs /dev/xvdb
~~~
After restarting your VM, everything should now work as expected.
The private volume size shown externally in the VM's settings interface is the same as that seen within the VM.

152
user/troubleshooting/disk-troubleshooting.rst Normal file
View file

@ -0,0 +1,152 @@
====================
Disk troubleshooting
====================
"Out of disk space" error
-------------------------
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
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
pool00 qubes_dom0 twi-aotz-- 453.17g 89.95 69.78
root qubes_dom0 Vwi-aotz-- 453.17g pool00 5.87
swap qubes_dom0 -wi-ao---- 7.57g
If you run ``df -h``, it only shows the information in the ``root`` line (which is already included in the ``pool00`` line). As you can see, the ``sudo lvs | head`` command includes additional important columns ``Data%`` and ``Meta%``, shown in the above example to have the values 89% and 69% respectively.
If your system is able to boot, but cannot load a desktop environment, it is possible to login to dom0 terminal with Alt + Ctrl + F2.
If this does not work, check the size of ``/var/lib/qubes/qubes.xml``. If it is zero, you’ll need to use one of the file backup (stored in ``/var/lib/qubes/backup``), hopefully you have the current data there. Find the most recent one and place in ``/var/lib/qubes/qubes.xml`` instead of the empty file.
In any case you’ll need some disk space to start the VM. Check ``df -h`` output if you have some. If not, here are some hints how to free some disk space:
1. Clean yum cache.
.. code:: bash
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
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
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
4. Remove some unneeded files in dom0 home (if you have any, most likely not). Also look for unneeded files in ``/var/log`` in dom0, and ``/var/log/qubes``.
The above steps applies to old VM disks format. These steps may work on Qubes 4.0, but are not default anymore. By default, Qubes 4.0 now uses LVM. The equivalent steps are:
1. Get a list of VM disks using ``sudo lvs``.
2. Use ``sudo lvremove qubes_dom0/<name>`` to remove backup copies of some less important VMs – entries with ``-back`` in their name.
3. If that isn’t enough, remove actual disks of less important VMs. NOTE: You will lose the data of that VM, but your system will resume working.
For example:
.. code:: bash
$ sudo lvs
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
pool00 qubes_dom0 twi-aotz-- 453.17g 89.95 69.78
root qubes_dom0 Vwi-aotz-- 453.17g pool00 5.87
swap qubes_dom0 -wi-ao---- 7.57g
(...)
vm-d10test-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 vm-d10test-private-1600961860-back 29.27
vm-d10test-private-1600961860-back qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.87
vm-d10test-standalone-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 vm-d10test-standalone-private-1580772439-back 4.90
vm-d10test-standalone-private-1580772439-back qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.87
vm-d10test-standalone-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-d10test-standalone-root-1580772439-back 43.37
vm-d10test-standalone-root-1580772439-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 42.05
vm-debian-10-my-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.96
vm-debian-10-my-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-debian-10-my-root-1565013689-back 57.99
vm-debian-10-my-root-1565013689-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 56.55
vm-debian-10-private qubes_dom0 Vwi-a-tz-- 2.00g pool00 4.94
vm-debian-10-root qubes_dom0 Vwi-a-tz-- 10.00g pool00 vm-debian-10-root-1601126126-back 93.44
vm-debian-10-root-1601126126-back qubes_dom0 Vwi-a-tz-- 10.00g pool00 88.75
(...)
$ sudo lvremove qubes_dom0/vm-d10test-standalone-root-1580772439-back
Do you really want to remove and DISCARD active logical volume qubes_dom0/vm-d10test-standalone-root-1580772439-back? [y/n]: y
Logical volume "vm-d10test-standalone-root-1580772439-back" successfully removed
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
qvm-start <VMname>
qvm-console-dispvm <VMname>
Since ``qvm-console-dispvm`` requires working graphical user interface login, you must first free enough space to be able to start a VM and login to graphical UI.
Can't resize VM storage / "resize2fs: Permission denied" error
--------------------------------------------------------------
:doc:`Resizing a volume </user/advanced-topics/resize-disk-image>` in the Qubes interface should be a straightforward process. But sometimes, an attempt to resize will look like it worked, when it in fact fails silently. If you then try the same operation in the dom0 console using the ``qvm-volume extend`` command, it fails with the error message: ``resize2fs: Permission denied to resize filesystem``. This error indicates that a ``resize2fs`` will not work, unless ``fsck`` is run first. Qubes OS utilities cannot yet handle this case.
To fix this issue:
1. In the dom0 terminal get a root console on the vm (eg. sys-usb) with:
.. code:: bash
qvm-console-dispvm sys-usb
2. Unmount everything mounted on the private volume ``/dev/xvdb partition``. There are typically several mounts listed in ``/etc/mtab``.
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
fuser -m /home
Kill these process until they are all gone using ``kill <process ID>``.
4. Finally, run:
.. code:: bash
umount /home
fsck /dev/xvdb
resize2fs /dev/xvdb
After restarting your VM, everything should now work as expected. The private volume size shown externally in the VM’s settings interface is the same as that seen within the VM.

80
user/troubleshooting/gui-troubleshooting.md
View file

@ -1,80 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/gui-troubleshooting/
ref: 233
title: GUI troubleshooting
---
## Can't click on parts of the screen after connecting high-resolution external display
When you connect a high-resolution external display, you may be unable to click on parts of the screen.
When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM.
This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine.
By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA).
This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a high-resolution display is connected.
If the buffer is too small, and internal desktop resize fails.
To determine if this is the problem affecting you, look at the Xorg log inside the Qube at `/home/user/.local/share/xorg/Xorg.0.log` for lines like the following:
~~~
[ 1623.988] (EE) DUMMYQBS(0): Unable to set up a virtual screen size of 3440x1440 with 17101 Kb of video memory available. Please increase the video memory size.
~~~
The solution to this problem is to increase the minimum size of the video RAM buffer, as explained in [GUI Configuration](/doc/gui-configuration/#video-ram-adjustment-for-high-resolution-displays).
## Screen blanks / Weird computer glitches like turning partially black or black boxes
You may encountering seemingly random screen blanking while using Qubes, where the screen will black and shows the logon screen, yet, only the active window will show when you move the mouse or use the keyboard. Sometimes, you will get random black screens or black boxes.
Similarly, while working, the XScreenSaver dialog may pop up (indicating the screen is locked) and the screen goes black. However, the screen is not locked, and you have to move a window to redraw the screen.
If you are experiencing the any of the above symptoms, try disabling the window compositor:
`Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing”`
## 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:
~~~
[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
~~~
Note that the `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` path applies when running from the installer (either directly after installation, before the reboot, or by starting the installer again in recovery mode). On the actual installed system, the file to edit is `/boot/efi/EFI/qubes/xen.cfg` -- but it may be hard to access directly when your system won't boot.
## 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:
```sh
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:
~~~
systemctl status -l qubes-gui-agent
~~~
If the service is in a failed state, you should see some messages on why it failed.
Another helpful place to look into is `/home/user/.xsession-errors`, which may also contain some hints what is wrong.
### 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:
```sh
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.
Once your troubleshooting is done, don't forget to remove this kernel parameters, it makes troubleshooting VMs not starting easier.

89
user/troubleshooting/gui-troubleshooting.rst Normal file
View file

@ -0,0 +1,89 @@
===================
GUI troubleshooting
===================
Can't click on parts of the screen after connecting high-resolution external display
------------------------------------------------------------------------------------
When you connect a high-resolution external display, you may be unable to click on parts of the screen.
When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM. This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine. By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA). This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a high-resolution display is connected. If the buffer is too small, and internal desktop resize fails.
To determine if this is the problem affecting you, look at the Xorg log inside the Qube at ``/home/user/.local/share/xorg/Xorg.0.log`` for lines like the following:
.. code:: bash
[ 1623.988] (EE) DUMMYQBS(0): Unable to set up a virtual screen size of 3440x1440 with 17101 Kb of video memory available. Please increase the video memory size.
The solution to this problem is to increase the minimum size of the video RAM buffer, as explained in :ref:`GUI Configuration <user/advanced-topics/gui-configuration:video ram adjustment for high-resolution displays>`.
Screen blanks / Weird computer glitches like turning partially black or black boxes
-----------------------------------------------------------------------------------
You may encountering seemingly random screen blanking while using Qubes, where the screen will black and shows the logon screen, yet, only the active window will show when you move the mouse or use the keyboard. Sometimes, you will get random black screens or black boxes.
Similarly, while working, the XScreenSaver dialog may pop up (indicating the screen is locked) and the screen goes black. However, the screen is not locked, and you have to move a window to redraw the screen.
If you are experiencing the any of the above symptoms, try disabling the window compositor:
``Q → System Tools → Window Manager Tweaks → Compositor → uncheck “Enable display compositing”``
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
[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
Note that the ``/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`` path applies when running from the installer (either directly after installation, before the reboot, or by starting the installer again in recovery mode). On the actual installed system, the file to edit is ``/boot/efi/EFI/qubes/xen.cfg`` – but it may be hard to access directly when your system won’t boot.
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
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
systemctl status -l qubes-gui-agent
If the service is in a failed state, you should see some messages on why it failed.
Another helpful place to look into is ``/home/user/.xsession-errors``, which may also contain some hints what is wrong.
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
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.
Once your troubleshooting is done, don’t forget to remove this kernel parameters, it makes troubleshooting VMs not starting easier.

52
user/troubleshooting/hardware-troubleshooting.md
View file

@ -1,52 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/hardware-troubleshooting/
redirect_from:
- /doc/newer-hardware-troubleshooting/
ref: 97
title: Hardware troubleshooting
---
## 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 [here](/doc/how-to-install-software-in-dom0/#kernel-upgrade) for more information about upgrading kernels in dom0).
In dom0:
~~~
sudo qubes-dom0-update kernel-latest
~~~
Reboot when it's done installing.
You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel.
Compare this with the output of `rpm -q kernel`.
If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings.
If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`.
## "Unsupported Hardware Detected" error
See [Installation Troubleshooting](/doc/installation-troubleshooting/#unsupported-hardware-detected-error).
## Keyboard layout settings not behaving correctly
The best approach is to choose the right keyboard layout during the installation process.
But if you want to change things afterwards, you can try this workaround.
Assuming XFCE desktop: in `Q` → `System Tools` → `Keyboard` → `Layout`, leave the checkbox "`Use system defaults`" checked. Do not customize the keyboard layout here.
Set the system-wide layout and options for `xorg` with the `localectl` command in `dom0`. You can use `localectl --help` as a starting point.
Example: `localectl set-x11-keymap us dell ,qwerty compose:caps`.
This generates the appropriate configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`.
This file is auto-generated.
Do not edit it by hand, unless you know what you are doing.
Restarting `xorg` is required.
The most straightforward way is to reboot the system.
More information in [this discussion](https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion) and [this GitHub issue](https://github.com/QubesOS/qubes-issues/issues/1396).

42
user/troubleshooting/hardware-troubleshooting.rst Normal file
View file

@ -0,0 +1,42 @@
========================
Hardware troubleshooting
========================
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
sudo qubes-dom0-update kernel-latest
Reboot when it’s done installing. You can double-check that the boot used the newer kernel with ``uname -r``, which prints the version of the currently-running kernel. Compare this with the output of ``rpm -q kernel``. If the start of ``uname -r`` matches one of the versions printed by ``rpm``, then you’re still using the Linux LTS kernel, and you’ll probably need to manually fix your boot settings. If ``uname -r`` reports a higher version number, then you’ve successfully booted with the kernel shipped by ``kernel-latest``.
"Unsupported Hardware Detected" error
-------------------------------------
See :ref:`Installation Troubleshooting <user/troubleshooting/installation-troubleshooting:"unsupported hardware detected" error>`.
Keyboard layout settings not behaving correctly
-----------------------------------------------
The best approach is to choose the right keyboard layout during the installation process. But if you want to change things afterwards, you can try this workaround.
Assuming XFCE desktop: in ``Q`` → ``System Tools`` → ``Keyboard`` → ``Layout``, leave the checkbox “ ``Use system defaults``” checked. Do not customize the keyboard layout here.
Set the system-wide layout and options for ``xorg`` with the ``localectl`` command in ``dom0``. You can use ``localectl --help`` as a starting point.
Example: ``localectl set-x11-keymap us dell ,qwerty compose:caps``.
This generates the appropriate configuration in ``/etc/X11/xorg.conf.d/00-keyboard.conf``. This file is auto-generated. Do not edit it by hand, unless you know what you are doing.
Restarting ``xorg`` is required. The most straightforward way is to reboot the system.
More information in `this discussion <https://groups.google.com/d/topic/qubes-devel/d8ZQ_62asKI/discussion>`__ and `this GitHub issue <https://github.com/QubesOS/qubes-issues/issues/1396>`__.

78
user/troubleshooting/hvm-troubleshooting.md
View file

@ -1,78 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/hvm-troubleshooting/
ref: 232
title: HVM troubleshooting
---
## 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:
```
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
```
To fix this:
1. Kill the HVM.
1. Start the HVM
1. Press "e" at the grub screen to edit the boot parameters
1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm"
1. Press "Ctrl-x" to start the HVM
If this solves the problem then you will want to make the change permanent:
1. Edit the file `/etc/default/grub`.
1. Find the line which starts:
~~~
GRUB_CMDLINE_LINUX=
~~~
1. Remove this text from that line:
~~~
rhgb
~~~
1. Add this text to that line:
~~~
modprobe.blacklist=bochs_drm
~~~
1. Run this command:
~~~
grub2-mkconfig --output=/boot/grub2/grub.cfg
~~~
The HVM should now start normally.
## 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:
```sh
qvm-prefs <HVMname> kernel ""
```
## HVM crashes when booting from ISO
If your HVM crashes when trying to boot an ISO, first ensure that `qvm-prefs <HVMname> kernel` is empty, as shown above.
If this doesn't help, then disable memory balancing and set the minimum memory to 2GB.
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:
```sh
qvm-prefs <HVMname> memory 2000
```
## Attached devices in Windows HVM stop working on suspend/resume
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see [Suspend/resume Troubleshooting](/doc/suspend-resume-troubleshooting/#attached-devices-in-windows-hvm-stop-working-on-suspendresume).

102
user/troubleshooting/hvm-troubleshooting.rst Normal file
View file

@ -0,0 +1,102 @@
===================
HVM troubleshooting
===================
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
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
To fix this:
1. Kill the HVM.
2. Start the HVM
3. Press “e” at the grub screen to edit the boot parameters
4. Find the /vmlinuz line, and edit it to replace “rhgb” with “modprobe.blacklist=bochs_drm”
5. Press “Ctrl-x” to start the HVM
If this solves the problem then you will want to make the change permanent:
1. Edit the file ``/etc/default/grub``.
2. Find the line which starts:
.. code:: bash
GRUB_CMDLINE_LINUX=
3. Remove this text from that line:
.. code:: bash
rhgb
4. Add this text to that line:
.. code:: bash
modprobe.blacklist=bochs_drm
5. Run this command:
.. code:: bash
grub2-mkconfig --output=/boot/grub2/grub.cfg
The HVM should now start normally.
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
qvm-prefs <HVMname> kernel ""
HVM crashes when booting from ISO
---------------------------------
If your HVM crashes when trying to boot an ISO, first ensure that ``qvm-prefs <HVMname> kernel`` is empty, as shown above. If this doesn’t help, then disable memory balancing and set the minimum memory to 2GB.
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
qvm-prefs <HVMname> memory 2000
Attached devices in Windows HVM stop working on suspend/resume
--------------------------------------------------------------
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To know how to make the devices work, see :ref:`Suspend/resume Troubleshooting <user/troubleshooting/resume-suspend-troubleshooting:attached devices in windows hvm stop working on suspend\/resume>`.

126
user/troubleshooting/installation-troubleshooting.md
View file

@ -1,126 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/installation-troubleshooting/
ref: 224
title: Installation troubleshooting
---
## "An unknown error has occurred" error during installation
Some people have encountered this error message when trying to install Qubes on drives that already have data on them.
The solution is to exit the installer, wipe all data or delete all partitions, then restart the Qubes installation.
## Trouble installing from USB stick
If you are facing issues when booting using UEFI mode, see the [UEFI troubleshooting guide](/doc/uefi-troubleshooting/).
There are a variety of other problems that could arise when using a USB installation medium, and some of the issues can be fixed by doing one or more of the following:
* **Use a different USB drive:**
If possible, try several drives of different sizes and formats.
This determines whether the problem stems from the flash drive or Qubes installer.
Some laptops cannot read from an external boot device larger than 8GB.
If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB less than 8GB and of format FAT32.
Note that the Qubes installation image is over 4GB, so it may not fit on a smaller USB.
If a machine can not boot from a bigger USB, it may be too old to run Qubes.
* **Verify your Qubes ISO:**
Errors will occur if the Qubes installer is corrupted.
Ensure that the installer is correct and complete before writing it to a flash drive by [verifying the ISO](/security/verifying-signatures/).
* **Change the method you used to [write your ISO to a USB key](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium):**
Some people use the ``dd`` command (recommended), others use tools like Rufus, balenaEtcher or the GNOME Disk Utility.
If installation fails after using one tool, try a different one.
For example, if you are facing trouble installing Qubes after writing the ISO using Rufus, then try using other tools like balenaEtcher or the ``dd`` command.
In case the boot partition is not set to "active" after copying the ISO, you can use some other tool like `gparted` on a Linux system to activate it.
## "Warning: dracut-initqueue timeout - starting timeout scripts" during installation
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 [how to write your ISO to a USB key](/doc/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.
```
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
```
See [here](https://github.com/QubesOS/qubes-issues/issues/6447) for a discussion of this error message.
## Boot screen does not appear / system does not detect your installation medium
If the boot screen does not appear, there are several options to troubleshoot.
First, try rebooting your computer.
If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order.
This may require an [advanced reboot](https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings).
## "Not asking for VNC because we don't have a network" / "X startup failed, aborting installation" / "Pane is dead" error during installation
The boot mode in use may be causing these error messages.
Try to install after enabling both UEFI and legacy boot modes.
If that doesn't help, then disable one and try the other.
Visit the [UEFI Troubleshooting guide](/doc/uefi-troubleshooting/) if other errors arise during UEFI booting.
These errors may also occur due to an incompatible Nvidia graphics card. If you have one, follow the following instructions:
1. Disable secure/fast boot and use legacy mode
2. Enter GRUB, move the selection to the first choice, and then press the Tab key.
3. Now, you are in edit mode. Move the text cursor with your arrow key and after ``kernel=`` line, add:
```bash
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
```
If the above code doesn't fix the problem, replace it with:
```bash
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
```
For more information, look at the [Nvidia Troubleshooting guide](https://forum.qubes-os.org/t/19021#disabling-nouveau).
## Installation freezes at "Setting up Networking"
If you are facing this problem on an Apple computer, check out the [Macbook Troubleshooting guide](https://forum.qubes-os.org/t/19020).
If you are installing Qubes 4.0 on an external storage device, you may have forgotten to disable `sys-usb` during the [initial setup](/doc/installation-guide/#initial-setup), which is generally required for that setup to work.
This issue occurs due to the network card, which may be missing some drivers or is incompatible with Qubes.
First, install all available drivers for the card.
You can install the drivers without internet access by first downloading them on another machine, then transferring them over to the current machine (e.g., with a USB drive).
If installing the available drivers does not help, disable the network card in the BIOS and perform the installation before re-enabling the card.
If this solves the issue, it confirms the PCI card is incompatible with Qubes.
In this case, you may want to consider replacing it with a network card of a different brand.
Broadcom cards are notoriously problematic with Qubes.
## "Unsupported Hardware Detected" error ##
During Qubes installation, you may come across the error message which reads "Unsupported Hardware Detected.
Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally".
This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS.
Return to the [hardware requirements](/doc/installation-guide/#hardware-requirements) section to learn how to activate it.
If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
In Qubes 4.0, the default installation won't function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to "PV".
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:
```
Start failed: internal error: libxenlight failed to create new domain 'sys-net', see /var/log/libvirt/libxl/libxl-driver.log for details
```
To confirm that a missing IOMMU is causing this problem, check for the following error message in `/var/log/libvirt/libxl/libxl-driver.log`:
```
2022-03-01 13:27:17.117+0000: libxl: libxl_create.c:1146:libxl__domain_config_setdefault: passthrough not supported on this platform
```
Here are the steps to fix this. Note that this allows sys-net and sys-usb to take complete control of the system, as described in the [FAQ here](/faq/#why-is-vt-damd-viamd-iommu-important):
1. Change the virtualization mode of sys-net and sys-usb to "PV"
2. Add `qubes.enable_insecure_pv_passthrough` to `GRUB_CMDLINE_LINUX` in `/etc/default/grub`
3. Run `sudo grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg`. If you are using a non-UEFI BIOS (where `/boot/efi/EFI` doesn't exist), use the command `sudo grub-mkconfig -o /boot/grub2/grub.cfg` instead.
4. Reboot

132
user/troubleshooting/installation-troubleshooting.rst Normal file
View file

@ -0,0 +1,132 @@
============================
Installation troubleshooting
============================
"An unknown error has occurred" error during installation
---------------------------------------------------------
Some people have encountered this error message when trying to install Qubes on drives that already have data on them. The solution is to exit the installer, wipe all data or delete all partitions, then restart the Qubes installation.
Trouble installing from USB stick
---------------------------------
If you are facing issues when booting using UEFI mode, see the :doc:`UEFI troubleshooting guide </user/troubleshooting/uefi-troubleshooting>`.
There are a variety of other problems that could arise when using a USB installation medium, and some of the issues can be fixed by doing one or more of the following:
- **Use a different USB drive:** If possible, try several drives of different sizes and formats. This determines whether the problem stems from the flash drive or Qubes installer. Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB less than 8GB and of format FAT32. Note that the Qubes installation image is over 4GB, so it may not fit on a smaller USB. If a machine can not boot from a bigger USB, it may be too old to run Qubes.
- **Verify your Qubes ISO:** Errors will occur if the Qubes installer is corrupted. Ensure that the installer is correct and complete before writing it to a flash drive by :doc:`verifying the ISO </project-security/verifying-signatures>`.
- **Change the method you used to** :ref:`write your ISO to a USB key <user/downloading-installing-upgrading/installation-guide:copying the iso onto the installation medium>` **:** Some people use the ``dd`` command (recommended), others use tools like Rufus, balenaEtcher or the GNOME Disk Utility. If installation fails after using one tool, try a different one. For example, if you are facing trouble installing Qubes after writing the ISO using Rufus, then try using other tools like balenaEtcher or the ``dd`` command. In case the boot partition is not set to “active” after copying the ISO, you can use some other tool like ``gparted`` on a Linux system to activate it.
"**Warning:** dracut-initqueue timeout - starting timeout scripts" during installation
----------------------------------------------------------------------------------
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
$ sudo dd if=Qubes-RX-x86_64.iso of=/dev/sdY status=progress bs=1048576 && sync
See `here <https://github.com/QubesOS/qubes-issues/issues/6447>`__ for a discussion of this error message.
Boot screen does not appear / system does not detect your installation medium
-----------------------------------------------------------------------------
If the boot screen does not appear, there are several options to troubleshoot. First, try rebooting your computer. If it still loads your currently installed operating system or does not detect your installation medium, make sure the boot order is set up appropriately.
The process to change the boot order varies depending on the currently installed system and the motherboard manufacturer.
If **Windows 10** is installed on your machine, you may need to follow specific instructions to change the boot order. This may require an `advanced reboot <https://support.microsoft.com/en-us/help/4026206/windows-10-find-safe-mode-and-other-startup-settings>`__.
"Not asking for VNC because we don't have a network" / "X startup failed, aborting installation" / "Pane is dead" error during installation
-------------------------------------------------------------------------------------------------------------------------------------------
The boot mode in use may be causing these error messages. Try to install after enabling both UEFI and legacy boot modes. If that doesn’t help, then disable one and try the other. Visit the :doc:`UEFI Troubleshooting guide </user/troubleshooting/uefi-troubleshooting>` if other errors arise during UEFI booting.
These errors may also occur due to an incompatible Nvidia graphics card. If you have one, follow the following instructions:
1. Disable secure/fast boot and use legacy mode
2. Enter GRUB, move the selection to the first choice, and then press the Tab key.
3. Now, you are in edit mode. Move the text cursor with your arrow key and after ``kernel=`` line, add:
.. code:: bash
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
If the above code doesn’t fix the problem, replace it with:
.. code:: bash
noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
For more information, look at the `Nvidia Troubleshooting guide <https://forum.qubes-os.org/t/19021#disabling-nouveau>`__.
Installation freezes at "Setting up Networking"
-----------------------------------------------
If you are facing this problem on an Apple computer, check out the `Macbook Troubleshooting guide <https://forum.qubes-os.org/t/19020>`__.
If you are installing Qubes 4.0 on an external storage device, you may have forgotten to disable ``sys-usb`` during the :ref:`initial setup <user/downloading-installing-upgrading/installation-guide:initial setup>`, which is generally required for that setup to work.
This issue occurs due to the network card, which may be missing some drivers or is incompatible with Qubes.
First, install all available drivers for the card. You can install the drivers without internet access by first downloading them on another machine, then transferring them over to the current machine (e.g., with a USB drive).
If installing the available drivers does not help, disable the network card in the BIOS and perform the installation before re-enabling the card. If this solves the issue, it confirms the PCI card is incompatible with Qubes. In this case, you may want to consider replacing it with a network card of a different brand. Broadcom cards are notoriously problematic with Qubes.
"Unsupported Hardware Detected" error
-------------------------------------
During Qubes installation, you may come across the error message which reads “Unsupported Hardware Detected. Missing features: IOMMU/VT-d/AMD-Vi, Interrupt Remapping. Without these features, Qubes OS will not function normally”.
This error message indicates that IOMMU-virtualization hasn’t been activated in the BIOS. Return to the :ref:`hardware requirements <user/downloading-installing-upgrading/installation-guide:hardware requirements>` section to learn how to activate it. If the setting is not configured correctly, it means that your hardware won’t be able to leverage some Qubes security features, such as a strict isolation of the networking and USB hardware.
In Qubes 4.0, the default installation won’t function properly without IOMMU, as default sys-net and sys-usb qubes require IOMMU. It is possible to configure them to reduce isolation and not use IOMMU by changing virtualization mode of these two VMs to “PV”.
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
Start failed: internal error: libxenlight failed to create new domain 'sys-net', see /var/log/libvirt/libxl/libxl-driver.log for details
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
2022-03-01 13:27:17.117+0000: libxl: libxl_create.c:1146:libxl__domain_config_setdefault: passthrough not supported on this platform
Here are the steps to fix this. Note that this allows sys-net and sys-usb to take complete control of the system, as described in the :ref:`FAQ here <introduction/faq:why is vt-d\/amd-vi\/amd iommu important?>`:
1. Change the virtualization mode of sys-net and sys-usb to “PV”
2. Add ``qubes.enable_insecure_pv_passthrough`` to ``GRUB_CMDLINE_LINUX`` in ``/etc/default/grub``
3. Run ``sudo grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg``. If you are using a non-UEFI BIOS (where ``/boot/efi/EFI`` doesn’t exist), use the command ``sudo grub-mkconfig -o /boot/grub2/grub.cfg`` instead.
4. Reboot

25
user/troubleshooting/media-troubleshooting.md
View file

@ -1,25 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/media-troubleshooting/
ref: 235
title: Media troubleshooting
---
## Can't play media videos in a VM due to missing codecs
If you’re having trouble playing a video file in a qube, you’re probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different template distros by following the instructions [here](/faq/#how-do-i-play-video-files).
## Video lagging
Playing videos may cause lags since software decoding uses a lot of CPU.
Depending on your video player, there are some settings that may smoothen video plays:
* If using VLC media player, go to Tools--> Preferences --> Video --> Output.
By default, the Output is set to "Automatic".
Go through the list and try out other output options to see if any makes videos run smoother.
* If using mpv media player, you may be able to improve performance by entering `mpv --profile=sw-fast --vo=x11` in a terminal.
* For video lags when playing videos from a browser, disable hardware acceleration in the browser. If the problem arises when watching streams, it may be smoother to use `streamlink` to view streams in mpv instead of using the browser.

26
user/troubleshooting/media-troubleshooting.rst Normal file
View file

@ -0,0 +1,26 @@
=====================
Media troubleshooting
=====================
Can't play media videos in a VM due to missing codecs
-----------------------------------------------------
If you’re having trouble playing a video file in a qube, you’re probably missing the required codecs. The easiest way to resolve this is to install VLC Media Player and use that to play your video files. You can do this in multiple different template distros by following the instructions :ref:`here <introduction/faq:how do i play video files?>`.
Video lagging
-------------
Playing videos may cause lags since software decoding uses a lot of CPU.
Depending on your video player, there are some settings that may smoothen video plays:
- If using VLC media player, go to Tools–> Preferences –> Video –> Output. By default, the Output is set to “Automatic”. Go through the list and try out other output options to see if any makes videos run smoother.
- If using mpv media player, you may be able to improve performance by entering ``mpv --profile=sw-fast --vo=x11`` in a terminal.
- For video lags when playing videos from a browser, disable hardware acceleration in the browser. If the problem arises when watching streams, it may be smoother to use ``streamlink`` to view streams in mpv instead of using the browser.

154
user/troubleshooting/pci-troubleshooting.md
View file

@ -1,154 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/pci-troubleshooting/
ref: 230
title: PCI troubleshooting
---
## DMA errors
VMs with attached PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb).
By default, it is 2MB, but some devices (such as the [Realtek RTL8111DL Gigabit Ethernet Controller](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3)) need a larger DMA buffer size.
Without a larger buffer, you will face DMA errors such as `Failed to map TX DMA`.
To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks) by running the following in a dom0 terminal:
```
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192"
```
The `8192` value is the default value and some devices may require a larger value (like `16384`).
## PCI Passthrough Issues
Sometimes the PCI arbitrator is too strict, which may cause errors such as `Unable to reset PCI device` and other PCI-related errors.
There is a way to enable permissive mode for it.
See also: [this thread](https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI) and the Xen wiki's [PCI passthrough](https://wiki.xen.org/wiki/Xen_PCI_Passthrough) page.
Other times, you may instead need to disable the FLR requirement on a device.
Both can be achieved during attachment with `qvm-pci` as described [PCI Devices documentation](/doc/how-to-use-pci-devices/#additional-attach-options).
## "Unable to reset PCI device" errors
### libvirt.libvirtError: internal error: Unable to reset PCI device [...]: internal error: Active [...] devices on bus with [...], not doing bus reset
After running `qvm-start sys-net`, you may encounter an error message which begins with `libvirt.libvirtError: internal error: Unable to reset PCI device`.
This issue is likely to occur if you have the same device assigned to more than one
VM.
When you try to start sys-net with the `qvm-start sys-net` command, there is already a VM running (e.g., auto-starting) with one or more of the same devices as those assigned to sys-net.
To fix the error, remove the offending PCI device.
#### Using the Qubes interface
From the "Selected" panel in sys-net, navigate to VM Settings, then Devices. There, you can remove the offending PCI device(s) and keep the desired PCI device.
#### 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:
~~~
0000:03:00.0 Audio device: Intel Corporation Haswell-ULT HD Audio Controller (rev 0b)
~~~
In the above output, the BDF (Bus Device Function) of the device is `0000:03:00.0`
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:
~~~
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`.
~~~
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:
~~~
[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
~~~
Finally, run `systemctl enable qubes-pre-netvm.service` and it will now persist between reboots.
### Domain [...] has failed to start: internal error: Unable to reset PCI device [...]: no FLR, PM reset or bus reset available
This is a [PCI passthrough issue](/doc/pci-troubleshooting/#pci-passthrough-issues), which occurs when PCI arbitrator is too strict.
There is a way to enable permissive mode for it.
Sometimes, you may instead need to disable the FLR requirement on a device.
Both can be achieved during attachment with `qvm-pci` as described below.
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.
~~~
qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>
~~~
Be sure to replace `<BDF_OF_DEVICE>` with the BDF of your PCI device, which can be obtained from running `qvm-pci`.
You can also configure strict reset directly from the Qubes interface by following these steps:
1. Go to the sys-net VM settings
2. Go to Devices
3. Make sure the device is in the right field
4. Click "Configure strict reset for PCI devices"
5. Select the device, click OK and apply
## Broadcom BCM43602 Wi-Fi card causes system freeze
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in [Macbook Troubleshooting](https://forum.qubes-os.org/t/19020#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card).
For other non-Macbook machines, it is advisable to replace the Broadcom BCM43602 with one known to work on Qubes, such as the Atheros AR9462.
Note that your computer manufacturer may have added a Wi-Fi card whitelist in your BIOS, which will prevent booting your computer if you have a non-listed wireless card.
It is possible bypass this limitation by removing the whitelist, disabling a check for it or modifying the whitelist to replace device ID of a whitelisted WiFi card with device ID of your new WiFi card.
## Wireless card stops working after dom0 update
There have been many instances where a Wi-Fi card stops working after a dom0 update.
If you run `sudo dmesg` in sys-net, you may see errors beginning with `iwlwifi`.
You can fix the problem by going to the sys-net VM's settings and changing the VM kernel to the previous version.
## Attached devices in Windows HVM stop working on suspend/resume
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working.
Refer to [Suspend/Resume Troubleshooting](/doc/suspend-resume-troubleshooting/#attached-devices-in-windows-hvm-stop-working-on-suspendresume) for a solution.
## PCI device not available in dom0 after being unassigned from a qube
After you assign a PCI device to a qube, then unassign it/shut down the qube, the device is not available in dom0.
This is an intended feature.
A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there.
Look at the [FAQs](/faq/#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshut-down-the-qube-why-isnt-the-device-available-in-dom0) to learn how to re-enable the device in dom0.
## Network adapter does not work
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes.
You may need to install a binary blob, which provides drivers, from the linux-firmware package.
Open a terminal and run `sudo dnf install linux-firmware` in the template upon which your NetVM is based.
You have to restart the NetVM after the template has been shut down.

166
user/troubleshooting/pci-troubleshooting.rst Normal file
View file

@ -0,0 +1,166 @@
===================
PCI troubleshooting
===================
DMA errors
----------
VMs with attached PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb). By default, it is 2MB, but some devices (such as the `Realtek RTL8111DL Gigabit Ethernet Controller <https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3>`__) need a larger DMA buffer size. Without a larger buffer, you will face DMA errors such as ``Failed to map TX DMA``.
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
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=8192"
The ``8192`` value is the default value and some devices may require a larger value (like ``16384``).
PCI Passthrough Issues
----------------------
Sometimes the PCI arbitrator is too strict, which may cause errors such as ``Unable to reset PCI device`` and other PCI-related errors. There is a way to enable permissive mode for it. See also: `this thread <https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI>`__ and the Xen wiki’s `PCI passthrough <https://wiki.xen.org/wiki/Xen_PCI_Passthrough>`__ page. Other times, you may instead need to disable the FLR requirement on a device.
Both can be achieved during attachment with ``qvm-pci`` as described :ref:`PCI Devices documentation <user/how-to-guides/how-to-use-pci-devices:additional attach options>`.
"Unable to reset PCI device" errors
-----------------------------------
libvirt.libvirtError: internal error: Unable to reset PCI device […]: internal error: Active […] devices on bus with […], not doing bus reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After running ``qvm-start sys-net``, you may encounter an error message which begins with ``libvirt.libvirtError: internal error: Unable to reset PCI device``.
This issue is likely to occur if you have the same device assigned to more than one VM. When you try to start sys-net with the ``qvm-start sys-net`` command, there is already a VM running (e.g., auto-starting) with one or more of the same devices as those assigned to sys-net.
To fix the error, remove the offending PCI device.
Using the Qubes interface
^^^^^^^^^^^^^^^^^^^^^^^^^
From the “Selected” panel in sys-net, navigate to VM Settings, then Devices. There, you can remove the offending PCI device(s) and keep the desired PCI device.
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
0000:03:00.0 Audio device: Intel Corporation Haswell-ULT HD Audio Controller (rev 0b)
In the above output, the BDF (Bus Device Function) of the device is ``0000:03:00.0``
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
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
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
[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
Finally, run ``systemctl enable qubes-pre-netvm.service`` and it will now persist between reboots.
Domain […] has failed to start: internal error: Unable to reset PCI device […]: no FLR, PM reset or bus reset available
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is a :ref:`PCI passthrough issue <user/troubleshooting/pci-troubleshooting:pci passthrough issues>`, which occurs when PCI arbitrator is too strict. There is a way to enable permissive mode for it. Sometimes, you may instead need to disable the FLR requirement on a device. Both can be achieved during attachment with ``qvm-pci`` as described below.
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
qvm-pci attach --persistent --option permissive=true --option no-strict-reset=true sys-usb dom0:<BDF_OF_DEVICE>
Be sure to replace ``<BDF_OF_DEVICE>`` with the BDF of your PCI device, which can be obtained from running ``qvm-pci``.
You can also configure strict reset directly from the Qubes interface by following these steps:
1. Go to the sys-net VM settings
2. Go to Devices
3. Make sure the device is in the right field
4. Click “Configure strict reset for PCI devices”
5. Select the device, click OK and apply
Broadcom BCM43602 Wi-Fi card causes system freeze
-------------------------------------------------
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in `Macbook Troubleshooting <https://forum.qubes-os.org/t/19020#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card>`__.
For other non-Macbook machines, it is advisable to replace the Broadcom BCM43602 with one known to work on Qubes, such as the Atheros AR9462.
Note that your computer manufacturer may have added a Wi-Fi card whitelist in your BIOS, which will prevent booting your computer if you have a non-listed wireless card. It is possible bypass this limitation by removing the whitelist, disabling a check for it or modifying the whitelist to replace device ID of a whitelisted WiFi card with device ID of your new WiFi card.
Wireless card stops working after dom0 update
---------------------------------------------
There have been many instances where a Wi-Fi card stops working after a dom0 update. If you run ``sudo dmesg`` in sys-net, you may see errors beginning with ``iwlwifi``. You can fix the problem by going to the sys-net VM’s settings and changing the VM kernel to the previous version.
Attached devices in Windows HVM stop working on suspend/resume
--------------------------------------------------------------
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. Refer to :ref:`Suspend/Resume Troubleshooting <user/troubleshooting/resume-suspend-troubleshooting:attached devices in windows hvm stop working on suspend\/resume>` for a solution.
PCI device not available in dom0 after being unassigned from a qube
-------------------------------------------------------------------
After you assign a PCI device to a qube, then unassign it/shut down the qube, the device is not available in dom0. This is an intended feature. A device which was previously assigned to a less trusted qube could attack dom0 if it were automatically reassigned there. Look at the :ref:`FAQs <introduction/faq:i assigned a pci device to a qube, then unassigned it\/shut down the qube. why isn't the device available in dom0?>` to learn how to re-enable the device in dom0.
Network adapter does not work
-----------------------------
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes. You may need to install a binary blob, which provides drivers, from the linux-firmware package.
Open a terminal and run ``sudo dnf install linux-firmware`` in the template upon which your NetVM is based. You have to restart the NetVM after the template has been shut down.

145
user/troubleshooting/resume-suspend-troubleshooting.md
View file

@ -1,145 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/suspend-resume-troubleshooting/
redirect_from:
- /en/doc/wireless-troubleshooting/
- /doc/wireless-troubleshooting/
ref: 94
title: Suspend/resume troubleshooting
---
First check if there are any remarks for similar devices in the [Hardware
Compatibility List (HCL)](/hcl/).
## Network-Manager says “Device not ready” on suspend/resume
These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here.
If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver.
### Determining your wireless card driver
First, determine which kernel module corresponds to your wireless card. There are several ways to do this.
The easiest is via the output of `lspci -k` in your sys-net VM:
~~~
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
Subsystem: Intel Corporation Device 0130
Kernel driver in use: iwlwifi
Kernel modules: iwlwifi
~~~
Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module.
### 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):
~~~
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
...
IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: Failed to load firmware chunk!
iwlwifi 0000:00:00.0: Could not load the [0] uCode section
iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110
iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110
...
iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2
~~~
### Seeing what modules you have loaded
You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo <module_name>`.
For example, we list what modules we have loaded:
~~~
[user@sys-net ~]$ lsmod
Module Size Used by
iwlmvm 315392 0
iwlwifi 155648 1 iwlmvm
mac80211 708608 1 iwlmvm
cfg80211 557056 3 iwlwifi,mac80211,iwlmvm
...
~~~
and check one:
~~~
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: The new Intel(R) wireless AGN driver for Linux
depends: iwlwifi,mac80211,cfg80211
~~~
Hey, it's our wireless driver!
Now, check if reloading the module makes wireless work again:
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
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:
~~~
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: Intel(R) Wireless WiFi driver for Linux
depends: cfg80211
~~~
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
## Drivers do not reload automatically on suspend/resume
If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`.
In the above example, it would look like this:
~~~
[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
# file is used only if the VM has any PCI device assigned. Modules will be
# automatically loaded after resume.
iwlmvm
iwlwifi
~~~
## Power consumption increases on suspend/resume
This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume.
To solve the problem, disable hyper-threading in the BIOS. This [external guide](https://www.pcmag.com/news/how-to-disable-hyperthreading) explains how to disable hyper-threading.
Since Qubes does disable hyperthreading by default (by not using secondary threads), you won't pay any performance cost.
## Attached devices in Windows HVM stop working on suspend/resume
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM.
This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again.
This is illustrated on the screenshot below:
![r2b1-win7-usb-disable.png](/attachment/doc/r2b1-win7-usb-disable.png)
## Suspend turns off the screen and gets stuck
On some devices suspend-to-RAM does not work and a hard power-off is needed to
recover, because the system does not go into deep sleep. To get suspend to
work, you need to add `mem_sleep_default=deep` kernel option. For legacy boot,
or UEFI/legacy in R4.1+, add it to the `GRUB_CMDLINE_LINUX` setting in
`/etc/default/grub`, update the grub config, and reboot. In R4.0 with UEFI
boot, you need to add it to every `kernel=` line in
`/boot/efi/EFI/qubes/xen.cfg` and reboot.

163
user/troubleshooting/resume-suspend-troubleshooting.rst Normal file
View file

@ -0,0 +1,163 @@
==============================
Suspend/resume troubleshooting
==============================
First check if there are any remarks for similar devices in the `Hardware Compatibility List (HCL) <https://www.qubes-os.org/hcl/>`__.
Network-Manager says "Device not ready" on suspend/resume
---------------------------------------------------------
These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here.
If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says “Device not ready”, then try un-loading and re-loading the driver.
Determining your wireless card driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, determine which kernel module corresponds to your wireless card. There are several ways to do this.
The easiest is via the output of ``lspci -k`` in your sys-net VM:
.. code:: bash
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
Subsystem: Intel Corporation Device 0130
Kernel driver in use: iwlwifi
Kernel modules: iwlwifi
Here we see that the machine in question has an Intel wireless card, being used by the ``iwlwifi`` kernel module.
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
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
...
IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: Failed to load firmware chunk!
iwlwifi 0000:00:00.0: Could not load the [0] uCode section
iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110
iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110
...
iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2
Seeing what modules you have loaded
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can check which drivers are currently loaded with ``lsmod``, and view details about a module with ``modinfo <module_name>``.
For example, we list what modules we have loaded:
.. code:: bash
[user@sys-net ~]$ lsmod
Module Size Used by
iwlmvm 315392 0
iwlwifi 155648 1 iwlmvm
mac80211 708608 1 iwlmvm
cfg80211 557056 3 iwlwifi,mac80211,iwlmvm
...
and check one:
.. code:: bash
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: The new Intel(R) wireless AGN driver for Linux
depends: iwlwifi,mac80211,cfg80211
Hey, it’s our wireless driver!
Now, check if reloading the module makes wireless work again:
.. code:: bash
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
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
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: Intel(R) Wireless WiFi driver for Linux
depends: cfg80211
.. code:: bash
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading
[user@sys-net ~]$ sudo modprobe iwlmvm
Drivers do not reload automatically on suspend/resume
-----------------------------------------------------
If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in ``/rw/config/suspend-module-blacklist``.
In the above example, it would look like this:
.. code:: bash
[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
# file is used only if the VM has any PCI device assigned. Modules will be
# automatically loaded after resume.
iwlmvm
iwlwifi
Power consumption increases on suspend/resume
---------------------------------------------
This problem is related to the software method used to disable sibling threads and how it interacts with suspend/resume. To solve the problem, disable hyper-threading in the BIOS. This `external guide <https://www.pcmag.com/news/how-to-disable-hyperthreading>`__ explains how to disable hyper-threading. Since Qubes does disable hyperthreading by default (by not using secondary threads), you won’t pay any performance cost.
Attached devices in Windows HVM stop working on suspend/resume
--------------------------------------------------------------
After the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working. To make the devices work, they should be restarted within the VM. This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), ‘Disabling’ the device, and then ‘Enabling’ the device again. This is illustrated on the screenshot below:
.. figure:: /attachment/doc/r2b1-win7-usb-disable.png
:alt: r2b1-win7-usb-disable.png
Suspend turns off the screen and gets stuck
-------------------------------------------
On some devices suspend-to-RAM does not work and a hard power-off is needed to recover, because the system does not go into deep sleep. To get suspend to work, you need to add ``mem_sleep_default=deep`` kernel option. For legacy boot, or UEFI/legacy in R4.1+, add it to the ``GRUB_CMDLINE_LINUX`` setting in ``/etc/default/grub``, update the grub config, and reboot. In R4.0 with UEFI boot, you need to add it to every ``kernel=`` line in ``/boot/efi/EFI/qubes/xen.cfg`` and reboot.

131
user/troubleshooting/uefi-troubleshooting.md
View file

@ -1,131 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/uefi-troubleshooting/
ref: 177
title: UEFI troubleshooting
---
## Successfully installed in legacy mode, but had to change some xen parameters
**Note**: If you make changes, you must boot from "Partition 1" explicitly from UEFI boot menu.
**Change the xen configuration on a USB media**
1. Attach the usb disk, mount the EFI partition (second partition available on the disk)
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`):
```
vi EFI/BOOT/grub.cfg
```
3. Change the `multiboot2 /images/pxeboot/xen.gz` line to add your xen parameters on the boot entry of your choice
4. Install using your modified boot entry
**Change xen configuration directly in an iso image**
1. Set up a loop device (replacing `X` with your ISO's version name): `losetup -P /dev/loop0 Qubes-RX-x86_64.iso`
2. Mount the loop device: `sudo mount /dev/loop0p2 /mnt`
3. Edit `EFI/BOOT/grub.cfg` to add your params to the `multiboot2 /images/pxeboot/xen.gz` line
4. Save your changes, unmount and dd to usb device
## Installation freezes before displaying installer
If you have an Nvidia card, see also [Nvidia Troubleshooting](https://forum.qubes-os.org/t/19021#disabling-nouveau).
## Installation from USB stick hangs on black screen
Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB lesser than 8GB and of format FAT32.
## Installation completes successfully but then system crash/restarts on next boot
Some Dell systems and probably others have [another bug in UEFI firmware](https://web.archive.org/web/20170901231026/https://markmail.org/message/amw5336otwhdxi76).
These systems need `efi=attr=uc` enabled at all times.
Although this is enabled by default in the installer, it is disabled after the first stage of a successful install.
You can re-enable it either as part of the install process:
1. Perform installation normally, but don't reboot the system at the end yet.
2. Go to `tty2` (Ctrl-Alt-F2).
3. Execute:
```
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
```
4. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
5. Continue with setting up default templates and logging in to Qubes.
Or if you have already rebooted after the first stage install and have encountered this issue, by:
1. Boot Qubes OS install media into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi)
2. Press '3' to go to the shell
3. Find and mount the EFI system partition. (replace `/dev/sda` with your disk name. If unsure, use the `lsblk` command to display a list of disks):
```
fdisk -l /dev/sda | grep EFI
```
The output should look like this:
```
/dev/sda1 2048 1230847 1228800 600M EFI System
```
Then mount it:
```
mkdir -p /mnt/sysimage/boot/efi
mount /dev/sda1 /mnt/sysimage/boot/efi
```
4. Execute:
```
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
```
5. Type `reboot`.
6. Continue with setting up default templates and logging in to Qubes.
## Boot device not recognized after installing
Some firmware will not recognize the default Qubes EFI configuration.
As such, it will have to be manually edited to be bootable.
1. Boot Qubes OS install media into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi)
2. Press '3' to go to the shell
3. Find and mount the EFI system partition. (replace `/dev/sda` with your disk name. If unsure, use the `lsblk` command to display a list of disks):
```
fdisk -l /dev/sda | grep EFI
```
The output should look like this:
```
/dev/sda1 2048 1230847 1228800 600M EFI System
```
Then mount it:
```
mkdir -p /mnt/sysimage/boot/efi
mount /dev/sda1 /mnt/sysimage/boot/efi
```
4. Copy `grubx64.efi` to the fallback path:
```
cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi
```
5. Type `reboot`
## "Qubes" boot option is missing after removing / attaching a disk or updating the BIOS
1. Boot Qubes OS install media into [rescue mode](/doc/uefi-troubleshooting/#accessing-installer-rescue-mode-on-uefi)
2. Press '3' to go to the shell
3. Create boot entry in EFI firmware (replace `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
```
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1
```
## Accessing installer Rescue mode on UEFI
Choose "Rescue a Qubes OS system" from grub2 boot menu.

146
user/troubleshooting/uefi-troubleshooting.rst Normal file
View file

@ -0,0 +1,146 @@
====================
UEFI troubleshooting
====================
Successfully installed in legacy mode, but had to change some xen parameters
----------------------------------------------------------------------------
**Note**: If you make changes, you must boot from “Partition 1” explicitly from UEFI boot menu.
**Change the xen configuration on a USB media**
1. Attach the usb disk, mount the EFI partition (second partition available on the disk)
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
vi EFI/BOOT/grub.cfg
3. Change the ``multiboot2 /images/pxeboot/xen.gz`` line to add your xen parameters on the boot entry of your choice
4. Install using your modified boot entry
**Change xen configuration directly in an iso image**
1. Set up a loop device (replacing ``X`` with your ISO’s version name): ``losetup -P /dev/loop0 Qubes-RX-x86_64.iso``
2. Mount the loop device: ``sudo mount /dev/loop0p2 /mnt``
3. Edit ``EFI/BOOT/grub.cfg`` to add your params to the ``multiboot2 /images/pxeboot/xen.gz`` line
4. Save your changes, unmount and dd to usb device
Installation freezes before displaying installer
------------------------------------------------
If you have an Nvidia card, see also `Nvidia Troubleshooting <https://forum.qubes-os.org/t/19021#disabling-nouveau>`__.
Installation from USB stick hangs on black screen
-------------------------------------------------
Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB lesser than 8GB and of format FAT32.
Installation completes successfully but then system crash/restarts on next boot
-------------------------------------------------------------------------------
Some Dell systems and probably others have `another bug in UEFI firmware <https://web.archive.org/web/20170901231026/https://markmail.org/message/amw5336otwhdxi76>`__. These systems need ``efi=attr=uc`` enabled at all times. Although this is enabled by default in the installer, it is disabled after the first stage of a successful install. You can re-enable it either as part of the install process:
1. Perform installation normally, but don’t reboot the system at the end yet.
2. Go to ``tty2`` (Ctrl-Alt-F2).
3. Execute:
.. code:: bash
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
4. Go back to ``tty6`` (Ctrl-Alt-F6) and click ``Reboot``.
5. Continue with setting up default templates and logging in to Qubes.
Or if you have already rebooted after the first stage install and have encountered this issue, by:
1. Boot Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi``
4. Execute:
.. code:: bash
sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg
5. Type ``reboot``.
6. Continue with setting up default templates and logging in to Qubes.
Boot device not recognized after installing
-------------------------------------------
Some firmware will not recognize the default Qubes EFI configuration. As such, it will have to be manually edited to be bootable.
1. Boot Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi``
4. Copy ``grubx64.efi`` to the fallback path:
.. code:: bash
cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi
5. Type ``reboot``
"Qubes" boot option is missing after removing / attaching a disk or updating the BIOS
-------------------------------------------------------------------------------------
1. Boot Qubes OS install media into :ref:`rescue mode <user/troubleshooting/uefi-troubleshooting:accessing installer rescue mode on uefi>`
2. Press ‘3’ to go to the shell
3. Create boot entry in EFI firmware (replace ``/dev/sda`` with your disk name and ``-p 1`` with ``/boot/efi`` partition number):
.. code:: bash
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1
Accessing installer Rescue mode on UEFI
---------------------------------------
Choose “Rescue a Qubes OS system” from grub2 boot menu.

48
user/troubleshooting/update-troubleshooting.md
View file

@ -1,48 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/update-troubleshooting/
ref: 239
title: Update troubleshooting
---
## “Failed to synchronize cache for repo” errors when updating Fedora templates
This is general Fedora issue, not a Qubes-specific issue.
Usually, this is due to network problems (especially if downloading updates over Tor) or problems with the download mirrors.
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- [https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/](https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/)
- [https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update](https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update)
- [https://www.reddit.com/r/Fedora/comments/74nldq/fedora\_26\_dnf\_error\_failed\_to\_synchronize\_cache/](https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/)
- [https://bugzilla.redhat.com/show\_bug.cgi?id=1494178](https://bugzilla.redhat.com/show_bug.cgi?id=1494178)
- [https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates](https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates)
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
## Lost internet access after a template update
In earlier versions of Qubes, there were situations where qubes lost internet access after a template update. The following fix should be applied in recent versions of Qubes.
Run `systemctl enable NetworkManager-dispatcher.service` in the template upon which your NetVM is based.
You may have to reboot afterward for the change to take effect.
(Note: This is an upstream problem. See [this Redhat ticket](https://bugzilla.redhat.com/show_bug.cgi?id=974811)).
For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
## Windows update is stuck
This has nothing to do with Qubes.
It's a longstanding Windows bug.
More information about this issue and solutions can be found [here](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates).
## Dom0 and/or template update stalls when updating via the GUI tool
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
Depending on your operating system, open a terminal in the templates and run:
* Fedora: `sudo dnf upgrade`
* Debian: `apt-get update && apt-get dist-upgrade`

54
user/troubleshooting/update-troubleshooting.rst Normal file
View file

@ -0,0 +1,54 @@
======================
Update troubleshooting
======================
"Failed to synchronize cache for repo" errors when updating Fedora templates
----------------------------------------------------------------------------
This is general Fedora issue, not a Qubes-specific issue. Usually, this is due to network problems (especially if downloading updates over Tor) or problems with the download mirrors. Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later. Here are some examples of non-Qubes reports about this problem:
- https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/
- https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update
- https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/
- https://bugzilla.redhat.com/show_bug.cgi?id=1494178
- https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates
More examples can be found by searching for “Failed to synchronize cache for repo” (with quotation marks) on your preferred search engine.
Lost internet access after a template update
--------------------------------------------
In earlier versions of Qubes, there were situations where qubes lost internet access after a template update. The following fix should be applied in recent versions of Qubes.
Run ``systemctl enable NetworkManager-dispatcher.service`` in the template upon which your NetVM is based. You may have to reboot afterward for the change to take effect. (**Note:** This is an upstream problem. See `this Redhat ticket <https://bugzilla.redhat.com/show_bug.cgi?id=974811>`__). For details, see the qubes-users mailing list threads `here <https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion>`__ and `here <https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion>`__.)
Windows update is stuck
-----------------------
This has nothing to do with Qubes. It’s a longstanding Windows bug. More information about this issue and solutions can be found `here <https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates>`__.
Dom0 and/or template update stalls when updating via the GUI tool
-----------------------------------------------------------------
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run ``sudo qubes-dom0-update``.
Depending on your operating system, open a terminal in the templates and run:
- Fedora: ``sudo dnf upgrade``
- Debian: ``apt-get update && apt-get dist-upgrade``

106
user/troubleshooting/usb-troubleshooting.md
View file

@ -1,106 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/usb-troubleshooting/
ref: 234
title: USB troubleshooting
---
## disp-sys-usb does not start
If the disp-sys-usb does not start, it could be due to a PCI passthrough problem.
For more details on this issue along with possible solutions, look at [PCI passthrough issues](/doc/pci-troubleshooting/#pci-passthrough-issues).
## Can't attach a USB device / USB device not showing in qvm-usb
To successfully attach a USB device, you require a VM dedicated to handling the USB input and output.
For guidance setting up a USB qube, see the [USB documentation](/doc/how-to-use-usb-devices/#creating-and-using-a-usb-qube).
Currently (until issue [1082](https://github.com/QubesOS/qubes-issues/issues/1082) gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, `libvirtd`) will think that the device is still attached to the qube and will not allow attaching further devices under the same name.
This may be characterized by VM manager crashes and the error message: `Houston, we have a problem`.
The easiest way to recover from such a situation is to reboot the qube to which the device was attached.
If this isn't an option, you can manually recover from the situation by following the instructions at the [Block Devices documentation](/doc/how-to-use-block-storage-devices/#what-if-i-removed-the-device-before-detaching-it-from-the-vm).
## "Device attach failed" error
Upon trying to attach a USB device using the `qvm-usb -a vm-name device-vm-name:device` command, you may face the error `Device attach failed: no device info received, connection failed, check backend side for details`.
This error mainly arises due to problems specific to the particular device, such as the device being incompatible with qvm-usb or a broken cable.
## Attaching device to a qube works, but the device disconnects or disappears upon usage
After attaching a device to a qube, upon attempting to use the device results in the device disappearing or disconnecting. This may be observed by the device no longer existing in the Devices widget or the application within the attached qube indicating the device is no longer found.
As a first line of defense, increase the amount of memory given to the USB VM (sys-usb). High-bandwidth devices such as webcams have been [observed](https://github.com/QubesOS/qubes-issues/issues/6200) to need more memory in sys-usb. If increasing the amount of memory does not resolve the issue, check kernel logs within sys-usb as well as the attached qube for errors before filing a bug report.
## USB VM does not boot after creating and assigning USB controllers to it
This is probably because one of the controllers does not support reset.
In Qubes R2 any such errors were ignored. In Qubes R3.x they are not.
In R4.x, devices that are automatically added to sys-net and sys-usb on install but do not support FLR will be attached with the no-strict-reset option, but see the related warning in the last sentence in this answer.
A device that does not support reset is not ideal and generally should not be assigned to a VM.
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:
```
lspci -nn | grep USB | cut -d '[' -f3 | cut -d ']' -f1 | xargs -I@ setpci -H1 -d @ d0.l=0
```
Errors suggesting this issue:
- in `xl dmesg` 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)
```
- during `qvm-start sys-usb`:
```
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
```
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`):
```
qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0:<BDF>
```
- In Qubes R3.x, by modifying the VM's properties:
```
qvm-prefs usbVM -s pci_strictreset false
```
These options allow the VM to ignore the error and the VM will start.
Please review the notes in the `qvm-prefs` man page and [here](/doc/how-to-use-devices/) and be aware of the potential risks.
## Can't use keyboard or mouse after creating sys-usb
You risk locking yourself out of your computer if you have a USB keyboard and use full disk encryption alongside sys-usb.
On boot, the keyboard may be inactive, preventing you from entering your LUKS decryption password.
When you enable a USB qube, it hides all the USB controllers from dom0, even before it gets started.
So, if your only keyboard is on USB, you should undo this hiding.
To solve the problem, disable the USB qube by not having it autostart, or unassigning your USB controller(s) from it. If you had created the USB qube by checking the box in the installer, then your USB controller(s) are probably hidden from dom0. To unhide them, reverse the procedure described in [how to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-usb-controllers-from-dom0) (i.e., remove `rd.qubes.hide_all_usb` instead of adding it).
Note that this procedure will attach your USB controllers to dom0, so do this only with USB devices you trust.
If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter the LUKS password.
## "qubes-usb-proxy not installed in the VM" error
When trying to [create and use a USB qube](/doc/how-to-use-usb-devices/#creating-and-using-a-usb-qube) with the `qubes-usb-proxy` package, you may receive this error: `ERROR: qubes-usb-proxy not installed in the VM`.
If you encounter this error, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
Depending on your operating system, open a terminal in the template and enter one of the following commands:
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`

119
user/troubleshooting/usb-troubleshooting.rst Normal file
View file

@ -0,0 +1,119 @@
===================
USB troubleshooting
===================
disp-sys-usb does not start
---------------------------
If the disp-sys-usb does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, look at :ref:`PCI passthrough issues <user/troubleshooting/pci-troubleshooting:pci passthrough issues>`.
Can't attach a USB device / USB device not showing in qvm-usb
-------------------------------------------------------------
To successfully attach a USB device, you require a VM dedicated to handling the USB input and output. For guidance setting up a USB qube, see the :ref:`USB documentation <user/how-to-guides/how-to-use-usb-devices:creating and using a usb qube>`.
Currently (until issue `1082 <https://github.com/QubesOS/qubes-issues/issues/1082>`__ gets implemented), if you remove the device before detaching it from the qube, Qubes OS (more precisely, ``libvirtd``) will think that the device is still attached to the qube and will not allow attaching further devices under the same name. This may be characterized by VM manager crashes and the error message: ``Houston, we have a problem``. The easiest way to recover from such a situation is to reboot the qube to which the device was attached. If this isn’t an option, you can manually recover from the situation by following the instructions at the :ref:`Block Devices documentation <user/how-to-guides/how-to-use-block-storage-devices:what if i removed the device before detaching it from the vm?>`.
"Device attach failed" error
----------------------------
Upon trying to attach a USB device using the ``qvm-usb -a vm-name device-vm-name:device`` command, you may face the error ``Device attach failed: no device info received, connection failed, check backend side for details``. This error mainly arises due to problems specific to the particular device, such as the device being incompatible with qvm-usb or a broken cable.
Attaching device to a qube works, but the device disconnects or disappears upon usage
-------------------------------------------------------------------------------------
After attaching a device to a qube, upon attempting to use the device results in the device disappearing or disconnecting. This may be observed by the device no longer existing in the Devices widget or the application within the attached qube indicating the device is no longer found.
As a first line of defense, increase the amount of memory given to the USB VM (sys-usb). High-bandwidth devices such as webcams have been `observed <https://github.com/QubesOS/qubes-issues/issues/6200>`__ to need more memory in sys-usb. If increasing the amount of memory does not resolve the issue, check kernel logs within sys-usb as well as the attached qube for errors before filing a bug report.
USB VM does not boot after creating and assigning USB controllers to it
-----------------------------------------------------------------------
This is probably because one of the controllers does not support reset. In Qubes R2 any such errors were ignored. In Qubes R3.x they are not. In R4.x, devices that are automatically added to sys-net and sys-usb on install but do not support FLR will be attached with the no-strict-reset option, but see the related warning in the last sentence in this answer.
A device that does not support reset is not ideal and generally should not be assigned to a VM.
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
lspci -nn | grep USB | cut -d '[' -f3 | cut -d ']' -f1 | xargs -I@ setpci -H1 -d @ d0.l=0
Errors suggesting this issue:
- in ``xl dmesg`` output:
.. code:: bash
(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)
- during ``qvm-start sys-usb``:
.. code:: bash
internal error: Unable to reset PCI device [...] no FLR, PM reset or bus reset available.
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
qvm-pci attach --persistent --option no-strict-reset=true usbVM dom0:<BDF>
- In Qubes R3.x, by modifying the VM’s properties:
.. code:: bash
qvm-prefs usbVM -s pci_strictreset false
These options allow the VM to ignore the error and the VM will start. Please review the notes in the ``qvm-prefs`` man page and :doc:`here </user/how-to-guides/how-to-use-devices>` and be aware of the potential risks.
Can't use keyboard or mouse after creating sys-usb
--------------------------------------------------
You risk locking yourself out of your computer if you have a USB keyboard and use full disk encryption alongside sys-usb. On boot, the keyboard may be inactive, preventing you from entering your LUKS decryption password.
When you enable a USB qube, it hides all the USB controllers from dom0, even before it gets started. So, if your only keyboard is on USB, you should undo this hiding.
To solve the problem, disable the USB qube by not having it autostart, or unassigning your USB controller(s) from it. If you had created the USB qube by checking the box in the installer, then your USB controller(s) are probably hidden from dom0. To unhide them, reverse the procedure described in :ref:`how to hide USB controllers from dom0 <user/advanced-topics/usb-qubes:how to hide usb controllers from dom0>` (i.e., remove ``rd.qubes.hide_all_usb`` instead of adding it).
Note that this procedure will attach your USB controllers to dom0, so do this only with USB devices you trust.
If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter the LUKS password.
"qubes-usb-proxy not installed in the VM" error
-----------------------------------------------
When trying to :ref:`create and use a USB qube <user/how-to-guides/how-to-use-usb-devices:creating and using a usb qube>` with the ``qubes-usb-proxy`` package, you may receive this error: ``ERROR: qubes-usb-proxy not installed in the VM``.
If you encounter this error, you can install the ``qubes-usb-proxy`` with the package manager in the VM you want to attach the USB device to. Depending on your operating system, open a terminal in the template and enter one of the following commands:
- Fedora: ``sudo dnf install qubes-usb-proxy``
- Debian/Ubuntu: ``sudo apt-get install qubes-usb-proxy``

92
user/troubleshooting/vm-troubleshooting.md
View file

@ -1,92 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/vm-troubleshooting/
redirect_from:
- /doc/remove-vm-manually/
ref: 223
title: Qube troubleshooting
---
## VM Kernel troubleshooting
This troubleshoot applies to the non-default kernel choice described in the [Managing VM docs](/doc/managing-vm-kernels/#using-kernel-installed-in-the-vm).
In case of problems, you can access the VM console using `qvm-console-dispvm VMNAME` in dom0, then access the GRUB menu.
You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window.
In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`).
You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.
## Qubes starts, but no VMs load
First, try to start a particular VM, check any failure message and direct further steps based on that.
This issue has been seen to occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted.
## Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name”
All of the following commands should be executed in a dom0 terminal.
When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template:
1. Check the state of `installed_by_rpm`
```
$ qvm-prefs template-vm-name
```
2. If `installed_by_rpm - True`, mark the template as not installed by package manager
```
$ qvm-prefs template-vm-name installed_by_rpm false
```
3. Re-check the state of `installed_by_rpm`
- If `installed_by_rpm - False`, remove the template like you would a regular qube:
```
$ qvm-remove template-vm-name
```
- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template.
## Fixing package installation errors
By default, templates in 4.0 only have a loopback interface.
Some packages will throw an error on installation in this situation.
For example, Samba expects to be configured using a network interface post installation.
One solution is to add a dummy interface to allow the package to install correctly:
```
ip link add d0 type dummy
ip addr add 192.168.0.1/24 dev d0
ip link set d0 up
```
## "Cannot connect to qrexec agent" error
If you face this error when starting a VM, look into the VM logs at `/var/log/xen/console/guest-VMNAME.log`.
Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup.
If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory.
## "No match found" when trying to install a template
For example:
```
[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...
No Match for argument qubes-template-debian-10
Nothing to download
```
This normally means you already have the template installed.
It may be that you have the matching package installed, but you removed or renamed the template.
Check `rpm -q qubes-template-<name>`.
If it lists the package, but you don't really have the template present (`qvm-ls` doesn't list it), you need to clean up leftovers of the package with `rpm -e --noscripts qubes-template-<name>`, then install it normally.

106
user/troubleshooting/vm-troubleshooting.rst Normal file
View file

@ -0,0 +1,106 @@
====================
Qube troubleshooting
====================
VM Kernel troubleshooting
-------------------------
This troubleshoot applies to the non-default kernel choice described in the :ref:`Managing VM docs <user/advanced-topics/managing-vm-kernels:using kernel installed in the vm>`.
In case of problems, you can access the VM console using ``qvm-console-dispvm VMNAME`` in dom0, then access the GRUB menu. You need to call it just after starting the VM (until ``GRUB_TIMEOUT`` expires); for example, in a separate dom0 terminal window.
In any case you can later access the VM’s logs (especially the VM console log ``/var/log/xen/console/guest-VMNAME.log``).
You can always set the kernel back to some dom0-provided value to fix a VM kernel installation.
Qubes starts, but no VMs load
-----------------------------
First, try to start a particular VM, check any failure message and direct further steps based on that.
This issue has been seen to occur if a dom0 update is interrupted halfway through and/or a hard power off is done without shutting down Qubes, which results in files getting corrupted.
Can not uninstall a VM / "ERROR: VM installed by package manager: template-vm-name"
-----------------------------------------------------------------------------------
All of the following commands should be executed in a dom0 terminal.
When a template is marked as ‘installed by package manager’, but cannot be uninstalled there, trying to uninstall manually will result in the error “ERROR: VM installed by package manager: template-vm-name”. Do as follows to be able to uninstall the template:
1. Check the state of ``installed_by_rpm``
.. code:: bash
$ qvm-prefs template-vm-name
2. If ``installed_by_rpm - True``, mark the template as not installed by package manager
.. code:: bash
$ qvm-prefs template-vm-name installed_by_rpm false
3. Re-check the state of ``installed_by_rpm``
- If ``installed_by_rpm - False``, remove the template like you would a regular qube:
.. code:: bash
$ qvm-remove template-vm-name
- If ``installed_by_rpm`` remains ``True``, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template.
Fixing package installation errors
----------------------------------
By default, templates in 4.0 only have a loopback interface.
Some packages will throw an error on installation in this situation. For example, Samba expects to be configured using a network interface post installation.
One solution is to add a dummy interface to allow the package to install correctly:
.. code:: bash
ip link add d0 type dummy
ip addr add 192.168.0.1/24 dev d0
ip link set d0 up
"Cannot connect to qrexec agent" error
--------------------------------------
If you face this error when starting a VM, look into the VM logs at ``/var/log/xen/console/guest-VMNAME.log``. Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup.
If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory.
"No match found" when trying to install a template
--------------------------------------------------
For example:
.. code:: bash
[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...
No Match for argument qubes-template-debian-10
Nothing to download
This normally means you already have the template installed. It may be that you have the matching package installed, but you removed or renamed the template. Check ``rpm -q qubes-template-<name>``. If it lists the package, but you don’t really have the template present (``qvm-ls`` doesn’t list it), you need to clean up leftovers of the package with ``rpm -e --noscripts qubes-template-<name>``, then install it normally.

51
user/troubleshooting/vpn-troubleshooting.md
View file

@ -1,51 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/vpn-troubleshooting/
ref: 240
title: VPN troubleshooting
---
## Tips
* If using qubes-vpn, check the VPN service's log in the VPN VM by running:
~~~
sudo journalctl -u qubes-vpn-handler
~~~
* Always test your basic VPN connection before adding scripts.
* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.
## VPN does not reconnect after suspend
This applies when using OpenVPN.
After suspend/resume, OpenVPN may not automatically reconnect. In order to get it to work, you must kill the OpenVPN process and restart it.
## VPN stuck at "Ready to start link"
After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected.
To figure out the root of the problem, check the VPN logs in `/var/log/syslog` or use `journalctl`. The logs may reveal issues like missing OpenVPN libraries, which you can then install.
## `notify-send` induced failure
[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:
```
Failed to execute child process “dbus-launch” (No such file or directory)
```
To check this tool is working properly run:
```bash
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:
1. Remove all calls to `notify-send` from scripts you are using to start VPN
2. Use another template qube that has a working `notify-send` or find proper guide and make your current template run `notify-send` work properly.

67
user/troubleshooting/vpn-troubleshooting.rst Normal file
View file

@ -0,0 +1,67 @@
===================
VPN troubleshooting
===================
Tips
----
- If using qubes-vpn, check the VPN service’s log in the VPN VM by running:
.. code:: bash
sudo journalctl -u qubes-vpn-handler
- Always test your basic VPN connection before adding scripts.
- Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
- Use ``iptables -L -v`` and ``iptables -L -v -t nat`` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.
VPN does not reconnect after suspend
------------------------------------
This applies when using OpenVPN.
After suspend/resume, OpenVPN may not automatically reconnect. In order to get it to work, you must kill the OpenVPN process and restart it.
VPN stuck at "Ready to start link"
----------------------------------
After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup “Ready to start link”, but the VPN isn’t connected.
To figure out the root of the problem, check the VPN logs in ``/var/log/syslog`` or use ``journalctl``. The logs may reveal issues like missing OpenVPN libraries, which you can then install.
``notify-send`` induced failure
-------------------------------
`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
Failed to execute child process “dbus-launch” (No such file or directory)
To check this tool is working properly run:
.. code:: bash
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:
1. Remove all calls to ``notify-send`` from scripts you are using to start VPN
2. Use another template qube that has a working ``notify-send`` or find proper guide and make your current template run ``notify-send`` work properly.