{{Header}}
{{#seo:
|description=Troubleshooting Installation and Network Issues with {{project_name_long}}.
|image=Troubleshooting-114197640.jpg
}}
[[image:Troubleshooting-114197640.jpg|thumb]]
* [[#Connectivity Troubleshooting|Connectivity Troubleshooting]]
* [[#General Troubleshooting|General Troubleshooting]]
{{intro|
Troubleshooting Installation and Network Issues with {{project_name_short}}.
}}
= Connectivity Troubleshooting =
== Essential Connectivity Troubleshooting Steps ==
In case of connectivity issues:
{{Box|text=
'''1.''' Download source.
Did you download {{project_name_short}} from {{project_clearnet}}? If downloaded from other sources, uninstall and try downloading from {{project_clearnet}} instead.
'''2.''' "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test your host computer first.
'''3.''' Test if the host internet connection is functional. [
By using ping.
For example, ping ]8.8.8.8.
On the host, run.
{{CodeSelect|code=
ping 8.8.8.8
}}
Ping google.com and/or other websites.
{{CodeSelect|code=
ping google.com
}}
and so on.
Open different websites such as {{project_clearnet}} in a host web browser. If the host internet connection is dysfunctional, {{project_name_short}} connectivity will also be broken. The host internet connection needs to be fixed first.
'''4.''' Speed and ping test the the host internet connection.
Running a internet speed test and ping test might show if there is something wrong with the host internet connection.
'''5.''' VPN/proxy related connectivity issues.
Using a VPN or proxy? ('''User → Tor → proxy/VPN/SSH → Internet''') If yes, the following tests should be performed.
* '''A)''' The host internet connection and speed without VPN and without Tor should be tested first.
* '''B)''' Next the host internet connection should be tested with a VPN only but without Tor.
* '''C)''' Only then complex setups such as Tor in combination with a VPN should be tested.
'''6.''' Check the date and time. [
{{CodeSelect|code=
date
}}
]
Check if the host clock time and date has accuracy of up to ± 30 minutes. If the host clock is more than 1 hour in the past or more than 3 hours in the future, Tor cannot connect. ([[Network Time Synchronization|details]])
If not, fix host clock, power off VM and restart the VM.
'''7.''' [[timezone|Do not change system timezone setting.]]
'''8.''' Unnecessary use of [[Bridges]].
Have bridges been configured? The user should consider if that is really necessary in their area. Note: Bridges are not necessarily more secure than entry guards ([[Bridges#Before_Configuring_a_Bridge|link to sources]]) and have the potential to cause broken, unreliable and slow connections. [
https://forums.whonix.org/t/time-too-long-error-or-very-long-time/12716/4
]
'''9.''' Using WiFi or mobile internet connection?
Both, WiFi and mobile internet connections might be unreliable. Clearnet browsing might be able to recover more easily from slight unreliability issues than Tor. If practical, it should be considered to use a wired internet connection such as DSL, fiber or cable internet. This might result in more stable and faster connections systemcheck is run in {{project_name_short}} it performs various tests and might provide insights why there are connectivity or other issues.
Check {{project_name_gateway_short}} first. If it succeeds, test {{project_name_workstation_short}}. If it fails, there is no need to test {{project_name_workstation_short}}.
'''12.''' [[Whonix-Workstation_Firewall#Ping|Forget about ping.]]
'''13.''' Check if other virtual machines have Internet connectivity, such as newly created ones or those from a different vendor.
See [[#General Virtualizer Connectivity Test|General Virtualizer Connectivity Test]].
'''14.''' Virtualizer settings changes.
Did you change any settings on the host operating system virtualization software?
For example, if using VirtualBox changing settings from NAT to [[Whonix-Gateway_Security#Warning:_Bridged_Networking|bridged networking is discouraged]] and breaks networking.
In case you changed virtualizer settings but don't know which, perform a {{kicksecure_wiki
|wikipage=Factory_Reset
|text=factory reset
}}, i.e. delete the {{project_name_short}} VMs and re-import these.
'''15.''' RELATED
Try [[#RELATED Fix|RELATED Fix]].
'''16.''' ICMP
Using dial-up connection? Or Tor bootstrapping stuck at 45%? See [[#ICMP Fix|ICMP Fix]].
'''17.''' [[Tor#Connectivity_Troubleshooting|Tor Connectivity Troubleshooting]].
}}
Information pertaining to these points should be included in any [[Support|support]] request or [[Reporting_Bugs|bug report]].
== RELATED Fix ==
{{box|text=
'''1.''' {{Firewall_Settings}}
'''2.''' Paste.
{{CodeSelect|code=
GATEWAY_ALLOW_INCOMING_RELATED_STATE=1
}}
'''3.''' Save.
'''4.''' {{Reload_Firewall}}
'''5.''' Done.
The process of allowing RELATED connections on {{project_name_gateway_short}} has been completed.
}}
related:
* https://forums.whonix.org/t/have-firewall-accept-icmp-fragmentation-needed/10233
* https://forums.whonix.org/t/tor-is-not-yet-fully-bootstrapped-30-done/8792/6
== ICMP Fix ==
Using a dial-up connection? Or is Tor bootstrapping stuck at 45%?
[https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol ICMP] [https://forums.whonix.org/t/have-firewall-accept-icmp-fragmentation-needed/10233/2 is disabled in {{project_name_short}} by default for security reasons] because only a minority of users require it.
Try allowing incoming ICMP on [[{{project_name_gateway_short}}|{{project_name_gateway_short}}]].
{{box|text=
'''1.''' {{Firewall_Settings}}
'''2.''' Paste.
{{CodeSelect|code=
GATEWAY_ALLOW_INCOMING_ICMP=1
}}
'''3.''' Save.
'''4.''' {{Reload_Firewall}}
'''5.''' Done.
The process of enabling ICMP on {{project_name_gateway_short}} has been completed.
}}
There might be [https://forums.whonix.org/t/have-firewall-accept-icmp-fragmentation-needed/10233/3 a more restricted ICMP permission] but it is not implemented. [[Reporting_Bugs#Contributions|Contributions welcome!]]
Also see this related [https://forums.whonix.org/t/icmp-support-is-required-for-networking-in-some-cases/12503 forum discussion].
== Advanced Connectivity Troubleshooting Steps ==
{{mbox
| type = notice
| image = [[File:Ambox_notice.png|40px|alt=Info]]
| text = These Advanced Connectivity Troubleshooting Steps are supplementary and not a substitute, "better", or a shortcut.
}}
{{Box|text=
'''1.''' Start with the [[#Essential Connectivity Troubleshooting Steps|Essential Connectivity Troubleshooting Steps]] above.
'''2.''' Consider [[#Clearnet Connectivity Test|Clearnet Connectivity Test]].
'''3.''' Investigate virtualizer-specific troubleshooting.
* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]
'''4.''' Check [[#General Troubleshooting|General Troubleshooting]] steps.
}}
== Clock Fix ==
Broken internet connectivity is to be expected if the clock is incorrect. At all times it is recommended to have a host clock with accuracy of up to ± 30 minutes.
Quote {{project_name_short}} [[Post Install Advice]]:
To protect against time zone leaks, the system clock inside {{project_name_short}} is set to UTC. This means it may be a few hours before or ahead of your host system clock. Do not change this setting!
See [[Network_Time_Synchronization#Manually_Set_Clock_Time_and_Date|Manually Set Clock Time and Date]].
== Clearnet Connectivity Test ==
{{mbox
| image = [[File:Ambox_warning_pn.svg.png|40px]]
| text = '''Warning:''' The following test might reveal the {{project_name_short}} platform is in use. If that is a valid concern, then omit this step.
}}
It is possible to check if a non-torified, non-anonyomus, direct connection to check.torproject.org is functional. [This test only uses TCP and not DNS.]
On {{project_name_gateway_long}}, run.
{{CodeSelect|code=
sudo -u clearnet {{Curl_Plain}} {{Curl_Secure}} -H 'Host: check.torproject.org' -k https://{{Check.torproject.org IP}} | grep IP
}}
== General Virtualizer Connectivity Test ==
If networking is unavailable inside {{project_name_short}}, then try:
# Installing an operating system in a non-{{project_name_short}} virtual machine or downloading a regular image without Tor enforcement.
# Testing network functionality in a freshly downloaded non-{{project_name_short}} virtual machine.
If networking is still not functional, then {{project_name_short}} will not work either. The user must first resolve this issue, which might require re-installation of the virtualizer, followed by a reboot and further connectivity test(s).
If networking is functional, then users should note that networking is working in non-{{project_name_short}} VMs as part of the support request or bug report.
== Unsuitable Connectivity Troubleshooting Tools ==
The following tools have limited usefulness when attempting to fix connectivity issues.
* [[tor-control-panel|Tor Control Panel]]
* [[Anon Connection Wizard]]
* Others listed further below.
These tools can offer assistance for Tor configuration, either by simply enabling access to the public Tor network or by configuring Tor to use [[Bridges]]. If an internet service provider (ISP) prevents access to the public Tor network, then using these tools to configure bridges might help. If the ISP prevents access to one type of bridges or specific (such as built-in) bridges, then choosing another type and/or different bridge might help.
However, these are simple utilities that create a Tor configuration file, restart Tor, and report what the Tor software is saying about the Tor bootstrap (connection) status. These tools do not have sophisticated features to debug complex connectivity issues; they are designed to:
# Ask for user input.
# Create Tor configuration file.
# Restart Tor.
# Show Tor bootstrap status.
Constant monitoring of network issues is not implemented. For example, after the initial setup is done -- such as using Tor Control Panel for Anon Connection Wizard -- these tools do not keep supervising Tor or other parts of the system. Therefore, the Tor Control Panel message stating "Connected to the Tor network" could be stale. That was true when the tool was started, but it is not constantly monitored.
From the perspective of the Tor software, these are [https://en.wikipedia.org/wiki/High-level_programming_language high-level level programming language] tools developed by a third party. [
]In computer science, a high-level programming language is a programming language with strong abstraction from the details of the computer. In contrast to low-level programming languages, it may use natural language elements, be easier to use, or may automate (or even hide entirely) significant areas of computing systems (e.g. memory management), making the process of developing a program simpler and more understandable than when using a lower-level language. The amount of abstraction provided defines how "high-level" a programming language is.
These tools have a limited "understanding" of Tor's internals, let alone other aspects of the system configuration that might be broken. [Such as broken networking in either the host network or in all virtual machines.
] When attempting to debug connectivity issues, the "lower" level must be inspected which is closer to the system, virtualizer and Tor.
[[sdwdate]], sdwdate logs and [[sdwdate-gui]] have limited usefulness for connectivity troubleshooting. These tools might point out issues with the system time but other than that sdwdate requires an already functional Tor to be able to fetch the time from onions.
Other unsuitable connectivity troubleshooting tools include:
* Mostly: [[Whonix-Workstation_Firewall#Ping|Using ping inside {{project_name_workstation_long}}]].
Other [[#Connectivity Troubleshooting|recommended steps]] mentioned on this page are far more promising.
== Why can't I Ping the {{project_name_gateway_short}}? ==
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/Kicksecure/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 similar to a Windows machine. 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 {{kicksecure_wiki
|wikipage=Linux User Experience versus Commercial Operating Systems
|text=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, such as the "run systemcheck" command if a virtual machine is no longer 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.''' Run [https://www.kicksecure.com/wiki/Systemcheck systemcheck], if possible.
This verifies the {{project_name_short}} system is up-to-date and that everything is in proper working order.
'''5.''' 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
}}
'''6.''' Debian (based) Linux host operating system users only: The following command should be silent and not show any errors or output at all. {{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]].
'''11.''' 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]].
'''12.''' 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 11).
'''13.''' Use recovery mode to acquire system logs.
# Boot in [[Recovery#Recovery_Mode|recovery mode]].
# Check system logs of previous boot (step 11).
'''14.''' 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}} VMs 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(s).
* 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(s).
* Other non-{{project_name_short}} VMs 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.
To add additional RAM to the {{project_name_short}} VM(s), follow the platform-specific advice below.
{{Tab
|type=controller
|addToClass=tcc-indent
|content=
{{Tab
|type=section
|title= === VirtualBox ===
|content=
# 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]].
}}
{{Tab
|type=section
|title= === KVM ===
|content=
{{KVM_RAM}}
}}
{{Tab
|type=section
|title= === Qubes-Whonix ===
|content=
Utilize Qube Manager:
Qube Manager → VM_name → Qubes settings → Advanced → Max memory: mem_size
}}
}}
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 VMs.
* Shut down and/or close non-essential processes and browser tabs in {{project_name_short}} VMs.
* [[Non-Qubes-Whonix|{{non_q_project_name_short}}]] only: If low memory issues emerge in {{project_name_workstation_short}}, additional resources can be freed by reducing RAM in {{project_name_gateway_short}} with [[RAM_Adjusted_Desktop_Starter|rads]].
= 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 ==
{{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?
* What is your hard drive's health status?
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.
* [[#gsmartcontrol|Run gsmartcontrol]] to rule out hard drive defects.
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 Whonix-Host operating system) 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.
* Choose memory test (memtest86+.elf).
* memory test (memtest86+.bin, serial console) serial console not needed.
'''4.''' Keep memtest86+ running for a significant period.
A single pass of memtest86+ from 0 to 100% progress is insufficient. The memory testing should be run for as long as practically possible; for example, ideally overnight or for 8+ hours. This is because RAM issues might not happen during memtest86+'s first pass. Sometimes only after a few 10 minutes or few hours issues can be detected because the issue might be related to stress, heat and not be easily and quickly reproducible.
'''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.]
}}
== gsmartcontrol ==
{{Box|text=
'''1.''' Install the gsmartcontrol+ tool.
On Debian (based) hosts such as [[Kicksecure]].
{{Install Package|package=
gsmartcontrol
}}
For other host operating systems, refer to gsmartcontrol upstream documentation.
'''2.''' Reboot.
'''3.''' Start gsmartcontrol.
'''4.''' Run the short and extended tests on all hard drives.
'''5.''' Done.
The hard drive test is complete.
If gsmartcontrol 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 (hard drive). [
Hard drive warranties may apply.
]
}}
= See Also =
* [[RAM|Advice for Systems with Low RAM]]
* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]
* [[Qubes/Troubleshooting|{{q_project_name_long}} Troubleshooting]]
* [[Recovery|Recovery Mode]]
* [[SysRq|System Recovery using SysRq Key]]
* [[Core Dumps]]
= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]