[GSoD] Progress, plans and feedback request

[c1e0]

Hiya!

Happy to be here.  \o/ . I'm Cleopatra. I go by c1e0 here and on IRC, and my username on GitHub is PROTechThor. I'm the Google Season of Docs technical writer (Thanks again for accepting my proposal, Marek). I've been lurking around here for some time. I should have said something earlier, but I was so caught up trying to refine the Troubleshooting Guide document layout.

The official documentation development period began last Monday. Here are some things I did last week:

- Attempted to set up a local version of the Qubes website (facing some podman issues. Should figure this out soon)

- Searched Github issues, #qubes-users, Reddit and Discourse for common issues. I recorded every issue which was mentioned at least three times. I managed to go as far back as 2018, when Qubes 4.0 was released.

- I went through all (I think) the existing documentation to find any troubleshoots lurking within instructions and recorded them.

- I modified my initial proposed layout for the Troubleshooting Guide. This initial layout was severely lacking in terms of content. I have expanded upon it, as you can see in my new and improved document layout pasted below. The caterogization is also improved, in my opinion.

Do you have any feedback on this new layout? I don't think it's perfect yet, but I will commence writing the guide and maybe make changes to the layout as I go. Some things may be added and others removed. We'll see. I will try to submit a PR weekly, each one addressing one or two of the troubleshooting topics.

I didn't account for how long it would take me to refine the document layout in my initial proposal timeline. I'll put together a new timeline soon, depending on how this and next week goes.

Refined TROUBLESHOOTING GUIDE layout

# Installation troubleshooting

•  "An unknown error has occured" error during installation
• Can't boot from USB stick
• Boot screen does not appear/  does not detect your installation medium during installation
• *Not asking for VNC because we don't have a network. X startup failed" error during installation
• *Pane is dead" error during installation
• Installation freezes at "Setting up Networking"
• Installation/booting freezes at "Setting up Networking"

# UEFI troubleshooting

• Black screen before booting the installer, after Xen output
•  Successfully installed in legacy mode, but had to change some kernal parameters
• Installation freezes before displaying installer
  - remove noexitboot and mapbs 
  - disable EFI runtime services
• Installation from USB stick hangs on black screen
• Installation completes successfully but then boot loops or hangs on black screen
•  Installation completes successfully but then system crash/restarts on next boot
•  Boot device not recognized after installing
• Installation finished but “Qubes” boot option is missing and xen.cfg is empty / Installation fails with "failed to set new efi boot target"
• Accessing the installer in Rescue mode on UEFI

# Verifying signatures troubleshooting

• “Can’t check signature: public key not found” error
•  “BAD signature from ‘Qubes OS Release X Signing Key’” error
•  “bash: gpg2: command not found” error
•  “can’t open signed data `Qubes-RX-x86_64.iso’ / can’t hash datafile: file open error”
• “can’t open `Qubes-RX-x86_64.iso.asc’ / verify signatures failed: file open error”
• “no valid OpenPGP data found” error
• “WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner.” error
• “X signature not checked due to a missing key” error
• Seeing additional signatures on a key with “[User ID not found]” or from a revoked key
• “verify signatures failed: unexpected data” error
• “not a detached signature” error
• “CRC error; […] no signature found […]” error
• “no properly formatted X checksum lines found” error
• “WARNING: X lines are improperly formatted” error
• “WARNING: 1 listed file could not be read” error
• *Other problems when verifying signatures.

# Suspend/resume troubleshooting

• “Device not ready” error on a wireless card after suspending and resuming.
• “Direct firmware load for ... failed with error” error.
• Drivers do not reload automatically on suspend and resume.
• Suspend doesn't work, freezing at resume
• Power consumption increases after suspend and resume

# VM troubleshooting

• Qubes starts, but no VMs load
• Can not uninstall a VM / “ERROR: VM installed by package manager: template-vm-name” error when trying to remove VMs.
• "Out of disk space" error
• Can't start/install an OS in an HVM
• Cannot increase the size of VM private storage
• "libxenlight failed to create new domain" error when starting a VM
• Fixing package installation errors in Qubes 4.0
• disp-sys-usb does not start
• VM kernel troubleshooting
• "Cannot connect to qrexec agent" error

# HVM Troubleshooting

• HVM crash when booting from ISO.
• HVM pauses on boot, followed by bootup kernel error

# PCI troubleshooting

• PCI device not available in dom0 after unassigning from a qube
• Realtek doesn't work
• PCI Passthrough issues

# USB troubleshooting

• USB "Device attach failed" error
• "qrexec not connected” error when trying to mount USB device
• usbVM doesn't boot after creating and assigning USB controllers to it / "Unable to reset PCI device" error.
• Can't attach a USB device / USB device not showing in qvm-usb
• Can't attach a device to a qube after removing a device without first detaching from the VM
• Can't use USB keyboard after setting up sys-usb VM

# GUI troubleshooting

• Can't click on everything after connecting 4k external display
• Screen blanks / Weird computer glitches like turning partially black
• After installation, screen goes black and freezes following LUKS decryption
•  Random black screen / black boxes

# Performance troubleshooting

• Qubes is so slow

# Media troubleshooting

• Can't play media videos in a VM due to missing codecs
• Video lagging

# VPN troubleshooting

# Firewall troubleshooting

# Wireless troubleshooting

• iwlwifi errors
•  Broadcom Wifi card doesn't work
• Wireless device disabled after update

# Nvidia troubleshooting

• System freezes during boot and the graphical login manager is not visible after installing Xen.
• System freezes followed by a reboot.
• Qubes fails to properly boot after the GRUB Boot menu, on a black screen that displays messages starting with nouveau.
• Trouble installing a Nvidia driver in dom0
• Lack of video output during Nvidia driver installation.

# AMD troubleshooting

• Dark screen during installation, accompanied by "Failed to load firmware" error.

# Intel Integrated Graphics troubleshooting

• Software rendering, video lagging or slow graphic updates.

• Workarounds for IOMMU-related issues (log errors, VM windows refresh issues, screen corruption and crashes).
  
   - For existing systems with VT-d enabled (grub / legacy mode).
  - For existing systems with VT-d enabled (UEFI).
  

# Lenovo troubleshooting

• Can’t perform UEFI boot from a USB stick or burned DVD on newer ThinkPads.
• Random reboots on ThinkPads with Intel HD 3000 graphics.
• Can’t boot the installer from a USB on Lenovo Thinkpad X201 & X200.
• Can’t scroll with the TrackPoint and middle mouse button on Lenovo Thinkpad X201 & X200.
• Can’t boot from USB stick on Lenovo 450
• Install hangs on Thinkpad with VT-d enabled
• Fixing suspend and resume problems

# Apple Macbook troubleshooting

• Boot freezes at "Setting up networking"
• System freezes when Broadcom wifi cardis attached

# Sony Vaio Z troubleshooting

• Graphics card doesn’t work.
• Touchpad doesn’t work during installation.
• Audio/sound doesn’t work.
• Screen doesn’t restore after resume.

# Troubleshooting other hardware issues

• Troubleshooting newer hardware
• “Unsupported Hardware Detected” Error
• “Hardware lacks the features required to proceed” error during installation
• Keyboard layout settings not behaving correctly
• Trackpad doesn't work

# Application troubleshooting

• Can't launch any applications after starting VM
• Fullscreen firefox is frozen
• "qubes-usb-proxy not installed in the VM" error
• LibreOffice opens as a tiny window
• Constant firefox crashes

# Update troubleshooting

• “Failed to synchronize cache for repo” errors when trying to update Fedora templates
• “Failed to synchronize cache for repo” errors when trying to update dom0
• “Failed to synchronize cache for repo” errors when trying to update packages
• "No match found" when trying to install a TemplateVM
• Lost internet access after a TemplateVM update
•  Dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool
• Previously-working features fail after an update

# Qubes-Whonix troubleshooting

• Error when upgrading Qubes-Whonix: Installed whonix-gateway-packages-dependencies 3.4.2-1 is outdated!
• Can't update due to non-functional onion services
• Reinstallation errors after uninstalling old Whonix templates

# Tails troubleshooting

• Black screen on startup
• Windows extend beyond the bottom of the screen
• Can't use persistent tools
• Tails qube doesn't shut doen cleanly

# Multiboot troubleshooting

[Andrew David Wong]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 2020-09-22 8:22 AM, c1e0 wrote:
> Hiya!
>
> Happy to be here. \o/ . I'm Cleopatra. I go by c1e0 here and on IRC, and
> my username on GitHub is PROTechThor. I'm the Google Season of Docs
> technical writer (Thanks again for accepting my proposal, Marek). I've been
> lurking around here for some time. I should have said something earlier,
> but I was so caught up trying to refine the Troubleshooting Guide document
> layout.
>

Welcome! Thanks for working on this. :)

> The official documentation development period began last Monday. Here are
> some things I did last week:
> - Attempted to set up a local version of the Qubes website (facing some
> podman issues. Should figure this out soon)

Feel free to ask me questions about this. I recently dealt with the same
thing and have a working setup now.

> - Searched Github issues, #qubes-users, Reddit and Discourse for common
> issues. I recorded every issue which was mentioned at least three times. I
> managed to go as far back as 2018, when Qubes 4.0 was released.
> - I went through all (I think) the existing documentation to find any
> troubleshoots lurking within instructions and recorded them.
> - I modified my initial proposed layout

> <https://docs.google.com/document/d/187NlnEvctYVVUnRuGtwY2PkYBVxBSSPfpSwZEaczqL8/edit?usp=sharing>

> for the Troubleshooting Guide. This initial layout was severely lacking in
> terms of content. I have expanded upon it, as you can see in my new and
> improved document layout pasted below. The caterogization is also improved,
> in my opinion.
>
> Do you have any feedback on this new layout? I don't think it's perfect
> yet, but I will commence writing the guide and maybe make changes to the
> layout as I go. Some things may be added and others removed. We'll see. I
> will try to submit a PR weekly, each one addressing one or two of the
> troubleshooting topics.

Just a cursory read, but it looks pretty good to me. I see a lot of
problems that are common pain points for users. I'm sure other folks
will have more detailed things to say about specific points.

> I didn't account for how long it would take me to refine the document
> layout in my initial proposal timeline. I'll put together a new timeline
> soon, depending on how this and next week goes.
>

> *Refined TROUBLESHOOTING GUIDE layout*
>
> [...]

- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAl9qHhIACgkQ203TvDlQ
MDBjfw/9FMAsnrfbW2oYDKWxFehDPHbPYR43HDYL5ugZ2FM+IDq+aahFRu7BHriA
/zc6yyr9mwHr781Yra1FwSQXkYWGMAhsYtLV71yO0xBNIxOXNoeOU8zSi4rl7PMn
O/Izkk+GO2GiszULGKkdUsHGqg1nCzswL/ytX9Hkvsxa8lwtVAac9RF++usHrmgn
MsGzm0YwSX/KD/P7C/MZUNKO30ynwrbb7Dh6UjBlY+RWpIMyRDonMvfyBiAPgq7z
i1YIcr8R4z6Gbw39QUcHZ3rwnSITf0+2KQz6Fg15zsvLO+uixe9qzqnIkJ7fvrFC
bRpI310Bojy0gToTsexNsrpTNwL9K5ZG1B3p9jxkbzwJWJ3fsV1ezZikrjLUBh00
5yyf7nrDJXI8v+9yt32OTsfbZgFg6C5J2bKc8DM8dw6xL7ovhb9y7xrUdiL9uBnh
btlXJMbuIHlH4kGtdtmXupr+7GJraeb8U+dznzxEoY1TqlWfBA9oJaAJFtUvlJqz
FAN6wjRb649rLHdlJbMc1IdaTQIVmkUcfxMC94Y5WKhT0QVZ3bXKMYbCXNBjgPhe
m0siAxPD6rXkD5GjaZtJN10bEwsXE5axQY95PcqpzCzbwit7XoXdLFqblz6htIbO
q1Aqv9JyyDL7k4bprlGcy3LQiQOtVCjm0Gz7uvJ9mC5z673uilU=
=Pzc3
-----END PGP SIGNATURE-----