From Whonix

(Redirected from Whonix Build Version)

whonixcheck completion
whonixcheck progress meter
whonixcheck in Konsole


whonixcheck is a bash script which checks numerous, important system variables. whonixcheck can be run in a CLI environment (such as in terminal emulator xfce4-terminal) or via the GUI option, which has an in-built progress meter and summary notification popup of the results. The script is stored in the /usr/bin/whonixcheck and /usr/lib/whonix/whonixcheck/ directories. Whonix ™ is functional without the whonixcheck script since it only checks the system status; it is not responsible for core settings. Nothing is compiled, and the script can be easily inspected in the source code.

The whonixcheck script was inspired by [archive]. In the past this was an important check when people were still recommended to use proxy settings to torify web browsers. Tor Browser is now securely pre-configured upon release, which means manual torification of web browsers is now recommended against. As an additional protection the default Tor Browser visits to confirm everything is working as expected. [1] This site also checks whether Tor Browser is up-to-date by having Tor Button perform a local check after downloading version information. is useful for a browser check, but Whonix ™ is a complete operating system. This means certain checks must be performed before the browser starts, otherwise a user's anonymity or security might be compromised. whonicheck's design allows the entire Whonix ™ community to stay informed about important updates or advice, and this is particularly important for users who might not start the browser or visit the Whonix ™ website regularly. For these reasons, whonixcheck is automatically started after boot/login if it has not been completed within the last 24 hours. This behavior holds true even if the system is not restarted, thereby keeping any long-running systems (like Onion Services) safely informed.

If it is necessary to hide Tor and Whonix ™ use from an ISP, see here. While only a small minority of users configure their system to hide Tor, it is still desirable to hide any obvious Whonix ™ signature. Whonix ™ users are better off if adversaries cannot distinguish them from vanilla Tor Browser users, as the Whonix ™ user pool is far smaller.

When whonixcheck auto-starts, it first waits for a randomized period of time ranging between 60 and 500 seconds. This obfuscation feature is intended to further stymie traffic analysis, while Tor is still responsible for basic defenses against traffic volume and pattern signatures. Without waiting for a randomized period traffic flows would be more distinguishable, since a spike in whonixcheck traffic would always occur immediately after bootstrapping.

Running whonixcheck[edit]

whonixcheck verifies that the Whonix system is up-to-date and that everything is in proper working order.

Users can manually run whonixcheck to check the system status by following the steps below.

How to Manually Run whonixcheck[edit]

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

Qubes App Launcher (blue/grey "Q")click on the Whonix VM you want to checkwhonixcheck / System Check

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

Start MenuSystemwhonixcheck

If you are using a terminal-only Whonix, complete the following steps.


Depending on the system specifications, whonixcheck may take up to a few minutes to run. Assuming everything is working as intended, the output should highlight each INFO heading in green (not red). A successful whonixcheck process results in output similar to the sample below.

Sample whonixcheck Output[edit]

[INFO] [whonixcheck] anon-whonix | Whonix-Workstation | whonix-ws-15 TemplateBased AppVM | Sat 09 Nov 2019 03:40:10 AM UTC
[INFO] [whonixcheck] Connected to Tor.
[INFO] [whonixcheck] Whonix APT Repository: Enabled.
When the Whonix team releases BUSTER-PROPOSED-UPDATES updates, they will be AUTOMATICALLY installed (when you run apt-get dist-upgrade) along with updated packages from the Debian team. Please read http://www.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/wiki/Trust [archive] to understand the risk.
If you want to change this, use:
sudo whonix_repository
[INFO] [whonixcheck] Debian Package Update Check: Checking for software updates via apt-get... ( Documentation: http://www.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/wiki/Update [archive] )
[INFO] [whonixcheck] Debian Package Update Check Result: No updates found via apt-get.
[INFO] [whonixcheck] Please donate!
See: http://www.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/wiki/Donate [archive]

System Checks[edit]

In all the checks below, whonixcheck warnings appear if a problem is detected. Conversely, whonixcheck output is otherwise quiet unless using the --verbose option. Any operating system updates, downloads or other network activity are stream-isolated by default.

Table: whonixcheck System Checks

Check Description
Clock Source Check if the clock source is KVMClock and warn if that is the case. [3]
Control Port Filter Proxy Check if Control Port Filter Proxy is running.
Entropy Test An entropy availability check confirms /proc/sys/kernel/random/entropy_avail contains no less than 112 bytes.
Hostname Check if:
  • hostname --fqdn outputs host.localdomain.
  • hostname outputs host.
  • hostname --ip-address outputs
  • hostname --domain outputs localdomain.

Also inform if Whonix-APT-Repository is enabled, and if so, which repository has been selected.

IP Address Routing Check if IP forwarding is disabled on Whonix-Gateway ™ (sys-whonix).
Log Inspection When using the --verbose option, check if ~/.whonix/msgdispatcher-error.log or ~/.whonix/whonix_torbrowser_updater_error.log exist and report this if confirmed.
Meta-package Check Check if the relevant meta-packages [4] are installed on Whonix-Gateway ™ (sys-whonix) or Whonix-Workstation ™ (anon-whonix). Also see: Whonix ™ Debian Packages.
Network Connection Check whonixsetup has properly configured networking.
Operating System Updates apt-get update is run through a separate apt-get SocksPort for stream isolation. A notification is provided whether the system is up-to-date or requires updating.
Package Manager Check if a package manager is currently running and wait until the process is finished. [5] This prevents connection failures during concurrent upgrades of the Tor or Control Port Filter Proxy packages.
Tor Check:
  • If Tor has been enabled by inspecting if DisableNetwork 1 has been commented out from /usr/local/etc/torrc.d/50_user.conf either manually or via whonixsetup.
  • If the Tor process (pid) is running on Whonix-Gateway ™ (sys-whonix).
  • The validity of Tor configuration files in Whonix-Gateway ™ (sys-whonix) by using sudo tor --verify-config.

Notify about the Tor connection / IP address. [6] [7]

Tor Bootstrap and Browser Version Tor Bootstrap Status:
  1. Download [archive] with curl through an extra SocksPort.
  2. Download [archive] with curl through TransPort.

On Whonix-Workstation ™ (anon-whonix), a Stream Isolation test checks the IP addresses from (1) and (2) differ.

Tor Browser version:

Virtualization Platform Check Whonix ™ is being run on one of the supported virtualizer platforms, including bare metal (Physical Isolation), VirtualBox, KVM or Qubes.

Version Numbers[edit]

Whonix ™ Build Version[edit]

The version number of the Whonix ™ build never changes. This is acceptable because at build time [8] the current Whonix ™ version number is added to the image itself. [9] This information is made available so whonixcheck can determine which build script version was used to create that particular image.

This version number should remain static and be unaffected by updating or other issues, since it only applies to specific (usually older) versions of the build script. This is useful for diagnostic purposes and means specific build versions can be deprecated if they are too difficult or expensive to upgrade. In this case, whonixcheck's Whonix ™ News function would inform users about the change.

Check Version[edit]

To check the current Whonix ™ version, run the following command.

whonixcheck --verbose --function show_versions

Should show something like the following.

[INFO] [whonixcheck] sys-whonix | Whonix-Gateway ™ | whonix-gw-14 TemplateBased ProxyVM | Sat Sep 29 01:32:56 UTC 2018
[INFO] [whonixcheck] Input Detection: INPUT_AUTO=true CLI=true GUI=false
stdin connected to terminal. Using cli output. Not using gui output.
Alternatively, if want to run from command line, but still use the graphical user interface for input, you could add to command line: --gui
[INFO] [whonixcheck] Root Check Result: Ok, not running as root.
[INFO] [whonixcheck] Pin certificate: disabled.
[INFO] [whonixcheck] whonix_build_version: 3:2.5-1
[INFO] [whonixcheck] whonix-gateway-packages-dependencies-cli: 7.9-1
[INFO] [whonixcheck] /etc/whonix_version: 14


When using whonixcheck with parameter --leak-tests curl will verify the SSL certificate for downloads from -- SocksPort Test, TransPort Test, -- and abort if the certificate is not valid. The ca-certificates Debian package [archive] is installed on Whonix ™.

When manually running this test, attack surface for this script includes at least curl, apt-get, gpg, grep, sed, bash, uwt, torsocks, zenity, and pgrep. Whonix ™ developers have assessed that the benefits of this check outweigh the potential risks.

SSL Certificate Pinning[edit]


By default, Whonix ™ has not yet implemented direct SSL certificate pinning for using curl. [10] The intent is to eventually provide users with an optional certificate pinning option for the SocksPort Test, TransPort Test and Tor Browser Update Check. To manually configure this setting, see below.


These instructions have moved to: whonixcheck SSL Certificate Pinning.

Defaults Discussion[edit]

Interested readers can learn more about why this feature is not enabled by default here.

Source Code Introduction[edit]

whonixcheck Information Sources[edit]

/usr/bin/whonixcheck [archive] sources:

  1. /usr/lib/msgcollector/error_handler [archive]
  2. /usr/lib/helper-scripts/tor_enabled_check [archive]
  3. /usr/lib/helper-scripts/pkg_manager_running_check [archive]
  4. Followed by all files in /usr/lib/whonixcheck/ [archive] in lexical order.

whonixcheck Operation[edit]

After gathering the above information, whonixcheck runs functions in whonixcheck_main while passing command line arguments.

Function whonixcheck_main then calls:

  1. Function parse_cmd_options [archive] while passing command line arguments.
  2. Function preparation [archive].
  3. Then uses function whonixcheck_run_function [archive] to run all other functions. [11]

Additional Functions[edit]

The /usr/lib/whonixcheck/ folder is not a real .d style plugin drop-in folder. The shell function for separate [Whonix ™, unit] checks can be placed in separate files for better readability. The provided functions are then supposed to be run from /usr/bin/whonixcheck function whonixcheck_main.

As a simple example, inspect the file /usr/lib/whonixcheck/check_entropy [archive] which contains function check_entropy. Users can gather as much information as they like for analysis via this function.

entropy_size="$(cat "$entropy_file")"
if [ "${entropy_size}" -lt "112" ]; then

Now it is possible to use, copy and paste, or create a common boilerplate for making discoveries visible.

local MSG="<p>Entropy Available Check Result: low. <code>$entropy_file</code>: <code>$entropy_size</code> Please report this issue!</p>"
$output ${output_opts[@]} --messagex --typex "warning" --message "$MSG"
$output ${output_opts[@]} --messagecli --typecli "warning" --message "$MSG"

To limit the notifications to those running whonixcheck with the --verbose option, add.

 if [ "$verbose" = "1" ]; then

Other useful variables include:

  • $VM "Whonix-Gateway" or "Whonix-Workstation ™"
  • $vm_lower_case_short "gateway" or "workstation"
  • $whonix_codename /etc/apt/sources.list.d/whonix.list codename
  • $whonix_codename_uppercase
  • $DAEMON = 1 run in daemon mode
  • $AUTOSTARTED = 1 run after boot
  • $manualrun = 1 manually run
  • $ARCH "$(uname --machine)"
  • $whonix_build_version
  • $whonix_deb_package_version

For further examples, please inspect the behavior of other functions in folder /usr/lib/whonixcheck/

Silent Mode[edit]

Table: whonixcheck Default Operation

Category Whonix-Gateway Whonix-Workstation ™
Runs after boot (autostart mode) Yes [12] No [13]
Runs regularly during Whonix ™ operation (daemon mode) No [14] No [15]

Table: whonixcheck Notification Matrix

Circumstance Notification
Tor bootstrapping completes promptly [16] "Connected to Tor" passive popup only
Tor bootstrapping is incomplete "Connecting to Tor" passive popup and successful "Connected to Tor" passive popup when finished, or an active error popup with advice when it fails
Grave issue [17] [18] found Active error popup with advice
No grave issue found No GUI output
Manual run of whonixcheck Then silent is set to 0, resulting in a progress bar and run of all tests [19] and active popup with results when complete

Other Silent Mode Settings[edit]

whonixcheck was specifically made more silent to suit the Qubes AppVM design:

  • When autostarted (after boot): silent=3
  • Daemon mode (planed iteration during run): silent=3
  • Silent only applies to autostart and daemon mode. When it is manually run, all messages are shown. [20]

Table: Silent Level Overview

Silent Level Action
Silent <= 0
  • Show SocksPort and TransPort "Test Result: Connected to Tor. IP" messages
Silent >= 1
  • No "whonixcheck was recently run, no need to run it again, you could still manually start it" message
Silent <= 2
  • Complete a SocksPort and TransPort test, but only report errors [21]
Silent >= 2
  • No "Tor Bootstrap Result: Connected to Tor." message unless bootstrapping was slow and a progress bar was shown
  • Perform test stream isolation, but only report errors
  • No Whonix ™ News result if there is no news and the Debian and build version are up-to-date
  • Absent "No updates found via apt-get" message
Silent >= 3
  • No Tor SocksPort / TransPort test is conducted
  • No stream isolation test at all
  • No Whonix ™ News check at all
  • No apt-get update check at all
  • Skip notification if Whonix ™ repository is enabled
  • No progress bar for the usual tests, except a progress bar if Tor has not bootstrapped yet
  • Skip the test for a concurrently running package manager
Silent >= 4
  • Skip the test for whether Whonix ™ repository is enabled/disabled. [22]


Use Cases[edit]

whonixcheck has specific use cases when it should be run either manually or automatically.

Automated Tests[edit]

Run after automatic boot by an automated test suite.

Auto-start Following Boot[edit]

  1. To provide connectivity progress information (Tor bootstrap check), with the familiar "in progress...", "done" (or failed) messages.
  2. As a general sanity check, for instance: the gateway is a ProxyVM and not an AppVM, IP forwarding is disabled, the clock is sane, and much more.

Manual User Start[edit]

  1. Connection functionality test.
  2. Connection leak test.
  3. General sanity check.
  4. General system security and anonymity check.
  5. As an information gathering tool, for example reporting the Whonix ™ Debian package and build version (build version requires the --verbose option).
  6. VPN / tunnel functionality test.
  7. To educate users that stream isolation is broken when adding a VPN.

Planned Features[edit]

When an error occurs, provide: [23]

  • A short error message.
  • A separate help button which opens advice relating to the problem.
  • A separate technical details drop-down button which contains debugging information.


  1. Tor Browser in Whonix ™ is configured to load a local Whonix ™ resource after launch -- the familiar landing page.
  2. Qube Managerright-click on the Whonix VM you want to checkselect "Run command in qube"

    Type each command below, followed by the ENTER key.


  3. This is only expected to affect those following the KVM instructions.
  4. These capture packages which depend on all other recommended / default-installed packages.
  5. Otherwise, eventually the system is locked or the package manager is left in a broken state. Advice is provided on what to do in such circumstances.
  6. Some users may wonder why it is necessary to check the IP address if the Whonix ™ design ensures that the real IP cannot be leaked. Sometimes reports false positives and fails to detect Tor exit nodes, so it is better to provide information about that possibility. This also reduces support requests and bad press. Users are welcome to investigate a Tor exit node that could not be detected, but it can be stated with high confidence that the IP address will be associated with a known Tor exit node.
  7. Another reason to perform this check is because some users set up dangerous and/or unsupported configurations, such as:
    • Changing the Whonix-Workstation ™ (anon-whonix) network interface from internal network "Whonix" to bridged or NAT.
    • Using virtualizers which are entirely unsupported and untested by Whonix ™ developers.
    • Installing arbitrary packages on Whonix-Workstation ™ (whonix-ws-15). This could theoretically create leak vectors, and whonixcheck is the last layer of defense against such leaks.
  8. The time at which the image was created.
  9. The anon-shared-build-log-build-version [archive] package, 70_log_build_version [archive] chroot script in essence runs:
    echo "$anon_dist_build_version" > "/var/lib/anon-dist/build_version"
  10. [archive]
  11. The order differs for Whonix-Gateway ™ (sys-whonix) and Whonix-Workstation ™ (anon-whonix). For detailed information concerning differences, see /usr/bin/whonixcheck. The purpose of function whonixcheck_run_function is to allow users to add function names to configuration variable whonixcheck_skip_functions, which permits the skipping of certain functions. Also see: whonixcheck Hardening.
  12. It is necessary to provide feedback if Tor bootstrapping is slow or there are other grave problems.
  13. This is designed to reduce the number and duplication of popups, like when Tor bootstrapping has not yet finished.
  14. Otherwise this could lead to a disruptive error popup while the user is doing something entirely different. One example is if the user has not used Whonix-Gateway ™ (sys-whonix) / Tor for a while and Tor is no longer connected, this would be reported. If it is only a transient error, users are better off. If it is a permanent error that will be visible later, the user will hopefully run whonixcheck manually.
  15. For example, if five AppVMs were in operation that would cause five error popups.
  16. Tor is connected when whonxicheck runs function check_tor_bootstrap
  17. For example, if unwanted packages are installed.
  18. Also see: System Checks.
  19. Verbose output still requires the --verbose option.
  20. The same as Whonix ™ 11.
  21. Relating to no connectivity, Tor not being detected and false positives.
  22. In other words, do not notify about a disabled Whonix ™ repository.
  23. Issues resolved in Whonix ™ 14 include:
    • Non-zero exit codes when at least one warning or error was detected [for automated test suite]; and
    • Check for failed systemd units (except perhaps apparmor) for automated test suite.

text=Jobs in USA
Jobs in USA

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Share: Twitter | Facebook

Have you read our Documentation, Design and Developer Portal links yet?

https link onion link

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.