{{Header}} {{#seo: |description=Troubleshooting Installation and Network Issues with {{project_name_long}} |image=Troubleshooting-114197640.jpg }} {{troubleshooting_mininav}} [[File:Troubleshooting-114197640.jpg|thumb|Troubleshooting]]
* [[#ISO|ISO]] * [[#Connectivity Troubleshooting|Connectivity]] * [[#General Troubleshooting|General Troubleshooting]]
{{intro| The wiki page covers troubleshooting tips for installation issues, general issues, network issues and hardware problems. }} = ISO = == ISO to USB Image Writer Tools == functional, bootable image: * Flashing using a Qubes Kicksecure VM with hide hardware information enabled using cp * Flashing using a Qubes Kicksecure VM using KDE ISO Image Writer from Flathub * Flashing using a Debian VM balanaEtcher AppImage. * Flashing using a Windows OS with balanaEtcher installer version. * Flashing using a Windows OS with UNetbootin (portable). broken: * Flashing using a Qubes Kicksecure VM with [[Security-misc#Reduce_Kernel_Information_Leaks_|hide hardware information]] enabled using balanaEtcher, which shows an error message due to hide hardware information. == Tips == * Exercise on separate notebook. * Use a VM to flash for security against data loss. == Live ISO Known Issues == === balenaEtcher === Platform specific. * '''A)''' Non-Windows host operating systems such as macOS or Linux: No special notice. * '''B)''' Windows: See below. If you have [https://support.microsoft.com/en-us/windows/allow-an-app-to-access-controlled-folders-b5b6627a-b008-2ca2-7931-7e51e912b034 Controlled Folder Access] enabled, you need to allow changes by Etcher: '''Figure:''' ''Windows Protection History'' [[File:Etcher Bug.png|900px]] If you have [https://learn.microsoft.com/en-us/windows/security/application-security/application-control/user-account-control/how-it-works User Account Control] enabled, allow Etcher to make changes to your device by pressing "Yes" when a popup similar to the following appears: '''Figure:''' ''Windows User Account Control'' [[File:windowsallowsystemchange.png|400px]] === KDE ISO Image Writer === {{quotation |quote=The last block was not fully written (-1 of 1,048,576 bytes)! |context=KDE ISO Image Writer Error Message }} [[File:isoimagewritererror.png|400px|KDE ISO Image Writer Error Message]] * Question: Why does it happen with {{project_name_short}} ISO but not with Debian or some other ISO? ** Answer: Not sure. Maybe a race condition. Or perhaps the premise might be wrong. A web search for this error message shows [https://askubuntu.com/questions/1471562/creating-a-windows-10-installation-usb-on-ubuntu-22-04 running Ubuntu and attempting to flash a Windows 10 ISO using KDE ISO Image Writer] failed. Also [https://www.reddit.com/r/kde/comments/zvoo0l/iso_image_writer_broken/ flashing KDE Neon failed]. This error seems to be reproducible with many Linux distributions. It is probably only possible for the KDE ISO Image Writer developers to fix this bug. There is probably nothing that the {{project_name_short}} ISO could do better. KDE upstream bug report: [https://bugs.kde.org/show_bug.cgi?id=474195 "Last block was not fully written" error if usbstick is not unmounted, does not unmount on its own] In this case, * '''A)''' try to unmount the USB device first or * '''B)''' use a different ISO Image Writer tool. === DVD Support === [[File:Cd-rom-icon.png|50px|thumb]] [[Untested]]. Should work in theory. Tested inside QEMU and VirtualBox with an emulated CD-ROM drive. So chances are good that it would work with a real DVD drive as well. === Dual Boot === It is recommended to physically disconnect any other physical disks while installing {{project_name_short}} (or any other operating system) to mitigate the risk of the installer overwriting the wrong drive due to user error or software bugs. === Fastboot === Fastboot is a BIOS setting which skips attempting to boot from USB on some computers. In this case, the user must disable Fastboot in order to be able to boot from USB. === Encryption Settings === * Default Encryption Settings: Which encryption settings will be used? See: {{CodeSelect|inline=true|code= cryptsetup luksFormat --help }} * Authority: Where are the default encryption settings coming from? From distribution defaults. In this case, from Debian because [[About#Based_on_Debian|{{project_name_short}} is based on Debian]]. * User customization: No, unfortunately not possible. Full disk encryption settings are not configurable in calamares. [https://github.com/calamares/calamares/issues/1452 calamares upstream bug report] (closed, but not implemented, "patches welcome") * Alternatives: [[Distribution Morphing]]: [[Debian|morphing Debian into {{project_name_short}}]] * Forum discussion: [https://forums.kicksecure.com/t/iso-cryptsetup-full-disk-encryption-fde-set-more-secure-default-encryption-settings/588 ISO - cryptsetup Full Disk Encryption (FDE) - set more secure default encryption settings] === Minor Issues === This might be an issue while installing additional packages while running the live ISO. This will not be an issue after installing to hard drive. ==== Failed to mount sysroot.mount - /sysroot. ==== The message Failed to mount sysroot.mount - /sysroot. during the boot ISO process is only a cosmetic issue. It can be safely ignored. This issue will be fixed in {{project_name_short}} 18 and above (Debian trixie based). Details here: https://forums.kicksecure.com/t/iso-error-message-during-boot-mount-sysroot-special-device-liveos-rootfs-does-not-exist/418 ==== update-grub ==== Note: There is most likely no need to run the following command. This is only documentation "what if". If running the following command, 
sudo update-grub
then the following error message would be shown. 
/usr/sbin/grub-probe: error: failed to get canonical path of `LiveOS_rootfs'.
zsh: exit 1     sudo update-grub
Please report a bug if this breaks something for you. Adding a workaround for this would not be difficult. This command is also unrelated to fixing installation issues. Users executing update-grub from an ISO is not very useful because an ISO is a read-only filesystem. Running update-grub can be useful during the installation from ISO to hard drive, but this is something that needs to happen inside a chroot, which is a specifically prepared environment. This is very difficult for most users and unnecessary because this is part of the tasks of the installer. == Calamares ISO Installer == = Connectivity Troubleshooting = == ICMP Fix == {{mbox | image = [[File:Ambox_notice.png|40px|alt=info]] | text = Note: Kicksecure firewall does not exist yet at time of writing. }} Therefore no such fix required yet. == Qubes-specific Connectivity Issue == Complete the following steps: # Shut down {{project_name_gateway_vm}}. # Change the {{project_name_gateway_vm}} NetVM setting from sys-firewall to sys-net. # Restart {{project_name_gateway_vm}}. This procedure might help, but should not be considered a final solution. This procedure was useful for [[Qubes|{{q_project_name_long}}]] R3.2 users, although the Qubes bug report is now resolved: https://github.com/QubesOS/qubes-issues/issues/2141 == Why can't I Ping the {{project_name_gateway_long}}? == {{mbox | image = [[File:Ambox_notice.png|40px|alt=info]] | text = Note: Kicksecure firewall does not exist yet at time of writing. }} The {{project_name_gateway_short}} does not respond to ping or similar commands because it is firewalled for security reasons; see ''{{W_Firewall}}'' or refer to the {{project_name_short}} source code. In most cases it is unnecessary to ping the {{project_name_gateway_short}} anyhow. If you insist on pinging the {{project_name_gateway_short}} or have a unique setup that requires it, then this can be tested by clearing all firewall rules with the [https://github.com/{{project_name_short}}/developer-meta-files/blob/master/dangerous-scripts/dev_clearnet dev_clearnet] script. Alternatively, a script can be run to try and [[Dev/Firewall_Unload|unload / remove every iptables rule]], or the {{project_name_short}} firewall can be hacked to not load at all. The latter method is only for experts and it is necessary to comment out ''exit 0'' at the beginning. ---- = General Troubleshooting = == Introduction == Troubleshooting issues can be time intensive and success cannot be guaranteed. Some users expect {{project_name_short}} to provide an easy experience. While the {{project_name_short}} developers make every effort to meet user expectations, limited funding and human resources makes meeting these expectations impossible. Even though problems emerge when using {{project_name_short}}, the cause is most often unrelated to {{project_name_short}} code. For example, users often report the same {{project_name_short}} release worked on different hardware and/or with a different host operating system. Most software such as the host operating system or the virtualizer is developed by independent entities; this is the norm in Linux distributions. See [[Linux User Experience versus Commercial Operating Systems]] to learn more about these relationships, as well as organizational and funding issues in the Open Source ecosystem. == Essential General Troubleshooting Steps == {{mbox | image = [[File:Ambox_notice.png|40px|alt=info]] | text = The following recommended steps will fix many startup, freezing or other unusual issues in {{project_name_short}}. Skips steps that are no longer possible if a virtual machine is not bootable. }} {{box|text= '''1.''' "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test your host computer first. '''2.''' Exclude basic [[#Hardware Issues|hardware issues]]. '''3.''' Ensure the virtual machine (VM) images have been imported into a supported virtualizer listed on the [[Download]] page. '''4.''' Debian (based) Linux host operating system users only: The following command should not show any errors. This process can be lengthy. {{CodeSelect|code= sudo dpkg-reconfigure -a }} '''5.''' Debian (based) Linux host operating system users only: The following command should be silent and not show any errors or output at all. {{CodeSelect|code= sudo dpkg --configure -a }} '''6.''' Debian (based) Linux host operating system users only: Next attempt to retrieve all available updates. {{CodeSelect|code= sudo apt update }} {{CodeSelect|code= sudo apt full-upgrade }} '''7.''' Check for possible [[#Low RAM Issues|Low RAM Issues]]. * [[#Free up Additional Memory Resources|Free up Additional Memory Resources]]. * Also refer to [[RAM|Advice for Systems with Low RAM]]. '''8.''' Virtualizer-specific troubleshooting. * [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]] / [[VirtualBox/Troubleshooting#General VirtualBox Troubleshooting Steps|General VirtualBox Troubleshooting Steps ]] * [[KVM#Troubleshooting|KVM Troubleshooting]] '''9.''' Check if other VMs are functional, such as newly created ones or those from a different vendor. # "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test the virtualizer host software first. # Try a VM other than {{project_name_short}} such as Debian {{Stable project version based on Debian codename}}. # If the issue persists, this means the root issue is not caused by {{project_name_short}}, see: [[unspecific]] to {{project_name_short}}. In this case, attempt to resolve the issue as per [[Self_Support_First_Policy|Self Support First Policy]]. '''10.''' Check [[#System Logs|System Logs]]. * Sometimes crashing or freezing issues are easier to detect by [[#Watch Systemd Journal Log of Current Boot|Watching Systemd Journal Log of Current Boot]]. * Sometimes it is necessary to [[#Check Systemd Journal Log of Previous Boot|Check Systemd Journal Log of Previous Boot]]. '''11.''' If a graphical environment (where one can use a computer mouse) is unavailable after booting, utilize a virtual console to acquire system logs. # [[Recovery#Virtual_Consoles|Recovery, Virtual Consoles]]. # Check system logs of the previous boot (step 10). '''12.''' Use recovery mode to acquire system logs. # Boot in [[Recovery#Recovery_Mode|recovery mode]]. # Check system logs of previous boot (step 10). '''13.''' Use a chroot to acquire system logs. If a virtual console is inaccessible and recovery mode is also broken, try [[Recovery#Chroot|using a chroot for recovery]]. }} == Low RAM Issues == If insufficient RAM is available for {{project_name_short}} VM they might become unusable. Low RAM issues in {{project_name_short}} are commonly caused by: * Unnecessary processes running and/or multi-tasking on the host OS. * Multiple, open browser tabs. * Unnecessary processes running in the {{project_name_short}} VM. * Allocating more RAM to the {{project_name_short}} VM than is available; this prevents the VM from booting. * Insufficient RAM allocated to the {{project_name_short}} VM. * Other non-{{project_name_short}} VM running in parallel. Insufficient RAM can cause multiple issues, but the most common effects include: * Slow or unresponsive applications. * The VM, mouse and/or keyboard freeze. * Scrolling causes window staggers or jumps. * Issues become worse when additional browser tabs or processes are spawned. * Overall performance is poor. See also: [[RAM|Advice for Systems with Low RAM]]. === Free up Additional Memory Resources === If a VM needs additional memory, then free up resources and/or add more RAM to the VM: * Terminate any non-essential processes on the host. * Shut down any non-essential VM. * Shut down and/or close non-essential processes and browser tabs in {{project_name_short}} VM. To add additional RAM to the {{project_name_short}} VM, follow the platform-specific advice below. === KVM === {{KVM_RAM}} === {{q_project_name_short}} === Utilize Qube Manager:
* Qube Manager → VM_name → Qubes settings → Advanced → Max memory: mem_size === VirtualBox === # To add RAM in VirtualBox the VM must first be powered down. # Virtual machine → Menu → Settings → Adjust Memory slider → Hit: OK See also: [[VirtualBox/Troubleshooting]]. = Generic Bug Reproduction = TODO related: [[Reporting_Bugs#Generic_Bug_Reproduction|Generic Bug Reproduction]] = System Logs = "user support template": https://forums.whonix.org/t/workstation-keeps-freezing/7693/6 == Check Systemd Journal Log of Current Boot == To inspect the systemd journal log of the current boot, run. {{CodeSelect|code= sudo journalctl -b }} This command requires pressing arrow keys like ↑, ↓, ←, →, as well as PgUp and PgDn for scrolling. For convenient reading of the log (until the command is issued), the log can be dumped to file. For example, the following command would write the log to file ~/systemd-log. {{CodeSelect|code= sudo journalctl -b > ~/systemd-log }} Use any available editor to read the log file, such as mousepad. {{CodeSelect|code= mousepad ~/systemd-log }} == Watch Systemd Journal Log of Current Boot == It is possible to to watch the systemd journal log as it is written. {{CodeSelect|code= sudo journalctl -b -f }} == Check Systemd Journal Log of Previous Boot == It is possible to inspect the systemd journal log of the previous boot. {{CodeSelect|code= sudo journalctl -b -1 }} This command requires pressing arrow keys like ↑, ↓, ←, →, as well as PgUp and PgDn for scrolling. For convenient reading of the log (until the command is issued), the log can be dumped to file. For example, the following command would write the log to file ~/systemd-log-previous. {{CodeSelect|code= sudo journalctl -b -1 > ~/systemd-log-previous }} Use any available editor to read the log file, such as mousepad. {{CodeSelect|code= mousepad ~/systemd-log-previous }} == View List of Systemd Journal Logs == {{CodeSelect|code= sudo journalctl --list-boots }} {{Anchor|Daemon Log}} == Daemon Log View == To view the log of a specific systemd unit. Syntax: (Replace unit-name with the actual name of the systemd unit.) {{CodeSelect|code= sudo journalctl -b --no-pager -u unit-name }} Example: {{CodeSelect|code= sudo journalctl -b --no-pager -u sdwdate }} == Daemon Log Follow == To follow the log of a specific systemd unit. Syntax: (Replace unit-name with the actual name of the systemd unit.) {{CodeSelect|code= sudo journalctl -f -b --no-pager -u unit-name }} Example: {{CodeSelect|code= sudo journalctl -f -b --no-pager -u sdwdate }} == Daemon Status == To view the status of a specific systemd unit. Syntax: (Replace unit-name with the actual name of the systemd unit.) {{CodeSelect|code= sudo systemctl status --no-pager unit-name }} Example: {{CodeSelect|code= sudo systemctl status --no-pager sdwdate }} == Check Systemd Journal Log of Failed Boot == An alternative to recovery mode might be [[Desktop#Virtual_Consoles|virtual consoles]], since they are an easier and more lightweight solution. A virtual console login might still be possible when the graphical user interface no longer starts. Prerequisite knowledge: [[Desktop#Virtual Consoles|Virtual Consoles]]. Try to log in to a virtual console in a functional VM as an exercise. If that works, try a virtual console login in the broken VM. If a virtual console is unavailable: # Boot into [[Recovery|Recovery Mode]]. # Reboot into normal mode so a log for the failed boot will be written (if not previously enabled). # Boot into recovery mode again. # [[#Check_Systemd_Journal_Log_of_Previous_Boot|Check Systemd Journal Log of Previous Boot]]. = Permission Fix = {{mbox | image = [[File:Ambox_notice.png|40px|alt=info]] | text = If something does not work, do not arbitrarily try to use sudo / root without any indication this is appropriate. Otherwise, this can negatively affect the correct user home folder permissions. See also: [[root|Safely Use Root Commands]]. }} {{Open a product ws terminal}} {{CodeSelect|code= sudo chown --recursive user:user /home/user }} = Hardware Issues = == General Recommendations == Rhetorical questions: * When was the last time a qualified person disassembled your computer/notebook and removed dust from the fan and checked the cooling system of the CPU? * How often should maintenance be performed? * What is your CPU temperature under heavy system load? * What is the room temperature where the computer is operating? Recommendations: * Ensure your computer or notebook has regular, proper maintenance. * Monitor CPU temperature by utilizing relevant host operating system tools. * Consider cooling the room where computers/notebooks operate. * Better placement (more air space) around computers or notebooks can help. * Consider a passive or active (notebook) cooling pad. Perform thorough research beforehand. * [[#memtest86+|Run memtest86+]] to rule out RAM problems. None of these issues are related to {{project_name_short}}. Therefore, please do not ask these questions in {{project_name_short}} support channels (until there is a {{project_name_short}} Host DVD available) as per [[Self_Support_First_Policy|Self Support First Policy]]. == memtest86+ == {{Box|text= '''1.''' Install the memtest86+ tool. On Debian (based) hosts such as [[Kicksecure]]. {{Install Package|package= memtest86+ }} For other host operating systems, refer to memtest86+ upstream documentation. '''2.''' Reboot. '''3.''' Start memtest86+ from (grub) boot menu. '''4.''' Keep memtest86+ running for a significant period. This should be run for as long as practically possible; for example, ideally overnight or for 8+ hours. '''5.''' Check the memtest86+ output. If there are any issues, red error messages appear in the middle of the screen. '''6.''' Done. The memory test is complete. If memtest86+ identified any issues, these can manifest in various ways such as system crashes at random times. In such cases, the only likely solution is replacing the faulty hardware (RAM banks). RAM bank warranties may apply. }} == Hard Drive Health Check == TODO: document also known as S.M.A.R.T * smartmontools * gsmartcontrol * smart-notifier * nvme-cli * package: gnome-disk-utility run: gnome-disks * https://packages.debian.org/bookworm/lm-sensors * https://packages.debian.org/bookworm/plasma-disks * https://packages.debian.org/bookworm/psensor * https://wiki.debian.org/SystemMonitoring = See Also = * [[RAM|Advice for Systems with Low RAM]] * [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]] * [[KVM#Troubleshooting|KVM Troubleshooting]] * [[Recovery|Recovery Mode]] * [[SysRq|System Recovery using SysRq Key]] * [[Core Dumps]] = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Documentation]]