Troubleshooting

From Whonix

Troubleshooting-114197640.jpg

Connectivity Troubleshooting[edit]

Essential Connectivity Troubleshooting Steps[edit]

In case of connectivity issues:

1. "Forget" about Whonix ™ for a moment and imagine you had never heard of the platform. Test your host computer first.

2. Test if the host internet connection is functional. [1]

Open different websites such as whonix.org in a host web browser. If the host internet connection is dysfunctional, Whonix ™ connectivity will also be broken. The host internet connection needs to be fixed first.

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

4. VPN/proxy related connectivity issues.

Using a VPN or proxy? (UserTorproxy/VPN/SSHInternet) 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.

5. Check the date and time. [2]

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. (details)

If not, fix host clock, power off VM and restart the VM.

6. Do not change system timezone setting.

7. 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 (link to sources) and have the potential to cause broken, unreliable and slow connections. [3]

8. 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 [3] and would also be more secure, resistant to de-anonymization attacks.

9. Check if Tor Browser works on the host to rule out a possible Network Obstacle.

Download the Tor Browser Bundle from torproject.org and test if it is working on the host.

If the Tor Browser Bundle is not functional on the host, then Whonix ™ is unlikely to work either. In that case, see unspecific to Whonix ™.

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 Whonix ™ will similarly require them.

Follow one of the methods outlined in Non-Whonix ™ Tor Browser.

10. Run systemcheck.

11. Forget about ping.

12. Check if other virtual machines have Internet connectivity, such as newly created ones or those from a different vendor.

See General Virtualizer Connectivity Test.

13. ICMP

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

14. Tor Connectivity Troubleshooting.

Information pertaining to these points should be included in any support request or bug report.

ICMP Fix[edit]

Using a dial-up connection? Or is Tor bootstrapping stuck at 45%?

ICMP is disabled in Whonix ™ by default for security reasons because only a minority of users require it.

Try allowing incoming ICMP on Whonix-Gateway.

1. Modify Whonix-Gateway ™ User Firewall Settings.

Note: If no changes have yet been made to Whonix ™ Firewall Settings, then the Whonix ™ User Firewall Settings File /usr/local/etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix ™, complete these steps.
In Whonix-Gateway ™ App Qube. Make sure folder /usr/local/etc/whonix_firewall.d exists.

sudo mkdir -p /usr/local/etc/whonix_firewall.d

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ App Qube (commonly called sys-whonix)Whonix ™ User Firewall Settings

If using a graphical Whonix-Gateway ™, complete these steps.

Start MenuApplicationsSettingsUser Firewall Settings

If using a terminal-only Whonix-Gateway ™, complete these steps.

In Whonix-Gateway ™, open the whonix_firewall configuration file in an editor.

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_gateway_default.conf.

Note: The Whonix ™ Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_gateway_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When {{project_name_long}} is updated, this
## file may be overwritten.

See also Whonix modular flexible .d style configuration folders.

To view the file, follow these instructions.

If using Qubes-Whonix ™, complete these steps.

Qubes App Launcher (blue/grey "Q")Template: whonix-gw-16Whonix Global Firewall Settings

If using a graphical Whonix-Gateway ™, complete these steps.

Start MenuApplicationsSettingsGlobal Firewall Settings

If using a terminal-only Whonix-Gateway ™, complete these steps.

In Whonix-Gateway ™, open the whonix_firewall configuration file in an editor.

nano /etc/whonix_firewall.d/30_whonix_gateway_default.conf

2. Paste.

GATEWAY_ALLOW_INCOMING_ICMP=1

3. Save.

4. Reload Whonix-Gateway ™ Firewall.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Reload Whonix ™ Firewall

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemReload Whonix ™ Firewall

If you are using a terminal-only Whonix-Gateway ™, run.

sudo whonix_firewall

5. Done.

The process of enabling ICMP on Whonix-Gateway is complete.

There might be a more restricted ICMP permission but it is not implemented. Contributions welcome!

Also see this related forum discussion.

Advanced Connectivity Troubleshooting Steps[edit]

Info These Advanced Connectivity Troubleshooting Steps are supplementary and not a substitute, "better", or a shortcut.

1. Start with the Essential Connectivity Troubleshooting Steps above.

2. Consider Clearnet Connectivity Test.

3. Investigate virtualizer-specific troubleshooting.

4. Check General Troubleshooting steps.

Clock Fix[edit]

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 Whonix ™ Post Install Advice:

To protect against time zone leaks, the system clock inside Whonix ™ 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 Manually Set Clock Time and Date.

Clearnet Connectivity Test[edit]

Ambox warning pn.svg.png Warning: The following test might reveal the Whonix ™ 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. [4]

On Whonix-Gateway ™, run.

sudo -u clearnet UWT_DEV_PASSTHROUGH=1 curl --tlsv1.3 --proto =https -H 'Host: check.torproject.org' -k https://116.202.120.181

General Virtualizer Connectivity Test[edit]

If networking is unavailable inside Whonix ™, then try:

  1. Installing an operating system in a non-Whonix ™ virtual machine or downloading a regular image without Tor enforcement.
  2. Testing network functionality in a freshly downloaded non-Whonix ™ virtual machine.

If networking is still not functional, then Whonix ™ 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-Whonix ™ VMs as part of the support request or bug report.

Unsuitable Connectivity Troubleshooting Tools[edit]

The following tools have limited usefulness when attempting to fix connectivity issues.

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:

  1. Ask for user input.
  2. Create Tor configuration file.
  3. Restart Tor.
  4. 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 high-level level programming language tools developed by a third party. [5] These tools have a limited "understanding" of Tor's internals, let alone other aspects of the system configuration that might be broken. [6] 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:

Other recommended steps mentioned on this page are far more promising.

Why can't I Ping the Whonix-Gateway ™?[edit]

The Whonix-Gateway ™ does not respond to ping or similar commands because it is firewalled for security reasons; see /usr/bin/whonix_firewall or refer to the Whonix ™ source code. In most cases it is unnecessary to ping the Whonix-Gateway ™ anyhow.

If you insist on pinging the Whonix-Gateway ™ or have a unique setup that requires it, then this can be tested by clearing all firewall rules with the dev_clearnet script. Alternatively, a script can be run to try and unload / remove every iptables rule, or the Whonix ™ 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[edit]

Introduction[edit]

Troubleshooting issues can be time intensive and success cannot be guaranteed. Some users expect Whonix ™ to provide an easy experience similar to a Windows machine. While the Whonix ™ developers make every effort to meet user expectations, limited funding and human resources makes meeting these expectations impossible.

Even though problems emerge when using Whonix ™, the cause is most often unrelated to Whonix ™ code. For example, users often report the same Whonix ™ 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 link=https://www.kicksecure.com/wiki/Linux User Experience versus Commercial Operating Systems 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[edit]

info The following recommended steps will fix many startup, freezing or other unusual issues in Whonix ™. Skips steps that are no longer possible, such as the "run systemcheck" command if a virtual machine is no longer bootable.

1. "Forget" about Whonix ™ for a moment and imagine you had never heard of the platform. Test your host computer first.

2. Exclude basic hardware issues.

3. Ensure the virtual machine (VM) images have been imported into a supported virtualizer listed on the Download page.

4. Run systemcheck, if possible.

This verifies the Whonix ™ 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. [7]

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

sudo dpkg --configure -a

7. Debian (based) Linux host operating system users only: Next attempt to retrieve all available updates.

sudo apt update

sudo apt full-upgrade

8. Check for possible Low RAM Issues.

9. Virtualizer-specific troubleshooting.

10. Try a non-Whonix VM.

Check if other VMs are functional, such as newly created ones or those from a different vendor.

  1. "Forget" about Whonix ™ for a moment and imagine you had never heard of the platform. Test the virtualizer host software first.
  2. Try a VM other than Whonix ™ such as Debian bullseye.
  3. If the issue persists, this means the root issue is not caused by Whonix ™, see: unspecific to Whonix ™. In this case, attempt to resolve the issue as per Free Support Principle.

11. Check System Logs.

12. If a graphical environment (where one can use a computer mouse) is unavailable after booting, utilize a virtual console to acquire system logs.

  1. Recovery, Virtual Consoles.
  2. Check system logs of the previous boot (step 11).

13. Use recovery mode to acquire system logs.

  1. Boot in recovery mode.
  2. 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 using a chroot for recovery.

Low RAM Issues[edit]

If insufficient RAM is available for Whonix ™ VMs they might become unusable. Low RAM issues in Whonix ™ are commonly caused by:

  • Unnecessary processes running and/or multi-tasking on the host OS.
  • Multiple, open browser tabs.
  • Unnecessary processes running in the Whonix ™ VM(s).
  • Allocating more RAM to the Whonix ™ VM than is available; this prevents the VM from booting.
  • Insufficient RAM allocated to the Whonix ™ VM(s).
  • Other non-Whonix ™ 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.

See also: Advice for Systems with Low RAM.

Free up Additional Memory Resources[edit]

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 Whonix ™ VMs.
  • Non-Qubes-Whonix ™ only: If low memory issues emerge in Whonix-Workstation ™, additional resources can be freed by reducing RAM in Whonix-Gateway ™ with rads.

To add additional RAM to the Whonix ™ VM(s), follow the platform-specific advice below.

KVM[edit]

1. Shut down the virtual machine(s).

virsh -c qemu:///system shutdown <vm_name>

2. Increase the maximum memory.

virsh setmaxmem <vm_name> <memsize> --config

3. Set the actual memory.

virsh setmem <vm_name> <memsize> --config

4. Restart the virtual machine(s).

virsh -c qemu:///system start <vm_name>

Qubes-Whonix ™[edit]

Utilize Qube Manager:

  • Qube ManagerVM_nameQubes settingsAdvancedMax memory: mem_size

VirtualBox[edit]

  1. To add RAM in VirtualBox the VM must first be powered down.
  2. Virtual machineMenuSettingsAdjust Memory sliderHit: OK

See also: VirtualBox/Troubleshooting.

System Logs[edit]

[8]

Check Systemd Journal Log of Current Boot[edit]

To inspect the systemd journal log of the current boot, run.

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.

sudo journalctl -b > ~/systemd-log

Use any available editor to read the log file, such as mousepad.

mousepad ~/systemd-log

Watch Systemd Journal Log of Current Boot[edit]

It is possible to to watch the systemd journal log as it is written.

sudo journalctl -b -f

Enable Persistent Systemd Journal Log[edit]

By default, a persistent systemd journal log is not enabled in Debian. [9] To enable it, apply the following steps.

Platform specific notes:

  • Non-Qubes-Whonix: No special steps are required; follow the steps below.
  • Qubes users: The following changes must be applied in a VM with a persistent root image like a Template or Standalone. It could be confusing if applied in App Qubes since the systemd journal log might be mixed up with boots by the Template, while the App Qube systemd journal logs would not be persistent. bind-dirs might be helpful, but further research is required.

1. Create folder /etc/systemd/journald.conf.d.

sudo mkdir -p /etc/systemd/journald.conf.d

2. Open file /etc/systemd/journald.conf.d/60_persistent_journal.conf in an editor with root rights.

(Qubes-Whonix ™: In Template)

This box uses sudoedit for better security. This is an example and other tools could also achieve the same goal. If this example does not work for you or if you are not using Whonix ™, please refer to this link.

sudoedit /etc/systemd/journald.conf.d/60_persistent_journal.conf

3. Add the following setting.

[Journal] Storage=persistent

Save.

4. Restart systemd-journald.

sudo systemctl restart systemd-journald

A persistent systemd journal log has now been enabled.

Check Systemd Journal Log of Previous Boot[edit]

After following the Enable Persistent Systemd Journal Log steps, it is possible to inspect the systemd journal log of the previous boot.

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.

sudo journalctl -b -1 > ~/systemd-log-previous

Use any available editor to read the log file, such as mousepad.

mousepad ~/systemd-log-previous

View List of Systemd Journal Logs[edit]

sudo journalctl --list-boots

Daemon Log View[edit]

To view the log of a specific systemd unit. Syntax:

(Replace unit-name with the actual name of the systemd unit.)

sudo journalctl -b --no-pager -u unit-name

Example:

sudo journalctl -b --no-pager -u sdwdate

Daemon Log Follow[edit]

To follow the log of a specific systemd unit. Syntax:

(Replace unit-name with the actual name of the systemd unit.)

sudo journalctl -f -b --no-pager -u unit-name

Example:

sudo journalctl -f -b --no-pager -u sdwdate

Daemon Status[edit]

To view the status of a specific systemd unit. Syntax:

(Replace unit-name with the actual name of the systemd unit.)

sudo systemctl status --no-pager unit-name

Example:

sudo systemctl status --no-pager sdwdate

Check Systemd Journal Log of Failed Boot[edit]

An alternative to recovery mode might be 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: 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:

  1. Boot into Recovery Mode.
  2. Enable Persistent Systemd Journal Log (if not previously enabled).
  3. Reboot into normal mode so a log for the failed boot will be written (if not previously enabled).
  4. Boot into recovery mode again.
  5. Check Systemd Journal Log of Previous Boot.

Permission Fix[edit]

info 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: Safely Use Root Commands.

Open a terminal.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ App Qube (commonly named anon-whonix)Xfce Terminal

If you are using a graphical Whonix ™ with XFCE, run.

Start MenuXfce Terminal

sudo chown --recursive user:user /home/user

Hardware Issues[edit]

General Recommendations[edit]

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. [10]
  • Run memtest86+ to rule out RAM problems.
  • Run gsmartcontrol to rule out hard drive defects.

None of these issues are related to Whonix ™. Therefore, please do not ask these questions in Whonix ™ support channels (until there is a Whonix-Host operating system) as per Free Support Principle.

memtest86+[edit]

1. Install the memtest86+ tool.

On Debian (based) hosts such as Kicksecure.

Install package(s) memtest86+.

A. Update the package lists and upgrade the system.

sudo apt update && sudo apt full-upgrade

B. Install the memtest86+ package(s).

Using apt command line parameter --no-install-recommends is in most cases optional.

sudo apt install --no-install-recommends memtest86+

C. Done.

The procedure of installing package(s) memtest86+ is complete.

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). [11]

gsmartcontrol[edit]

1. Install the gsmartcontrol+ tool.

On Debian (based) hosts such as Kicksecure.

Install package(s) gsmartcontrol.

A. Update the package lists and upgrade the system.

sudo apt update && sudo apt full-upgrade

B. Install the gsmartcontrol package(s).

Using apt command line parameter --no-install-recommends is in most cases optional.

sudo apt install --no-install-recommends gsmartcontrol

C. Done.

The procedure of installing package(s) gsmartcontrol is complete.

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). [12]

See Also[edit]

Footnotes[edit]

  1. By using ping. For example, ping 8.8.8.8. On the host, run.
    ping 8.8.8.8
    Ping google.com and/or other websites.
    ping google.com
    and so on.
  2. date
  3. 3.0 3.1 https://forums.whonix.org/t/time-too-long-error-or-very-long-time/12716/4
  4. This test only uses TCP and not DNS.
  5. 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.

  6. Such as broken networking in either the host network or in all virtual machines.
  7. 7.0 7.1 This process can be lengthy.
  8. "user support template": https://forums.whonix.org/t/workstation-keeps-freezing/7693/6
  9. https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=801906
  10. Perform thorough research beforehand.
  11. RAM bank warranties may apply.
  12. Hard drive warranties may apply.