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

Correct code-block lexers

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

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

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

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

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

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

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

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

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

@ -52,7 +52,7 @@ In dom0, the ``qvm-appmenus`` tool allows the user to see the list of available
To change the whitelist shown in app menu, you need to provide a list of the desktop entries. Each line contains a desktop entry name, with its ``.desktop`` extension, like this:
.. code:: bash
.. code:: console
qubes-open-file-manager.desktop
qubes-run-terminal.desktop
@ -78,7 +78,7 @@ You can manually create new entries in the “available applications” list of
2. Create a custom ``.desktop`` file in ``/usr/share/applications`` (you may need to first create the subdirectory). Look in ``/usr/share/applications`` for existing examples, or see the full `file specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>`__. It will be something like:
.. code:: bash
.. code:: desktop
[Desktop Entry]
Type=Application
@ -111,7 +111,7 @@ To add a custom menu entry instead:
4. Add a custom menu entry referring to your newly created ``.desktop`` file.
.. code:: bash
.. code:: xml
<Menu>
<Name>Webmail</Name>
@ -178,7 +178,7 @@ First, check in the corresponding ``.desktop`` file in ``~/.local/share/qubes-ap
The line starting with ``Exec=`` points out the exact command run by dom0 to start the application. It should be something like:
.. code:: bash
.. code:: desktop
Exec=qvm-run -q -a --service -- <QUBE_NAME> qubes.StartApp+<APPLICATION_NAME>
@ -206,7 +206,7 @@ The whitelist given to ``qvm-appmenu --set-whitelist`` is stored as a feature ca
Actual command lines for the menu shortcuts involve the ``qvm-run`` command which starts a process in another domain. Examples:
.. code:: bash
.. code:: console
qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox
qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager
@ -215,7 +215,7 @@ Actual command lines for the menu shortcuts involve the ``qvm-run`` command whic
Note that you can create a shortcut that points to a ``.desktop`` file in your app qube with e.g.:
.. code:: bash
.. code:: console
qvm-run -q -a --service -- personal qubes.StartApp+firefox
@ -226,7 +226,7 @@ While this works well for standard applications, creating a menu entry for Windo
**Note:** Applications installed under *wine* are installed in AppVMs, not in the template on which these AppVMs are based, as the file structure used by *wine* is stored under ``~/.wine``, which is part of the persistent data of the AppVM and not inherited from its template.
.. |image1| image:: /attachment/doc/r4.0-dom0-menu.png
.. |image2| image:: /attachment/doc/r4.0-dom0-appmenu-select.png

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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