whonixcheck done
whonixcheck in progress
whonixcheck in Konsole


whonixcheck is a bash script, checking many important things. Supports to be run in console and also has a grapical progress meter and graphical info popup for the results. It is stored in /usr/bin/whonixcheck and in /usr/lib/whonix/whonixcheck/. Whonix will also work without that script. It only checks things, it doesn't change things. Nothing is compiled, it is just a script and anyone can read the source code.

The whonixcheck script was inspired by In past when people were still recommended to use proxy settings to torify web browsers, it was an important check. While manual torification of web browsers is nowadays recommended against, Tor Browser, which is securely pre-configured, still visits check.tpo and checks if everything is okay. Check.tpo also checks if the Tor Browser version is up to date (technically Tor Button downloads version information and checks locally).

While check.tpo just checks the browser, Whonix is more than a browser. It is a complete operating system. Therefore when the browser starts, it is already too late. It has to be checked earlier, because the user might not start the browser. That's why whonixcheck will be automatically started after boot/login (if it hasn't been recently run, i.e. if whonxicheck has been completed within 24 hours earlier).

whonixcheck will run once every day, even if the system is not restarted. The motivation behind that is also to inform long running systems.

Some users wish to hide the fact from their ISP, they they are using Tor and Whonix. See Hide Tor and Whonix from your ISP article. While only a fraction of users goes through the procedures to hide Tor, it is still desirable to hide the fact they're using Whonix. We're better off if adversaries can't distinguish between lets say Tor Browser and Whonix users. When whonixcheck is automatically started, it waits a randomized amount of time (between 60 and 500 seconds). Although it would be Tor's job to prevent any kinds of conclusions from the amount of traffic and the traffic pattern, this feature is supposed to aid to obfuscation of that kind of traffic analysis. Starting Tor and instantly having a lot of traffic (from whonixcheck) might be easier to distinguish than waiting a randomized amount of time until that kind of traffic flows.

Running Whonixcheck[edit]

By default, Whonixcheck runs automatically from time to time whenever the user starts up a Whonix-Workstation (commonly called whonix-ws). Whonixcheck verifies that the Whonix system is up-to-date and that everything is in proper working order.

Even though Whonixcheck should run automatically and periodically, [1] users can also manually run Whonixcheck to check the system status by following the directions 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 check -> whonixcheck / System Check

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

Start Menu -> System -> whonixcheck

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: SocksPort Test Result: Connected to Tor. IP: 

INFO: TransPort Test Result: Connected to Tor. IP: 

INFO: Stream Isolation Test Result: Functional. 

INFO: Whonix News Result:
√ Up to date: whonix-workstation-packages-dependencies 3.4.2-1

INFO: Debian Package Update Check Result: No updates found via apt-get. 

INFO: Whonix APT Repository: Enabled. When the Whonix team releases JESSIE updates, they will be AUTOMATICALLY installed (when you run apt-get dist-upgrade) along with updated packages from the Debian team. Please read to understand the risk. If you want to change this, use: 
dom0 -> Start Menu -> Template: whonix-ws -> Whonix Repository 

Tor Bootstrap[edit]

Tor bootstrap refers to the process of attempting to connect to the Tor network (successfully or unsuccessfully). Familiar output related to this process includes: "Tor connecting xx percent...", "Tor not connected", "Tor connected" and so on. Bootstrapping does not refer to related concepts, such as whether connections are "secure", "not secure", "anonymous" or "not anonymous".


  • If run either on supported platforms bare metal (Physical Isolation), VirtualBox, KVM or Qubes. Warns when using an unsupported (by Whonix developers) virtualizer. Reports only if not. Otherwise quiet unless using --verbose.
  • Checks if the clock source is KVMClock and warns if that is the case. Might probably only happen for users using the KVM instructions. Reports only if KVMClock is detected. Otherwise quiet unless using --verbose.
  • Checks that whonixsetup is done. Reports only if not. Otherwise quiet unless using --verbose.
  • Checks that Tor is enabled. Reports only if not. Otherwise quiet unless using --verbose.
  • Check the validity of Tor's config files by using sudo tor --verify-config. Whonix-Gateway only. Reports only error. Otherwise quiet unless using --verbose.
  • Check if a package manager is currently running. Waits as long as a package manager is running until it continues. It waits, because the Tor package or Dev/CPFP is currently upgraded, connection checks would fail. Otherwise quiet unless using --verbose.
  • Checks, that Tor has been enabled (i.e., that DisableNetwork 1) has been commented out from /etc/tor/torrc (by whonixsetup or manually). Reports only if not. Otherwise quiet unless using --verbose.
  • Check if the Tor process (pid) is running. Only on Whonix-Gateway. Reports error if not. Otherwise quiet unless using --verbose.
  • Checks if IP forwarding is disabled on gateway.
  • entropy availability check: Checks is /proc/sys/kernel/random/entropy_avail contains no less than 112 bytes.
  • When using --verbose: Checks if ~/.whonix/msgdispatcher-error.log or ~/.whonix/whonix_torbrowser_updater_error.log exist and reports, if so.
  • Checks if Control Port Filter Proxy is running.
  • Tor connection / IP
    • Tor Bootstrap Status
    • (1) downloads with curl through extra SocksPort
    • (2) downloads with curl through TransPort
    • The Whonix design ensures, that never the users real IP can be detected. Why check it anyway? Sometimes check.tpo reports false positives and fails to detect Tor exit nodes. The user should be informed about that possibility. That reduces support requests and bad press. It is fine to investigate if the Tor exit node could not be detected, but we're quite confident, that the outcome will be, that it is a Tor exit node IP. Some users may do dangerous and/or unsupported things, such as changing Whonix-Workstation's network interface from internal network "Whonix" to bridged or NAT or other creative and adventurous things, such as using virtualizers which are entirely unsupported and untested by Whonix developers. Last but not least, users can and are encouraged to install upgrades using apt-get and free to install arbitrary packages on Whonix-Workstation. In a totally unexpected case, that may open up for a leak and whonixcheck is Whonix's last layer of defenses against such leaks.
    • On Whonix-Workstation: Stream Isolation, checks IP from (1) and (2) differ.
  • Tor Browser version
  • Checks if a package manager is currently running. (Eventually the system is locked or the package manager in a broken state. Advices what to do in such situations.)
  • operating system updates: Runs apt-get update through separate apt-get SocksPort (for stream isolation) and inform about the system being up to date or requiring updates. Using security workaround for unreliable apt-get exit codes. [3]
  • Meta Package Check: Accordingly checks if on a the whonix-gateway or whonix-workstation package is installed. (The packages which depend on all other recommended/default installed packages. See also Whonix_Debian_Packages.)
  • Whonix version and Whonix news
    • Supposed to work even if Whonix repository is down / changed.
    • Supposed to work also for users who do not wish to use Whonix-APT-Repository (at all times).
    • Not yet implemented: to defeat a permanent takedown threat.
    • Downloads Whonix News Files with curl through extra whonix news SocksPort.
    • Is supposed to reflect most important news for people not even following Whonix Important Blog. In theory, if an IP leak in Whonix where found or exit nodes actively exploiting apt-get traffic, this would be used to briefly inform users about the danger.
    • Whonix News Format
    • Whonix version and news file must be signed by Whonix developer Patrick.
    • Patrick's gpg key got copied to whonix_shared/usr/share/whonix/keys/whonix-keys.d/ at build time.
    • Warns if the file can not be gpg verified with Patrick's gpg key. In that case version and news is ignored.
    • Messages signed more than one month ago are rejected and the user is informed about the message being no longer valid.
    • Also see Trust.
  • Hostname
    • Checks, if hostname --fqdn outputs host.localdomain.
    • Checks, if hostname outputs host.
    • Checks, if hostname --ip-address outputs
    • Checks, if hostname --domain outputs localdomain.
  • Informs if Whonix-APT-Repository is enabled and if yes, which one is enabled.

Version Numbers[edit]

Whonix Build Version[edit]

The version number of the build. It never changes. And that is fine. At build time [4] the current Whonix version number is being added to the image itself. [5] It is there so whonixcheck can find out which version of the build script has created that version. This version number is supposed to never change. This is because sometimes updating or other issues do only apply to version created by specific, mostly older versions of the build script. This helps with diagnostic purposes therefore, should we ever need to deprecate a specific build version (because it would be too difficult/expensive to upgrade), then whonixcheck's #Whonix News could inform about this.


The ca-certificates Debian package is installed on Whonix. Curl will verify the SSL certificate for downloads from check.tpo (SocksPort Test, TransPort Test, Tor Browser version check) and aborts if the certificate is not valid.

Attack surface for this script includes at least curl, apt-get, gpg, grep, sed, bash, uwt, torsocks, zenity, pgrep. Patrick believes, that benefits outweigh the risks not running those checks. The user is free to sudo chmod -x /usr/bin/whonixcheck and Patrick remains as always open for reviews and suggestions.

Also see SSL.

SSL Certificate Pinning[edit]


In whonixcheck 1.1-1 / Whonix 10 and above there will be an optional certificate pinning option for SocksPort Test, TransPort Test and Tor Browser Update Check. If you want to use this, see below.


Moved to: Next#whonixcheck_SSL_Certificate_Pinning.

Defaults Discussion[edit]

For reasons for (not) enabling this feature by default, see Dev/SSL Certificate Pinning#Defaults Discussion.

Source Code Introduction[edit]

/usr/bin/whonixcheck sourcees:

Then runs functions whonixcheck_main while passing command line arguments.

Function whonixcheck_main then calls:

  • function parse_cmd_options while passing command line arguments
  • function preparation
  • then uses function whonixcheck_run_function to run all other functions. The order differs for Whonix-Gateway and Whonix-Workstation. To find out how exactly and in which order, please have a look at /usr/bin/whonixcheck. The purpose of function whonixcheck_run_function is to allow users adding function names to configuration variable whonixcheck_skip_functions which allows to skip certain functions. (See also whonixcheck Hardening.)

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

For a simple example have a look at file /usr/lib/whonixcheck/check_entropy which contains function check_entropy. You can just do any information gathering and analysis as you want. In essence, in the function check_entropy example, that is.

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

Then you can use, copy and paste, common boilerplate for making what you found out 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"

Or if you wanted to only output it, if the user has run whonixcheck with --verbose, then you could use.

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

Other useful variables are available.

  • $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 more examples, please look what other functions in folder /usr/lib/whonixcheck/ are doing.

Silent Mode[edit]

Whonix-Gateway Whonix-Workstation
run in after boot (autostart mode) Yes [6] No [7]
run regularly during run (daemon mode) No [8] No [9]
situation action
Tor bootstrapping fast enough [10] "Connected to Tor" passive popup only.
Tor bootstrapping not done "Connecting to Tor" passive popup + success "Connected to Tor" passive popup when done or active error popup with advice when failed
grave issue [11] [12] found active error popup with advice
no grave issue found no gui output
manual run of whonixcheck Then silent gets set to 0. Resulting in progress bar + run all tests [13] + active popup with results when done (like in Whonix 11).
  • always skip disclaimer when running inside Qubes
  • made whonixcheck more silent, suitable for Qubes AppVM design

1) If running in Qubes, when autostarted (after boot) -> silent=3
2) If running in Qubes, when daemon (planed iteration during run) -> silent=3
3) Silent only applies to autostart and daemon mode. When manually run, show all messages. Same as Whonix 11.
4) overview of various silent levels

  • silent lower/equal 0: show SocksPort and TransPort "Test Result: Connected to Tor. IP" messages
  • silent greater/equal 1: no "whonixcheck was recently run, no need to run it again, you could still manually start it" message.
  • silent lower/equal 2: do test SocksPort and TransPort but only report errors (no connectivity, Tor not detected and false positives)
  • silent greater/equal 2: no "Tor Bootstrap Result: Connected to Tor." message unless bootstrapping took a while and a progress bar was shown
  • silent greater/equal 2: do test stream isolation, but only report errors
  • silent greater/equal 2: no Whonix News result if there are no news and debian and build version up to date
  • silent greater/equal 2: no "No updates found via apt-get" message
  • silent greater/equal 3: no Tor SocksPort / TransPort test at all
  • silent greater/equal 3: no stream isolation test at all
  • silent greater/equal 3: no Whonix News check at all
  • silent greater/equal 3: no apt-get update check at all
  • silent greater/equal 3: skip to inform if Whonix repository is enabled
  • silent greater/equal 3: no progress bar for the usual tests. Except a progress bar if Tor is not bootstrapped yet.
  • silent greater/equal 3: skip test if a package manager is already running.
  • silent greater/equal 4: skip test whether Whonix repository enabled/disabled test at all. In other words, do not report disabled Whonix repository.


Use Cases[edit]

  • automated test: run after automatic boot by an automated test suite
  • automatic run after boot: as connectivity progress information (Tor bootstrap check) (in progress... done [or failed])
  • automatic run after boot: as a general sanity check [run gateway in ProxyVM, not AppVM, IP forwarding disabled, clock sanity, and much more]
  • manual by the user: as connection functionality test
  • manual by the user: as connection leak test
  • manual by the user: as a general sanity check
  • manual by the user: as a general system security and anonymity check
  • manual by the user: as an information gather tool, shows Whonix Debian Package Version (and when using with --verbose it shows Whonix build version)
  • manual by the user: as a VPN / tunnel functionality test
  • to educate users: when they add a VPN, it breaks stream isolation


  • non-zero exit codes when at least one warning or error was detected [for automated test suite] (Done in Whonix 14)
  • check for failed systemd units [except perhaps apparmor] [for automated test suite] (Done in Whonix 14)
  • on error -> short error message, separate help button opens help, separate technical details drop down button shows debugging information


  1. This does not happen every time the user starts a Whonix-Workstation.
  2. Qubes VM Manager -> right-click on the Whonix VM you want to check -> select "Run command in VM"

    Type the following.
    Then press.

    Type the following.


    Then press.

  4. The time at which the image was created.
  5. The anon-shared-build-log-build-version package, 70_log_build_version chroot script does in essence.
    echo "$anon_dist_build_version" > "/var/lib/anon-dist/build_version"
  6. To possibly give feedback in case of Tor bootstrapping is slow or grave issues.
  7. Less popups. Avoid duplicate popups (such as Tor bootstrapping not done yet).
  8. Could result in a disruptive error popup while the user is doing something entirely different. Such as if the user has not been using Whonix-Gateway/Tor for a while and Tor is no longer connected, it would report this issue. If it is only a transient error, we are better off. If it is a permanent error that will get visible later, the user will hopefully run whonixcheck manually.
  9. When using for example 5 AppVMs that would cause 5 error popups.
  10. (Tor connected when whonxicheck runs function check_tor_bootstrap)
  11. For example, if unwanted packages are installed
  12. See also #Checks.
  13. Verbose ones only when using --verbose.

Random News:

Want to get involved with Whonix? Check out our Contribute page.

https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)