{{Header}}
{{#seo:
|description=Troubleshooting Installation and Network Issues with {{project_name_long}}.
|image=Troubleshooting-thumbnail.jpg
}}
<div class="mininav">
* [[#Connectivity Troubleshooting|Connectivity Troubleshooting]]
* [[#General Troubleshooting|General Troubleshooting]]
</div>
[[File:Troubleshooting-thumbnail.jpg|300px|thumb]]
{{intro|
Troubleshooting Installation and Network Issues with {{project_name_short}}.
}}
= Introduction =

{{#widget:Icon_Bullet_List|fontSize=18px
|item=fa-solid fa-1 cs-green,On this page you will find help for <b>various troubleshooting topics</b>, including general troubleshooting, connectivity troubleshooting
|item=fa-solid fa-2 cs-green,You will also learn about <b>virtual machine bug analysis, system logs</b> and other related topics
|item=fa-solid fa-3 cs-green,Please be aware that some very specific, individual problems <b>can take a long time</b> to research and solve. Don't expect a "magic solution" for most of these issues
|item=fa-solid fa-4 cs-green,We will help you with a lot of common problems here, but also be sure to <b>check out <a href="/wiki/Documentation">our Documentation</a></b> and related pages.
}}

= Connectivity Troubleshooting =

This chapter covers connectivity issues that you may encounter.

== Introduction ==

* '''There is no general network problem analysis tool.''' While there are many tools and commands available for specific aspects of network diagnostics, there isn't a single built-in command for any operating system that performs a fully comprehensive, automated network analysis with one execution.
* '''Shortcut? There is no shortcut:''' Network diagnostics require a systematic approach, where each potential issue must be carefully examined and ruled out one by one. Unlike other processes that may offer quick fixes or automated solutions, network troubleshooting involves methodically testing different aspects of the network to identify the root cause of a problem. This process is inherently time-consuming. Attempting to rush through diagnostics or skipping steps can lead to incomplete or inaccurate conclusions, making the resolution process even longer. Therefore, persistence and attention to detail are essential when working through network issues, as there is no single tool or command that can automatically solve all potential problems.
** '''Is there really no shortcut? There is not'''. While a theoretical "shortcut" might exist, it would be economically infeasible. See the footnote for details. <ref>
While a Linux kernel developer could attach a debugger to analyze low-level operations, doing so for a common network error shown by Firefox, such as <code>DNS_PROBE_FINISHED_NO_INTERNET</code>, is generally impractical and unnecessary for several reasons:
** '''Complexity:''' Kernel debugging is complex and requires deep system knowledge. It involves analyzing system calls, network stack processes, and possibly kernel code, which is overkill for typical network issues.
** '''Time-Consuming:''' Setting up a kernel debugger environment, reproducing the issue, and analyzing the results can take significantly more time than standard troubleshooting methods.
** '''Expenses:''' There are few people with the skills required. Hiring a developer with these skills would be more expensive than standard network troubleshooting.
* '''User expectations:''' Debugging attempts are not guaranteed to work, but they are encouraged to help fix outstanding issues.

For everyday network issues, especially those related to DNS, using standard troubleshooting techniques and tools is more efficient and safer.
</ref>
* '''How to proceed:''' Please run the following checklist in the next chapter. Please ensure that you have completed all steps in this checklist. The results of each step should be included in your support request. Omitting these steps, failing to provide this information result will most likely result in unresolved connectivity issues.

```wiki
== Essential Connectivity Troubleshooting Steps ==
In case of connectivity issues, please complete the following checklist:

{{Box|text=
{{IconSet|h2|1}} '''Make sure you started Whonix-Gateway first.'''

For a functional network connection, [[Whonix-Gateway]] must be started before [[Whonix-Workstation]].

{{IconSet|h2|2}} '''Download source.'''

Did you download {{project_name_short}} from {{project_clearnet}}? If downloaded from other sources, uninstall and try downloading from {{project_clearnet}} instead.

{{IconSet|h2|3}} '''Test your host computer first.''' 

"Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test your host computer first.

{{IconSet|h2|4}} '''Test if the host internet connection is functional.''' <ref>
By using ping.

For example, ping <code>8.8.8.8</code>.

On the host, run.

{{CodeSelect|code=
ping 8.8.8.8
}}

Ping <code>google.com</code> and/or other websites.

{{CodeSelect|code=
ping google.com
}}

and so on.
</ref>

Open different websites such as <code>{{project_clearnet}}</code> 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.

{{IconSet|h2|5}} '''Speed and ping test the host internet connection.'''

Running an internet speed test and ping test might show if there is something wrong with the host internet connection.

{{IconSet|h2|6}} '''VPN/proxy related connectivity issues.'''

Using a VPN or proxy? ('''<code>User</code> &rarr; <code>Tor</code> &rarr; <code>proxy/VPN/SSH</code> &rarr; <code>Internet</code>''') If yes, the following tests should be performed.

{{IconSet|h3|A}} The host internet connection and speed without VPN and without Tor should be tested first.

{{IconSet|h3|B}} Next, the host internet connection should be tested with a VPN only but without Tor.

{{IconSet|h3|C}} Only then should complex setups such as Tor in combination with a VPN be tested.

{{IconSet|h2|7}} '''Check the date and time. <ref>'''
{{CodeSelect|code=
date
}}
</ref>

Check if the host clock time and date have 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.

{{IconSet|h2|8}} '''[[timezone|Do not change system timezone setting.]]'''

{{IconSet|h2|9}} '''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. <ref name=bridges-and-wifi-slow-report>
https://forums.whonix.org/t/time-too-long-error-or-very-long-time/12716/4
</ref>

{{IconSet|h2|10}} '''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 <ref name=bridges-and-wifi-slow-report /> and would also be more secure, resistant to de-anonymization attacks.

{{IconSet|h2|11}} '''Check if Tor Browser works on the host to rule out a possible [[Network Obstacle]].'''

Download the Tor Browser Bundle from [https://www.torproject.org/download/ torproject.org] and test if it is working on the host.

If the Tor Browser Bundle is not functional on the host, then {{project_name_short}} is unlikely to work either. In that case, see [[Unspecific|unspecific to {{project_name_short}}]].

It is recommended to have a recent Tor Browser Bundle version installed at all times. This way users can test if they live in a censored area or not and whether Tor is blocked by the ISP. Further, if (private) (obfuscated) [[bridges]] are necessary for Tor Browser Bundle functionality on the host, then {{project_name_short}} will similarly require them.

Follow one of the methods outlined in [[Install_Tor_Browser_Outside_of_{{project_name_short}}|Non-{{project_name_short}} Tor Browser]].

{{IconSet|h2|12}} '''Run {{kicksecure_wiki
|wikipage=systemcheck
|text=systemcheck
}}'''.

Because when <code>systemcheck</code> 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}}.

{{IconSet|h2|13}} '''[[Whonix-Workstation_Firewall#Ping|Forget about <code>ping</code>.]]'''

{{IconSet|h2|14}} '''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]].

{{IconSet|h2|15}} '''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.

{{IconSet|h2|16}} '''RELATED state fix (regarding iptables)'''

Try [[#RELATED Fix|RELATED Fix]].

{{IconSet|h2|17}} '''ICMP fix'''

Using dial-up connection? Or Tor bootstrapping stuck at 45%? See [[#ICMP Fix|ICMP Fix]].

{{IconSet|h2|18}} '''[[Tor#Connectivity_Troubleshooting|Tor Connectivity Troubleshooting]].'''

{{IconSet|h2|19}} '''Consider continuation with [[Troubleshooting#Advanced_Connectivity_Troubleshooting_Steps|Advanced Connectivity Troubleshooting Steps]].'''
}}

Information pertaining to these points should be included in any [[Support|support]] request or [[Reporting_Bugs|bug report]].
```

== RELATED state fix (regarding iptables) ==
{{Anchor|RELATED_Fix}}

{{box|text=
{{IconSet|h2|1}} '''{{Firewall_Settings}}'''

{{IconSet|h2|2}} '''Paste.
'''
{{CodeSelect|code=
GATEWAY_ALLOW_INCOMING_RELATED_STATE=1
}}

{{IconSet|h2|3}} '''Save.'''

{{IconSet|h2|4}} '''{{Reload_Firewall}}'''

{{IconSet|h2|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=
{{IconSet|h2|1}} {{Firewall_Settings}}

{{IconSet|h2|2}} Paste.

{{CodeSelect|code=
GATEWAY_ALLOW_INCOMING_ICMP=1
}}

{{IconSet|h2|3}} Save.

{{IconSet|h2|4}} {{Reload_Firewall}}

{{IconSet|h2|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=
{{IconSet|h2|1}} Start with the [[#Essential Connectivity Troubleshooting Steps|Essential Connectivity Troubleshooting Steps]] above.

{{IconSet|h2|2}} Consider [[#Clearnet Connectivity Test|Clearnet Connectivity Test]].

{{IconSet|h2|3}} Investigate virtualizer-specific troubleshooting.

* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]

{{IconSet|h2|4}} Check [[#General Troubleshooting|General Troubleshooting]] steps.

{{IconSet|h2|5}} Support requests.

Posting in forums, reddit, etc. most likely won't help. Most likely nobody will be able to suggest a simple method on how to easily fix this. See footnote for examples. <ref>
https://www.reddit.com/r/Whonix/comments/1easzpq/the_hellish_5_problem_plz_help/
</ref>

The only chance is to go through the troubleshooting guide step-by-step. Then please include the results for each troubleshooting step in the support request. Tedious, yes, but unfortunately there is no better option.
}}

== 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]]:

<blockquote>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. <u>Do not change this setting!</u></blockquote>

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. <ref>This test only uses TCP and not DNS.</ref>

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}}, start by testing the virtualizer host software as if you've never encountered {{project_name_short}}. This will give you a baseline. This can be done by trying the following steps:

{{IconSet|h2|1}} '''Install a Standard Virtual Machine''': Install a non-{{project_name_short}} operating system. This means to install an operating system in a virtual machine that does not run {{project_name_short}}. A good candidate would be Debian <code>{{Stable project version based on Debian codename}}</code>.

{{IconSet|h2|2}} '''Test Network Functionality''': Test the network functionality in this freshly downloaded or created standard virtual machine.

{{IconSet|h2|3}} '''DONE.'''

'''If Networking is Non-Functional:'''

If networking is still not functional in these standard virtual machines, then {{project_name_short}} will not work either. It indicates that the problem isn't caused by to {{project_name_short}}. Such issues that are [[unspecific]] to {{project_name_short}} should be tackled according to these guidelines:

* In case of VirtualBox: [[VirtualBox/Troubleshooting#VirtualBox_Generic_Bug_Reproduction|VirtualBox Generic Bug Reproduction]]
* [[Self_Support_First_Policy|Self Support First Policy]]
* [[Reporting_Bugs#Generic_Bug_Reproduction|Generic Bug Reproduction]]

The user must first resolve this issue, which might require:

* Re-installation of the virtualizer.
* Rebooting the system.
* Conducting further connectivity tests.

'''If Networking is Functional:'''

If networking is functional in the standard virtual machines, then users should:

* Note that networking is working in non-{{project_name_short}} VMs.
* Include this information as part of the support request or bug report for {{project_name_short}}.

These steps will help ensure that the underlying network infrastructure is working correctly before troubleshooting {{project_name_short}} specific issues.

== 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. <ref>
<blockquote>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.<blockquote></ref> These tools have a limited "understanding" of Tor's internals, let alone other aspects of the system configuration that might be broken. <ref>Such as broken networking in either the host network or in all virtual machines.
</ref> 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 <code>ping</code> 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 =

This chapter covers general issues that you may encounter and solution approaches.

== 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=
{{IconSet|h2|1}} '''Test your host computer first.'''

"Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. Test your host computer first.

{{IconSet|h2|2}} '''Exclude basic [[#Hardware Issues|hardware issues]].'''

{{IconSet|h2|3}} '''Ensure the virtual machine (VM) images have been imported into a supported virtualizer''' listed on the [[Download]] page.

{{IconSet|h2|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.

{{IconSet|h2|5}} '''Debian (based) Linux host operating system users only: The following command should not show any errors.''' <ref name=lengthy_test>
This process can be lengthy.
</ref>

{{CodeSelect|code=
sudo dpkg-reconfigure -a
}}

{{IconSet|h2|6}} '''Debian (based) Linux host operating system users only: The following command should be silent and not show any errors or output at all.''' <ref name=lengthy_test />

{{CodeSelect|code=
sudo dpkg --configure -a
}}

{{IconSet|h2|7}} '''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
}}

{{IconSet|h2|8}} '''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]].

{{IconSet|h2|9}} '''Virtualizer-specific troubleshooting.'''

* [[VirtualBox/Troubleshooting|VirtualBox Troubleshooting]] / [[VirtualBox/Troubleshooting#General VirtualBox Troubleshooting Steps|General VirtualBox Troubleshooting Steps
]]
* [[KVM#Troubleshooting|KVM Troubleshooting]]

{{IconSet|h2|10}} '''Try a non-Whonix VM.'''

Attempt [[Virtualizer Generic Bug Reproduction|#Generic Bug Reproduction]].

{{IconSet|h2|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 <u>Current</u> Boot]].
* Sometimes it is necessary to [[#Check Systemd Journal Log of Previous Boot|Check Systemd Journal Log of <u>Previous</u> Boot]].

{{IconSet|h2|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).

{{IconSet|h2|13}} '''Use recovery mode to acquire system logs.'''

# Boot in [[Recovery#Recovery_Mode|recovery mode]].
# Check system logs of previous boot (step 11).

{{IconSet|h2|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 <u>must</u> first be powered down.
# <code>Virtual machine</code> &rarr; <code>Menu</code> &rarr; <code>Settings</code> &rarr; <code><i>Adjust</i></code> <code>Memory slider</code> &rarr; <code><i>Hit:</i> OK</code>

See also: [[VirtualBox/Troubleshooting]].
}} <!-- close VirtualBox tab -->
{{Tab
|type=section
|title= === KVM ===
|content=
{{KVM_RAM}}
}} <!-- close KVM tab -->
{{Tab
|type=section
|title= === Qubes-Whonix ===
|content=
Utilize Qube Manager:

<code>Qube Manager</code> &rarr; <code>VM_name</code> &rarr; <code>Qubes s<u>e</u>ttings</code> &rarr; <code>Advanced</code> &rarr; <code>Max memory:</code> <code><i>mem_size</i></code>
}}<!-- close Qubes-Whonix tab -->
}}<!-- close tab controller -->

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]].

= Virtualizer Generic Bug Reproduction =
{{Anchor|Generic_Bug_Reproduction}}

'''{{Icon|fa-solid fa-info cs-blue}} This chapter teaches you how check virtual machines for generic bugs that have nothing to do with {{project_name_short}}.'''

Check if other VMs are functional, such as newly created ones or those from a different vendor. If an issue is happen inside {{project_name_short}}, start by testing the virtualizer host software as if you've never encountered {{project_name_short}}. "Forget" about {{project_name_short}} for a moment and imagine you had never heard of the platform. This will give you a baseline. This can be done by trying the following steps:

# '''Install a Standard Virtual Machine''': Install a non-{{project_name_short}} operating system. This means to install an operating system in a virtual machine that does not run {{project_name_short}}. A good candidate would be Debian <code>{{Stable project version based on Debian codename}}</code>.
# '''Test the Feature''': Test the functionality in this freshly downloaded or created standard virtual machine.

'''If the Feature is Non-Functional:'''

If the feature is still not functional in these standard virtual machines, then {{project_name_short}} will not work either. It indicates that the problem isn't caused by to {{project_name_short}}. Such issues that are [[unspecific]] to {{project_name_short}} should be tackled according to these guidelines:

* In case of VirtualBox: [[VirtualBox/Troubleshooting#VirtualBox_Generic_Bug_Reproduction|VirtualBox Generic Bug Reproduction]]
* [[Self_Support_First_Policy|Self Support First Policy]]
* [[Reporting_Bugs#Generic_Bug_Reproduction|Generic Bug Reproduction]]

The user must first resolve this issue, which might require:

* Re-installation of the virtualizer.
* Rebooting the system.
* Conducting further tests.
* Reading upstream documentation.
* Contacting upstream support.

'''If the Feature is Functional:'''

If feature is functional in the standard virtual machines, then users should:

* Note that the feature is working in non-{{project_name_short}} VMs.
* Include this information as part of the support request or bug report for {{project_name_short}}.

These steps will help ensure that the underlying feature is working correctly before troubleshooting {{project_name_short}} specific issues.

= System Logs =

Use the system logs to your advantage.

<ref>
"user support template": https://forums.whonix.org/t/workstation-keeps-freezing/7693/6
</ref>

== 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 &uarr;, &darr;, &larr;, &rarr;, as well as <code>PgUp</code> and <code>PgDn</code> 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 <code>~/systemd-log</code>.

{{CodeSelect|code=
sudo journalctl -b > ~/systemd-log
}}

Use any available editor to read the log file, such as <code>mousepad</code>.

{{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 &uarr;, &darr;, &larr;, &rarr;, as well as <code>PgUp</code> and <code>PgDn</code> 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 <code>~/systemd-log-previous</code>.

{{CodeSelect|code=
sudo journalctl -b -1 > ~/systemd-log-previous
}}

Use any available editor to read the log file, such as <code>mousepad</code>.

{{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 <code>unit-name</code> 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 <code>unit-name</code> 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 <code>unit-name</code> 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 =

Fix permissions that might not be set correctly.

{{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 =

These are hardware issue that you may encouter.

== 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. <ref>Perform thorough research beforehand.</ref>
* [[#memtest86+|Run <code>memtest86+</code>]] to rule out RAM problems.
* [[#gsmartcontrol|Run <code>gsmartcontrol</code>]] 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=
{{IconSet|h2|1}} Install the <code>memtest86+</code> tool.

On Debian (based) hosts such as [[Kicksecure]].

{{Install Package|package=
memtest86+
}}

For other host operating systems, refer to <code>memtest86+</code> upstream documentation.

{{IconSet|h2|2}} Reboot.

{{IconSet|h2|3}} Start <code>memtest86+</code> from (grub) boot menu.

* Choose <code>memory test (memtest86+.elf)</code>.
* <code>memory test (memtest86+.bin, serial console)</code> serial console not needed.

{{IconSet|h2|4}} Keep <code>memtest86+</code> running for a significant period.

A single pass of <code>memtest86+</code> 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 <code>memtest86+</code>'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.

{{IconSet|h2|5}} Check the <code>memtest86+</code> output.

If there are any issues, red error messages appear in the middle of the screen.

{{IconSet|h2|6}} Done.

The memory test is complete.

If <code>memtest86+</code> 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). <ref>RAM bank warranties may apply.</ref>
}}

== gsmartcontrol ==
{{Box|text=
{{IconSet|h2|1}} Install the <code>gsmartcontrol+</code> tool.

On Debian (based) hosts such as [[Kicksecure]].

{{Install Package|package=
gsmartcontrol
}}

For other host operating systems, refer to <code>gsmartcontrol</code> upstream documentation.

{{IconSet|h2|2}} Reboot.

{{IconSet|h2|3}} Start <code>gsmartcontrol</code>.

{{IconSet|h2|4}} Run the short and extended tests on all hard drives.

{{IconSet|h2|5}} Done.

The hard drive test is complete.

If <code>gsmartcontrol</code> 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). <ref>
Hard drive warranties may apply.
</ref>
}}

= 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]]