Git-Mirrors/Qubes-Community-Content
1
0
Fork 0
mirror of https://github.com/Qubes-Community/Contents.git synced 2025-05-02 22:35:23 -04:00
Code Issues Projects Releases Packages Wiki Activity

Rename directories to match target repo structure

Browse source
This commit is contained in:
Andrew David Wong 2020-12-07 20:00:31 -08:00
parent c7f785452a
commit 0c3f3bacfa
No known key found for this signature in database
GPG key ID: DB4DD3BC39503030
50 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

45
docs/troubleshooting/application-troubleshooting.md Normal file
View file

@ -0,0 +1,45 @@
---
layout: doc
title: Application Troubleshooting
permalink: /doc/application-troubleshooting/
---
# Troubleshooting default applications on Qubes #
## Fullscreen Firefox is frozen ##
Press F11 twice.
## Firefox crashes ##
If you are facing frequent crashes or lags when using Firefox browser (especially when watching videos), you may need to turn off Hardware Acceleration. You can do this by navigating to "Preferences", then "Performance". Untick the "Use recommended performance settings" checkbox, followed by "Use hardware acceleration when available".
If this doesn't fix the issue, try turning off smooth scrolling by unticking "Use smoothing scrolling" under the "Browsing" section.
## LibreOffice open as a tiny window ##
Some programs like LibreOffice open as a tiny window -- small enough that the content of the file is not even visible.
You can open LibreOffice as a larger window using this workaround:
### Using the command line
1. In the VM where you want to open the LibreOffice, open the `registrymodifications.xcu` file in an editor:
~~~
sudo nano ~/.config/libreoffice/4/user/registrymodifications.xcu
~~~
2. Find the lines containing `ooSetupFactoryWindowAttributes`. It will look like this:
~~~
<item oor:path="/org.openoffice.Setup/Office/Factories/org.openoffice.Setup:Factory['com.sun.star.sheet.SpreadsheetDocument']"><prop oor:name="ooSetupFactoryWindowAttributes" oor:op="fuse"><value>61,61,1807,982;5;38,56,1807,982;</value></prop></item>
~~~
3. We are interested in the values between the `<value>` tag. These window position values are specified as: `x-pos,y-pos,width,height ; window-state ; maximized-x-pos,maximized-y-pos,maximized-width,maximized-height`. Edit the third and fourth values to your desired width and height (for example, to 1800 and 900).
4. Do this once for every template and the program will always open at this size.
### Using the GUI
1. Open any Libreoffice app.
2. Navigate to the "Tools" menu, select "Options", then "Advanced". Click the "Open Expert Configuration" button.
3. Search for "ooSetupFactoryWindowAttributes".
4. Scroll right to see the values set for each component as a string value. For example: `61,61,1807,982;5;38,56,1807,982;`. These window position values are specified as: `x-pos,y-pos,width,height ; window-state ; maximized-x-pos,maximized-y-pos,maximized-width,maximized-height`. Edit the third and fourth values to your desired width and height (for example, to 1800 and 900).
5. Do this once for every template and the program will always open at this size.

65
docs/troubleshooting/intel-igfx-troubleshooting.md Normal file
View file

@ -0,0 +1,65 @@
---
layout: doc
title: Intel Integrated Graphics Troubleshooting
permalink: /doc/intel-igfx-troubleshooting/
---
# Intel Integrated Graphics Troubleshooting #
## Software Rendering or Video Lags
If you are experiencing this issue, you will see extremely slow graphics updates.
You will be able to watch the screen and elements paint slowly from top to bottom.
You can confirm this is the issue by looking for a line similar to the following in your `/var/log/Xorg.0.log` file:
[ 131.769] (EE) AIGLX: reverting to software rendering
Newer versions of the Linux kernel have renamed the `i915.preliminary_hw_support=1` option to `i915.alpha_support=1`, so if you needed this kernel option in the past you will have to rename it or add it to your configuration files (follow either GRUB2 or EFI, not both):
* GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and
Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
* EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s)
## IOMMU-related issues ##
Dom0 Kernels currently included in Qubes have issues related to VT-d (IOMMU) and some versions of the integrated Intel Graphics Chip.
Depending on the specific hardware / software combination the issues are quite wide ranging, from apparently harmless log errors, to VM window refresh issues, to complete screen corruption and crashes rendering the machine unusable with Qubes.
Such issues have been reported on at least the following machines:
* HP Elitebook 2540p
* Lenovo x201
* Lenovo x220
* Thinkpad T410
* Thinkpad T450s
Log errors only on :
* Librem 13v1
* Librem 15v2
The installer for Qubes 4.0 final has been updated to disable IOMMU for the integrated intel graphics by default.
However, users of 3.2 may experience issues on install or on kernel upgrades to versions higher than 3.18.x.
Disabling IOMMU for the integrated graphics chip is not a security issue, as the device currently lives in dom0 and is not passed to a VM.
This behaviour is planned to be changed as of Qubes 4.1, when passthrough capabilities will be required for the GUI domain <sup id="a1-1">[1](#f1)</sup>.
## Workaround for existing systems with VT-d enabled (grub / legacy mode) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/etc/default/grub` (e.g. `sudo nano /etc/default/grub`)
3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit
4. Commit the change with`sudo grub2-mkconfig --output /boot/grub2/grub.cfg`
## Workaround for existing systems with VT-d enabled (UEFI) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/boot/efi/EFI/qubes/xen.cfg` (e.g. `sudo nano /boot/efi/EFI/qubes/xen.cfg`)
3. Add to the line `options` the setting `iommu=no-igfx`, save and quit
<b name="f1">1</b> <https://github.com/QubesOS/qubes-issues/issues/2841> [↩](#a1-1)

241
docs/troubleshooting/macbook-troubleshooting.md Normal file
View file

@ -0,0 +1,241 @@
---
layout: doc
title: Apple MacBook Troubleshooting
permalink: /doc/macbook-troubleshooting/
---
# Apple MacBook Troubleshooting
## System freezes after attaching Broadcom BCM43602 Wi-Fi card
You may experience system freezes or crashes after attaching a Broadcom Wi-Fi adapter to the sys-net VM. This issue has been reported to exist on both Qubes 3.2 and 4.0.
### Qubes 3.2
To fix this issue on Qubes 3.2:
1. During VM setup, force a reboot and press `OPTION` key.
2. You will reach the grub shell
~~~
configfile /EFI/qubes/grub.cfg
~~~
3. Press Fn+F10 to boot without XEN support.
4. Once booted, press Fn+CTRL+ALT+F4 to open a shell.
5. Log into the system
~~~
sudo su -
systemctl disable qubes-netvm
~~~
6. Press Fn+F2 and complete the setup.
7. Reboot Qubes.
8. DO NOT launch the sys-net qube.
Rather, open its setting and remove the Wi-Fi adapter from the Selected devices using the Qubes Manager.
You can also remove it from the command line, if you know the BDF of the adapter.
You can see the list of devices attached to sys-net and their associated BDFs by running:
~~~
qvm-pci -l sys-net
~~~
For a device with a BDF of `04:00.0`, you can remove it with:
~~~
qvm-pci -d sys-net 04:00.0
~~~
9. In a dom0 terminal, run:
~~~
sudo su -
xl pci-assignable-list
echo 04:00.0 > /sys/bus/pci/drivers/pciback/permissive
qvm-start sys-net
xl pci-attach sys-net DEVICE_BDF
~~~
Be sure to replace "DEVICE_BDF" with the actual BDF of the Wi-Fi adapter.
After following the above steps, you should be able to launch sys-net with Wi-Fi access. These steps can be automated in a custom `systemd` service.
### Qubes 4.0
For Qubes 4.0, you may have to remove the wireless card from sys-net or replace it, as described in the [PCI Troubleshooting](/doc/pci-troubleshooting/#broadcom-bcm43602-wi-fi-card-causes-system-freeze) guide.
It is a bit tricky to execute, but you may be able to successfully attach a Broadcom BCM43602 to sys-net by executing the `attach` command immediately after starting sys-net. Follow these steps:
1. Disable "Start qube automatically on boot" for sys-net and sys-firewall in the Qubes Manager.
2. Manually start sys-net using the `qvm-start sys-net` command.
3. Immediately (About 2 seconds later) after stating sys-net, attach the device to sys-net using permissive mode:
`sudo xl pci-attach sys-net 'DEVICE_BDF,permissive=1`
Replace `DEVICE_BDF,` with the BDF of your wireless card. If you can immediately attach the device to sys-net while it is still starting up, it could work. If it is attached too late, the VM doesn't seem to detect it.
You can use the following script to do the above steps quickly after each boot:
~~~
#!/bin/bash
qvm-start sys-net &
sleep 3
sudo xl pci-attach sys-net '03:00.0,permissive=1'
~~~
## Broadcom BCM4360 doesn't work in a Fedora-based qube
Several people have been unable use the Broadcom BCM4360 Wireless card on a Fedora-based qube. This issue appears to be [related to Fedora](https://ask.fedoraproject.org/t/cant-connect-to-wifi-after-update-bcm4360-with-broadcom-wl-driver/482?page=2), not Qubes.
To get internet access in sys-net, try shutting down all your VMs, then changing sys-net to use the Debian 10 template. Finally, install the [broadcom-sta-dkms](https://pkgs.org/download/broadcom-sta-dkms) package.
## Boot freezes at "Setting up networking"
After installing Qubes 3.2 on a MacBook Air 13" mid-2011 (MacBookAir 4,2), it may freeze at "Setting up networking" during booting. This issue is caused by the Broadcom Wireless adapter, if you have one.
To fix the problem, you need to [remove the Wi-Fi card from your Mac][bluetooth-replacement] or put the Wi-Fi adapter into PCI passthrough, as explained below:
1. Run in a terminal:
~~~
# diskutil list
(find your usb device)
# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition
# reboot
~~~
2. Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up.
Select Troubleshooting and Boot the Rescue image. Enter your disk password when
prompted. Select continue and after mounting the HD filesystem and launching a
shell, `chroot` as instructed.
3. Find your Wi-Fi card:
~~~
# lspci
...
02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01)
~~~
In the above example, the device has a BDF of `02:00.0`.
To assign this device to the sys-net VM:
~~~
# qvm-pci -a sys-net 02:00.0
~~~
4. Create `/etc/systemd/system/qubes-pre-netvm.service` with:
~~~
[Unit]
Description=Netvm fix for Broadcom
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
~~~
5. To enable the `qubes-pre-netvm` services, run:
~~~
systemctl enable qubes-pre-netvm.service
~~~
6. After reboot, boot Mac OS X again by running in a terminal:
~~~
# diskutil list
(find the HD device where you installed Qubes)
# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition
# reboot
~~~
## Can't boot the installer
You can install Qubes 3.2 on a MacBook Pro Retina, 15 inch, Mid-2015 (MacBookPro 11,5) using BIOS or UEFI (If one method fails, try the other):
* BIOS/CSM/Legacy
* UEFI plain: Here, the grub menu appears, but any gives a quick flash and returns the main menu. Then, you can boot it manually and fix the `grub.cfg` file by adding the commands `linuexefi` and `initrdefi` and pointing to the proper files in `/efi/boot`. After boot, you may end up with no root file system.
* UEFI, using rEFInd: This method may prove successful, but there are some issues to be fixed manually after the installation is complete.
1. Download [rEFInd] refind-bin-0.10.4.zip. Note that this file is not signed, so decide if you trust it or not. The SHA1 sum is 3d69c23b7d338419e5559a93cd6ae3ec66323b1e
2. Unzip it and run the installer, which installs rEFInd on the internal SSD
3. If installation fails due to SIP, reboot in recovery mode, open a terminal and run the command:
~~~
csrutil disable
~~~
4. Reboot. You will see some icons.
5. Choose Boot EFI\BOOT\xen.efi from ANACONDA. After a while, the graphical installer is up (keyboard and touchpad working)
## Can't boot using GRUB2
After installing Qubes 3.2 on a MacBook Mid-2015, you may be unable to boot using `EFI/qubes/xen.efi` because the [XEN bootloader configuration is broken](/doc/macbook-troubleshooting/#cant-boot-using-xen-bootloader).
You can't also boot using GRUB2 without XEN support because the GRUB configuration is broken as well.
To start fixing this issue manually, switch to the console by pressing Fn+CTRL+ALT+F2.
It can be very useful – during troubleshooting – to have a rescue system at hand. It could help you boot Qubes, even without XEN support. This troubleshoot assumes you are performing a [UEFI boot, using rEFInd](/doc/macbook-troubleshooting/#cant-boot-the-installer).
At this point, the GRUB configuration file is using some wrong commands, which are not compatible with grub2-efi
~~~
chroot /mnt/sysimage
sed -i.bak -e "s/multiboot/chainloader/" -e "s/module.*--nounzip/initrdefi/" -e "s/module/linuxefi/" /etc/grub.d/20_linux_efi
exit
~~~
Now, despite XEN configuration is still broken, you have a rescue system booting vmlinux from rEFInd screen.
TBV1: chainloading XEN does not work, unless you specify the right disk prefix, eg: (hd1,gpt4)
TBV2: grub.cfg set the wrong disk in "set root" command
TBV3: in case you reach grub shell, you can
~~~
ls
~~~
and also reload config file and change it manually before booting
~~~
configfile /EFI/qubes/grub.cfg
~~~
Then press "e", edit `grub.cfg` and boot by pressing Fn+F10.
## Can't boot using XEN bootloader
You may be unable to boot Qubes 3.2 using `EFI/qubes/xen.efi` on a MacBook Mid-2015 because the XEN bootloader configuration is broken. This issue is accompanied by the GRUB2 configuration being broken as well. After [fixing the GRUB configuration](/doc/macbook-troubleshooting/#cant-boot-using-grub2), follow the following steps to fix the bootloader. This troubleshoot assumes you are performing a [UEFI boot, using rEFInd](/doc/macbook-troubleshooting/#cant-boot-the-installer).
* Fix grub2 configuration, which uses wrong command for EFI boot
* Analyzing `/mnt/sysimage/var/log/anaconda/program.log`, you may find the faulty commands issued by the Anaconda installer.
~~~
chrooot /mnt/sysimage
~~~
* Edit the `/boot/efi/EFI/qubes/xen.cfg` file to add the following content:
~~~
[global]
default=4.4.14-11.pvops.qubes.x868_64
[4.4.14-11.pvops.qubes.x868_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
~~~
* The main mistake is that `efibootmgr` needs the right commands. Just in case, reapply all the commands, adapting them to your own disk layout (`-d /dev/sdxxx -p partition_number`)
~~~
grep Running /mnt/sysimage/var/log/anaconda/program.log | tail -n 20
efibootmgr -b 0000 -B
efibootmgr -c -w -L Qubes -d /dev/sda -p 4 -l \\EFI\\qubes\\xen-4.6.1.efi
/usr/libexec/mactel-boot-setup
kernel-install add 4.4.14-11.pvops.qubes.x86_64 /boot/vmlinuz-4.4.14-11.pvops.qubes.x86_64
systemctl disable qubes-netvm
reboot
~~~
At the rEFInd screen, choose Boot EFI/qubes/xen-4.6.1.efi.
Everything should now be ok, Qubes OS boots using EFI and you will get the last setup screen.
Select "Qubes OS", do not change anything and click on "Done".
VMs are created, including NetVM.
## System freezes often for 20 seconds
Using Qubes 3.2 on the MacBook Mid-2015 was reported to have frequent freezes, which lasts for 20 seconds. Upon looking at the `journalctl` output, you may see that pulseaudio locks the CPU for 20 seconds, very often.
To fix this issue, kill audio support with this quick workaround:
1. Open a dom0 terminal as root
2. Edit `/etc/pulse/client.conf` and add `autospawn = no`
3. As normal user, kill pulseaudio with the command `pulseaudio --kill`
[bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360
[rEFInd]: http://www.rodsbooks.com/refind/getting.html

225
docs/troubleshooting/nvidia-troubleshooting.md Normal file
View file

@ -0,0 +1,225 @@
---
layout: doc
title: Nvidia Troubleshooting
permalink: /doc/nvidia-troubleshooting/
redirect_from:
- /en/doc/nvidia-troubleshooting/
- /doc/NvidiaTroubleshooting/
- /wiki/NvidiaTroubleshooting/
---
# Nvidia Troubleshooting Guide
## System freezes during boot / Graphical login manager is not visible
If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a workaround so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects".
### Boot in failsafe
Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel.
If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you.
### Configure X with nouveau
Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps...
1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2)
2. Log in as root
3. Switch to runlevel 3 (this should kill your X server):
~~~
init 3
~~~
4. Run X-autoconfiguration:
~~~
Xorg -configure
~~~
This should generate a file `xorg.conf.new` in the `/root` directory.
In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file.
5. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications:
First, uncomment the ShadowFB option, so that you should now have something like this:
~~~
Option "ShadowFB" # [<bool>]
~~~
Second, change the driver name to `nouveau` (you will probably have `nv` written there):
~~~
Driver "nouveau"
~~~
Save the modification, exit the editor.
6. Move the file to `/etc/X11` and rename it as `xorg.conf`:
~~~
mv /root/xorg.conf.new /etc/X11/xorg.conf
~~~
7. Verify that X will work with those new settings:
~~~
xinit
~~~
If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them).
8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now.
## Boot failure after GRUB menu / System freezes followed by reboot
If Qubes fails to properly boot after the GRUB Boot menu and you are stuck on a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly.
One way to get rid of this for now is to disable nouveau.
### Disabling Nouveau
Example error:
~~~
nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout
nouveau E[ PGRAPH][0000:01:00.0] failed to construct context
nouveau E[ PGRAPH][0000:01:00.0] init failed, -16
~~~
Tip: In case you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should ensure that you're using the integrated graphics card instead of the nvidia graphics card.
If you're seeing this error then that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support altogether.
#### EFI
1. Open a terminal in dom0.
2. To edit the `xen.cfg` file using the `nano` editor:
~~~
sudo nano /boot/efi/EFI/qubes/xen.cfg
~~~
3. Locate the three `kernel=` lines. Press the left/right arrow keys to position the cursor at the end of the lines, after `rhgb quiet`.
4. Add the following:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
This will disable nouveau until the option is manually edited back to its original state.
5. Press the `Ctrl+X` keys, then `y` to save changes.
6. Reboot
#### GRUB
1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast.
~~~
Qubes
Qubes with advanced Xen options
~~~
2. Quickly press the "E" key before the time is up.
3. An editor will open up that allows you to temporarily change the grub options for the next boot.
4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options will look like this:
~~~
module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet
~~~
It is not an exact copy as it may differ from system to system.
Please note: choose the module that starts with `vmlinux`!
5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case.
6. Add the following:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
This will temporarily disable nouveau until next boot.
7. Press either the F10 key or Ctrl+X to start the boot process.
Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau.
You'll have to do the following to make this change persistent, so that it will work properly on every boot :
1. Open a terminal (do this by clicking on Q > 'run command' > type 'terminal' and hit enter)
2. type following commands:
~~~
cd /etc/default/
sudo nano grub
~~~
3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
4. ctrl + X and then y to save the file.
5. The final step is to compile the configuration file to something the bootloader can read.
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
## Lack of video output during Nvidia driver installation
Specifically, the notes below are aimed to help when during Nvidia driver installation, the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules.
### Initial setup.
*Note*: The steps below do *not* produce a fully-functional Qubes OS install. Rather, only a dom0 instance is functional, and there is no networking there. However, they can be used to gather data in order to troubleshoot video card issues and/or possible other basic kernel module issues.
1. Append `nomodeset ip=dhcp inst.nokill inst.vnc` to the kernel command line. Remove `rhgb` and `quiet` to see the kernel messages scroll by, which may help in further diagnostics.
* If DHCP is not available on the installation network, the syntax becomes a bit more involved. The full list of variants is documented in the [Dracut Command-line parameters] (http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html)
2. The VGA console should switch into the installer's multi-virtual-terminal display. VNC may take a number of minutes to start, please be patient.
* Using the anaconda installer interface, switch to the "shell" TTY (ALT-F2), and use `ip a` command to display the IP addresses.
3. Using the Connect to the IP (remember the :1) using a VNC viewer.
4. Follow the installation UI.
* Since this won't be a usable install, skipping LUKS encryption is an option which will simplify this troubleshooting process.
* Do *not* reboot at the end of the installation.
5. Once the installation completes, use the local VGA console switch to TTY2 via ALT-F2
* Switch to the chroot of the newly-installed system via `chroot /mnt/sysinstall`
* Set the root password (this will also enable the root account login)
* Double-check that `/boot/grub2/grub.cfg` contains a `nomodeset` kernel parameter.
* Exit out of the chroot environment (`exit` or CTRL-D)
6. Reboot
*Note* If the kernel parameters do *not* include `quiet` and `rhgb`, the kernel messages can easily obscure the LUKS passphrase prompt. Additionally, each character entered will cause the LUKS passphrase prompt to repeat onto next line. Both of these are cosmetic. The trade-off between kernel messages and the easy-to-spot LUKS passphrase prompt is left as an exercise to the user.
### Gather initial `dmesg` output
If all is well, the newly-installed Qubes OS instance should allow for user root to log in.
Run `dmesg > dmesg.nomodeset.out` to gather an initial dmesg output.
### Gather the 'video no worky' `dmesg` output
1. Reboot and interrupt the Grub2's process, modifying the kernel parameters to no longer contain `nomodeset`.
* If the LUKS passphrase was set, blindly enter it.
2. Wait for the system to finish booting (about 5 minutes, typically).
3. Blindly switch to a TTY via CTRL-ALT-F2.
4. Blindly log in as user root
5. Blindly run `dmesg > dmesg.out`
6. Blindly run `reboot` (this will also serve to confirm that logging in as root, and running commands blindly is possible rather than, say, the kernel having hung or some such).
* Should this step fail, perhaps by the time step #3 was undertaken, the OS hasn't finished coming up yet. Please retry, possibly with a different TTY (say, 3 or 4 - so CTRL-ALT-F3?)
### Exfiltrate the dmesg outputs
Allow the system to boot normally, log in as user root, and sneakernet the files off the system for analysis, review, bug logging, et cetera.

58
docs/troubleshooting/sony-vaio-tinkering.md Normal file
View file

@ -0,0 +1,58 @@
---
layout: doc
title: Sony Vaio Tinkering
permalink: /doc/sony-vaio-tinkering/
redirect_from:
- /en/doc/sony-vaio-tinkering/
- /doc/SonyVaioTinkering/
- /wiki/SonyVaioTinkering/
---
Instructions for getting your Sony Vaio Z laptop working with Qubes/Linux
=========================================================================
The following issues were reported on Qubes 3.2 and may not be prevalent on Qubes 4.0.
Graphics card does not work
---------------------------
Newer models of Sony Vaio Z come with an "intelligent" GPU switch, that automatically chooses either Intel Integrated GPU (IGD) or the discrete NVIDIA GPU. This confuses the Linux graphics so much, that in most cases, it won't even be able to install a regular Linux on such a machine. Unfortunately, moving the switch into the "Stamina" position apparently doesn't work, and the automatic GPU switching is still active.
One solution that actually worked for me was to reflash the BIOS (I know, I know, this is scary) and to enable the so called "Advanced Menu" in the BIOS. This Advanced Menu allows you to choose the desired behaviour of the GPU switch, which in our case would be to set it to "Static" and then move the mechanical switch to the "Stamina" position, that enabled the Intel IGD (which is much better supported on Linux).
If you think you are ready to reflash you BIOS, you can follow [these instructions](http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html).
**WARNING**: We take absolutely no responsibility that the BIOS reflashing instructions given at the referenced forum are 1) valid, 2) non-malicious, and 3) work at all. Do this step at your own risk. Keep in mind that reflashing your BIOS might yield your system unusable. If you don't feel like taking this risk (which is a reasonable state of mind), look for a different notebook, or ask Sony Support to enable this option for you.
In practice I have downloaded the BIOS-patching tools, run them in a VM on a BIOS image I extracted from my laptop, diffed the two versions, and concluded that it doesn't *seem* malicious, and then bravely applied the patched image. If you don't know what are you doing, just get a different laptop, really!
On a side note, we should note that allowing anybody to reflash the BIOS is really a bad idea from a security point of view (Hello Evil Maids!). Shame on you, Sony!
Touchpad does not work during installation
------------------------------------------
In order to get the touchpad working during installation you should pass the `i8042.nopnp=1` option to the kernel before the installer starts:
~~~
sudo nano /etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT="i8042.nopnp=1"
~~~
Applying other fixes
--------------------
There are a few more fixes needed for Sony Vaio Z, and we have prepared a special package that you can install in dom0 that applies them all. After the installation is complete, open a console in dom0 and do the following:
~~~
$ sudo bash
# qvm-dom0-networking up
# yum install qubes-core-dom0-vaio-fixes
# reboot
~~~
This script takes care about the following:
- Setting i8042.nopnp for your installed system
- Adding special option for the sound module (so you can get sound)
- Adding pm-suspend scripts that take care about restoring your screen after resume

33
docs/troubleshooting/tails-troubleshooting.md Normal file
View file

@ -0,0 +1,33 @@
---
layout: doc
title: Tails Troubleshooting
permalink: /doc/tails-troubleshooting/
---
# Tails Troubleshooting Guide #
## Black screen during startup
This was reported with earlier versions of Tails -- the problem should now be fixed.
If you do encounter a black screen during Tails startup, you can try to constrain display settings by appending vga codes to the Tails boot parameters.
If you do not know the codes, append `vga=999`, and a helpful prompt will appear.
Note: Tails 2.3 does not appear to honour the vga code.
## Window extends beyond the bottom of the screen
This problem seems to arise because Tails sizes to the height of the screen, but there is a title bar at the top of the window.
Either remove the title bar altogether, or move the window upwards using ALT+drag.
## Persistent tools do not work
The persistence tools, such as persistent volume, may not work because Tails has not been launched from USB.
The HVM disk(s) can be configured and mounted from within Tails to provide persistent storage.
If you want to use an existing USB persistent volume:
1. Interrupt the Tails vm boot process with arrow-up when the grub boot menu appears.
2. In dom0 attach the USB drive containing the persistent volume to the Tails VM.
3. Continue booting Tails. Tails-greeter will detect the encrypted partition on the attached USB.
4. Unlock the persistent volume in Tails-greeter and use it as normal.
## Tails qube doesn't shut down cleanly
If the Tails qube will not shut down cleanly, you can kill it from the GUI Manager or enter ```qvm-kill Tails``` in the console.

94
docs/troubleshooting/thinkpad-troubleshooting.md Normal file
View file

@ -0,0 +1,94 @@
---
layout: doc
title: Lenovo ThinkPad Troubleshooting
permalink: /doc/thinkpad-troubleshooting/
redirect_from:
- /doc/thinkpad_x201/
- /en/doc/thinkpad_x201/
- /doc/Thinkpad_X201/
- /wiki/Thinkpad_X201/
- /doc/lenovo450-tinkering/
- /en/doc/lenovo450-tinkering/
- /doc/Lenovo450Tinkering/
- /wiki/Lenovo450Tinkering/
---
# Lenovo ThinkPad Troubleshooting #
## Installation from USB stick fails for newer (UEFI-only) ThinkPads ##
Some newer ThinkPads (e.g. T470, T470p, [P51](https://www.svensemmler.org/blog/2017/12/17/qubes-on-thinkpad-p51.html), ThinkPad 25, but not the [P53](https://github.com/QubesOS/qubes-issues/issues/5851)) are likely to fail installation attempts made from a USB stick that was created with dd or Rufus, and even from a DVD burned using official ISO images - if the ThinkPad is configured for UEFI boot. If you don't want to use Legacy Mode as a workaround, the following instructions should help you create a Qubes Installation USB stick that works in UEFI-only mode.
In a nutshell, you need to use the Fedora livecd-tools to make a Qubes Installation USB Stick from the Qubes ISO image, then update the label on the partition of that USB stick to "BOOT", and then update the BOOT/EFI/BOOTX64.cfg file on the USB stick so that all labels point to BOOT. In more detail:
1. On your ThinkPad, enter the UEFI setup (press F1 at startup) and make sure to set at least the following options:
- *USB UEFI BIOS Support: Enabled*
- *UEFI/Legacy Boot: UEFI Only*
- *Secure Boot: Disabled*
2. On a different computer, create a "Fedora Live USB Stick": Download a current Fedora Live CD image, and put it onto a USB stick (e.g. using dd or Rufus). Start your ThinkPad from the Fedora Live USB Stick on your ThinkPad (Press F12 at startup to select boot device). Of course, you can alternatively start a different machine from the Fedora Live USB Stick, or use an existing Fedora installation. The next steps all occur within Fedora:
3. Install livecd-tools: `# dnf install livecd-tools`
4. Download the desired Qubes ISO image (or attach a storage device containing it), and verify the signatures as described in the Qubes installation guide. For these instructions, I assume the ISO image is at */run/media/liveuser/qsrc/Qubes-R4.0-rc3-x86_64.iso* (so whenever you see that path going forward in these instructions, replace it with whatever your own path is)
5. Within Fedora, attach the USB stick that you would like to turn into your Qubes Installation USB Stick. Use `dmesg` to figure out what the device name of that stick is. For these instructions, I assume it's */dev/sdd* (so whenever you see */dev/sdd* going forward in these instructions, replace it with whatever your actual device name is)
6. Make sure your target USB stick (presumed to be /dev/sdd) has no mounted partitions: ``# umount /dev/sdd*`` (the asterisk at the end makes sure to unmount all partitions if more than one exists). If none are mounted you'll get an error that you can ignore.
7. Use livecd-tools to copy the image: ``# livecd-iso-to-disk --format --efi /run/media/liveuser/qsrc/Qubes-R4.0-rc3-x86_64.iso /dev/sdd``. **This will erase everything on the drive. Make sure you specify the correct destination.** Then press ENTER when prompted to proceed. This process will take quite a while, be patient.
8. When imaging is complete, change the partition label to BOOT: ``# dosfslabel /dev/sdd1 BOOT``
9. Now create a mount point and mount the partition:
``# mkdir /mnt/qinst``
``# mount /dev/sdd1 /mnt/qinst/``
10. Use your favorite editor to edit the file */mnt/qinst/EFI/BOOT/BOOTX64.cfg*: Replace all instances of ``LABEL=Qubes-R4.0-rc3-x86_64`` with ``LABEL=BOOT``. There is typically no space in front of ``LABEL``, but there is a space at the end of the portion you replace.
11. Unmount the Qubes Installation USB stick: ``# umount /dev/sdd*`` and disconnect it.
That's it! You can now reboot the machine with the Qubes USB Installation stick attached, and press F12 to select it as the boot device at startup. Proceed to install Qubes OS normally. Enjoy!
## Random reboots on ThinkPads with Intel HD 3000 graphics ##
Several ThinkPad models have Intel HD 3000 graphics, including the T420s and the
T520. Some users with these laptops have experienced random reboots, which were
solved by adding `i915.enable_rc6=0` as a kernel parameter to
`GRUB_CMDLINE_LINUX` in the file `/etc/default/grub` in dom0.
## Can't boot the installer from a USB on Thinkpad X201 & X200 ##
For being able to boot the installer from USB, you have to disable VT-d in the BIOS.
Enter the BIOS by hitting F1, go to Config - CPU and then disable VT-d there.
After the installation, you have to set a startup-parameter for Xen, to be able to activate VT-d again:
1. Open a terminal in dom0
2. Edit `/etc/default/grub`
3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit
4. sudo `grub2-mkconfig --output /boot/grub2/grub.cfg`
Then reboot, enter BIOS and re-enable VT-d.
### Getting scrolling with the Trackpoint and the Middle Button to work ###
1. Create a script with the following content:
~~~
#!/bin/sh
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation" 1
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Button" 2
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Timeout" 200
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Axes" 6 7 4 5
~~~
2. Add the script to the startup-items of your desktop environment.
## Can’t boot from USB stick on Lenovo 450 ##
Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install.
### Setting UEFI options to get Qubes install to boot ###
1. Enable Legacy USB mode
2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT
3. Save settings and reboot
5. Install Qubes
... and now enjoy :) These settings may be needed also in other UEFI computers.