Jump to: navigation, search

Dev/Build Documentation/Physical Isolation/11

Random News:

Did you know, that Whonix has some protection against backdoors? The Verifiable Builds feature only adds security if people like you actually use it!

WARNING: Please don't forget reading the Warnings and First time user chapter.



Technical Introduction[edit]

When setting up Whonix in the form of two Virtual Machines running on the same physical host, exploits targeting the VM implementation or the host can still break out of the torified Client VM and expose the IP of a user. Malware running on the host has full control over all VMs. To protect such attacks we need a different approach: In this context we called it Physical Isolation, because the gateway system is installed on separate hardware. This drastically reduces the TCB[1] by more than the half.

In total we'll be installing and configuring two computers and set up an isolated point to point network between them (you could also set up a an ordinary, completely isolated, LAN behind the Whonix-Gateway). One computer acts as the client or "Whonix-Workstation", the other as a proxy or "Whonix-Gateway" which will transparently route all of the Whonix-Workstation's traffic through Tor.

The Whonix-Gateway on its own physical device can either run directly on hardware or inside a virtual machine. Both options have advantages and disadvantages. We recommend to use no additional Virtual Machine for the Whonix-Gateway.

The Whonix-Workstation should always be installed in a Virtual Machine: A VM hides hardware serial numbers. See also Recommendation to use multiple VM Snapshots.

The host operating system(s) should only be used for downloading operating system updating, hosting Whonix-Gateway or Whonix-Workstation and nothing else.

Bonus points if the physical systems are exclusively used for hosting Whonix, or if storage devices are separated for Whonix and non-Whonix use cases, to avoid a Whonix hard drive getting infected by a another operating system.

First time user?[edit]


WARNING: Less tested than VM builds. Needs your help for more rigid testing!

WARNING: Instructions are difficult. Only advanced Linux users can understand them.

WARNING: Dev/Build Anonymity has not been considered for this article.

WARNING: Do also read the warnings in the latest build instructions for VM images. Some of them, Don't add private files to Whonix's source code folder! and Check if the OpenPGP public keys are still up to date. also applies to the physical isolation page.

WARNING: This article currently lacks information about Whonix-Gateway's and Whonix-Workstation's MAC address. See also:

WARNING: Joanna Rutkowska, security researcher, developer of Qubes OS made a security comparison about software compartmentalization vs. physical separation (pdf), that concluded, that in some cases, notably for specific, desktop-related workflows, Physical Isolation might be less secure sometimes than Qubes (software compartmentalization) approach. (See also: Qubes-Whonix.)

Using spare hardware + Virtual Machine[edit]


  • You can install a graphical host.
  • Use the Whonix download version.
  • You can use the graphical network manager on the host, for example to connect to WiFi.
  • You can setup easily a VPN on the host. Tor will be tunneled through the VPN.


  • Higher attack surface, because the Virtual Machine code get's involved.

Using spare hardware without Virtual Machine[edit]


  • More secure, because less code is involved.


  • Slightly more complicated setup
  • More difficult to set up VPN
  • More difficult to set up 3G networking compared to using a Windows host



We recommend that you use two dedicated computers for Whonix that are never used for activities that could lead back to your identity. Alternatively you can use an already existing and otherwise used computer for the Whonix-Gateway. To offer some isolation you should disconnect all internal and external drives and boot from a eSATA, USB or another internal drive into a clean environment.

non-anonymous use[edit]

  • non-anonymous box (leave it as it is, like you want)
  • non-anonymous home dial up internet router (leave it as it is, like you want)

anonymous use[edit]

  • Whonix-Gateway
    • This really does not have to be a big desktop computer or ordinary server. There are alternatives.
    • smartphone [2],
    • UMPC[3]
    • pad, tablet,
    • notebook, netbook,
    • Raspberry Pi[4]: needs contributor, development thread
    • router [5],
    • set top box,
    • etc.
    • how to utilize such a device as a linux server is beyond the scope of this guide, there are already better resources
  • anonymous 3G modem (see below) or anonymous wifi adapter (see below)
  • Whonix-Workstation
    • You get the idea. Use a device which suits you.

Before installing[edit]

Read and apply the Pre Installation Security Advice.


  • System Requirements
  • Whonix-Gateway: A device with at least two network adapters, at least one of them ethernet [6], capable of running Linux. It will run Debian. [7]
  • Whonix-Workstation: A device connected via ethernet to the Whonix-Gateway. It must only have this one NIC and no other network connectivity! Must be connected by wire.[8] This will be the torified client system or Whonix-Workstation. It must be capable of running Debian.[9]
  • We recommend to use a VM as the client, the same Whonix-Workstation, that most non Physical Isolation users use. [10] [11] [12]
  • Host build environment has a working internet connection to Debian mirrors.
  • General advice from Build Documentation about Build Security applies
  • Optionally, it would be useful, if you knew how to open a second virtual console.

Host Preparation[edit]

  • You need to build on Debian Stable (Wheezy). (How to obtain Debian safely: [13]) [14]
  • Build dependencies and configurations get automatically applied, so you don't have to worry about that. [15]
  • It is recommended to set your terminal (for example Konsole) to unlimited scrollback, so you can watch the full build log.

How To Install Whonix-Gateway on Hardware (RECOMMENDED)[edit]

Get Debian[edit]

Download a Debian Stable/Wheezy 32 bit installation iso. Detailed instructions doing so are unfortunately not part of this guide. However, the Debian page contains some help.

You can choose iso of any desktop environment (KDE, LXDE, Xfce, ...) but since you'll be using the command line, Debian Stable/Wheezy network install (netinst) version is recommended (it's the most minimal).

(You could also use a Debian Stable/Wheezy 64 bit installation iso, these instructions should also work, but it's less tested.)

Install Debian[edit]

In the installer boot menu of Debian Stable (Wheezy) press "Install" and choose following settings:

Select a language: English
Select your location: United States
Configure the keyboard: (select yours)
Hostname: host
Domain name: (empty)
Root password: (set up a strong password)
Full name for the new user: user
Username for your account: user
Password for the new user: (choose a good password, different from root password)
Partitioning method: Guided - use entire disk (it's a good idea to set up cryptsetup encrypted LVM at this point)
Partitioning scheme: All files in one partition (select the listed device in the next step)
Partition disks/overview: Finish partitioning
Write changes to disk: Yes

Debian archive mirror country: Go back
Continue without a network mirror: Yes

Use a network mirror: No
Participate in the package usage survey: No
Software selection: None; deselect all options (using Space)
Install the GRUB boot loader: Yes (select the listed device in the next step)
Finish the installation: Continue


If you are interested in seeing a visual walk-through of the minimal installation of Debian Stable Wheezy, click on Expand on the right.

In the menu select "Install"


Set language as English.


Set location as United States.


Select your keyboard.


Installing additional content.


Network will auto-configure (hopefully).


Set the hostname to "host".


Leave the domain name empty.


Pick a strong root password.


Reenter the password.


Full name should should be "user".


Username should also be "user".


Enter a strong user password.


Reenter the password.


Network time procedure.


Use a guided partitioning method with the whole disk (FDE is a good idea if you plan to use physical isolation or as your main system).


Select the suggested disk.


Partition all files in one partition.


Finish partitioning.


Confirm the changes.


It takes a few minutes to get the base system installed.

39.png 40.png

We don't need any extra packages so don't select a mirror, "Go back".


Confirm that you want to continue without a mirror.


Configuring apt.


"No thanks" to survey participation.


Deselect (no star) the given option (using Space).

45.png 46.png

Install GRUB.


Select your disk.


Finishing the installation.


Done! The system will reboot.


OS screen.


Login screen.



If you are interested in configuring a custom encryption algorithm to enhance security during the minimal installation of Debian Stable Wheezy, click on Expand on the right.

1. Under "Partitioning method", select Manual

2. Select the disk you are installing to and press enter, then select <Yes> to create a new empty partition table.

3. Select the "FREE SPACE" of the drive you are installing to, press Enter, "Create a new partition" should already be selected; press Enter again.

4. Now create a boot partition. This is the unencrypted partition your system boots from. The standard is 254.8 MB. Type "254.8 MB" (without the quotes) and press Enter.

5. Under "Type for the new partition:", Primary should already be selected, press Enter again; Under "Location for the new partition: "Beginning" should already be selected, press Enter again to go to the Partition settings screen.

Use the following settings for your boot partition:

Use as:         Ext2 file system

Mount point:       /boot
Mount options:    noatime
Label:                 none
Reserved blocks:  5%
Typical Usage:     standard
Bootable flag:      on    

Then select "Done setting up the partition" and press Enter, you will be brought back to the main partitioning menu.

6. Select "Configure encrypted volumes" and press Enter, then select <Yes> when asked to write the changes to disk and configure encrypted volumes.

7. Create encrypted volumes should already be selected, press Enter and select the free space of the drive you are installing to by pressing the spacebar, then select <Continue> and press Enter again. Additional components will load, then you will be brought to the configuration page for your encrypted partition. Here you can customize your encryption settings.

Use as:      physical volume for encryption
Encryption method:   Device-mapper (dm-crypt)

Encryption: twofish 
[Recommend "twofish" and "serpent" as alternatives. "Serpent" is the slowest and only recommended if you have a fast system (and a fast drive), as it creates a lot of system overhead. "Twofish" is an algorithm created by Bruce Schneier, and is a lot faster, computationally-speaking. For most use-cases, "twofish" should be sufficient as an alternative algorithm]
Key size:     256 (leave as-is)
IV algorithm:  xts-plain64 
[for most use-cases, xts-plain64 should be sufficient. Do not change this unless you know what you are doing. You could inadvertently create a security hole]
Encryption key: Passphrase (leave as-is)
Erase data: yes (this will wipe the partition)
Bootable flag: off  

8. After you have completed your configuration, select "Done setting up this partition", and press Enter, then select <Yes> and press enter to write the changes to disk, then on the next screen select "Finish", and press Enter.

9. It is highly recommended that you erase the partition before you continue. Please note this may take a while for large drives. If you have already securely wiped your device before starting this installation, you can skip this step. To erase the partition, select <Yes> and press enter.

10. Choose a strong password. This password should be at LEAST 26 characters, including symbols. Remember: the stronger your password, the stronger your encryption. The weaker the password, the weaker your encryption. After entering your password and confirming it, you will be brought back to the main partitioning menu.

11. Under your new "Encrypted volume" (which should be at the top of the list), highlight the partition that was just created under it (it should say ext4), and press Enter. Under "Use as:", change this to "physical volume for LVM", and press Enter, then select "Done setting up the partition", and press Enter again to be brought back to the main partitioning menu.

12. Now select "Configure the Logical Volume Manager" and press Enter.

13. Highlight "Create volume group", and press Enter. Under "Volume group name:", enter HOST_VG, and press Enter.

14. Use the spacebar to select your encrypted partition, then select <Continue> and press Enter.

(Optional) SWAP USERS:

O1. Now create your swap partition. Highlight "Create logical volume" and press Enter, then select HOST_VG and press Enter again. Type SWAP, press Enter.

O2. Enter your volume size (2.5 GB is usually a good standard size for most systems) then select <Continue> and press Enter.

15. Highlight "Create logical volume" and press Enter, then select HOST_VG and press Enter again. Type ROOT, press Enter.

16. Under the "Logical volume size:", your entire volume should already be displayed, press Enter again.

17. Highlight "Finish", then press Enter to be brought back to the main partitioning menu.

18. You should see your new partition for ROOT displayed on this screen [LVM VG HOST_VG, LV ROOT - xxx.x GB Linux device-mapper (linear)]. Select the partition underneath the heading and press Enter

19. Change "do not use" to the filing system of your choice. Ext4 is good for most installations. XFS is more suitable for filesystems on top of encryption and is more robust with better performance. For the purposes of this documentation, the following configuration is provided:

Use as:             XFS journaling file system

Mount point:     / 
Mount options: defaults
Label:               none

20. Once you're done, select "Done setting up this partition", and press Enter to return to the main partitioning menu.

(Optional) SWAP USERS:

O1. You should see your new partition for SWAP displayed on this screen [LVM VG HOST_VG, LV SWAP - 2.5 GB Linux device-mapper (linear)]. Select the partition underneath the heading and press Enter.

O2. Change "do not use" to "swap area", and press Enter. Then select "Done setting up the partition" to return to the main partitioning menu.

21. Highlight "Finish partitioning and write changes to disk" and press Enter, then select <Yes> when asked to confirm the changes. Your installation will continue automatically.

Network Configuration[edit]

The external interface (usually eth0) may need to be configured according to the requirements of your local network, e.g. static or simply left to use dhcp if the gateway is connected to a dhcp capable router. For wlan follow the upstream documentations: debian wiki, Ubuntu help.

Make sure the internet is working.

Logon and upgrade Debian[edit]

Logon, install all security updates and reboot.

## (host) login with "root"

## Add a new repository source.
echo "deb http://ftp.us.debian.org/debian stable main" >> /etc/apt/sources.list

## Refresh package lists and upgrade
apt-get update && apt-get dist-upgrade -y


Install sudo and git. [16]

## Install "sudo" and git.
apt-get install sudo git -y

You must build as user "user" and that user must be a member of the "sudo" group. Rebooting applies the changes.

## Add "user" to "sudo" group
addgroup user sudo

## Reboot the system
shutdown -r now

## (host) login with "user"

You may want to take an image of your installation in case the build script fails in the middle.

Get the Source Code[edit]

Install git and curl

sudo apt-get install git curl

Get source code including git submodules.

git clone --recursive https://github.com/Whonix/Whonix

Remember it's Whonix, not whonix! If you are prompted for a username for github, it means you have mistyped the web address.

Get into the source folder.

cd Whonix

(For experimental, faster, alternative method, see footnote. [17])

Get the Signing Key[edit]

This chapter is recommended for better security, but not strictly required. (See Trust)

Download the key.

curl --tlsv1 --proto =https -o patrick.asc https://www.whonix.org/patrick.asc

Check fingerprints/owners without importing anything.

gpg --with-fingerprint patrick.asc

Verify it shows the following.

pub  4096R/2EEACCDA 2014-01-16 Patrick Schleizer <adrelanos@riseup.net>
      Key fingerprint = 916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA
sub  4096R/CE998547 2014-01-16 [expires: 2016-10-05]
sub  4096R/119B3FD6 2014-01-16 [expires: 2016-10-05]
sub  4096R/77BB3C48 2014-01-16 [expires: 2016-10-05]

If it checks out, import the key.

gpg --import patrick.asc

Only getting the signing key from one source, from the download you want to verify isn't safe. For better security, Learn about Whonix Signing Key.

OpenPGP Verify the Source Code[edit]

This chapter is recommended for better security, but not strictly required.[18]

Get a list of available git tags.

git tag

Verify the tag you want to build.

## ... Replace with tag you want to build.

## Debian Wheezy
git tag -v

## Debian Jessie
git verify-tag

Output should look similar to this.

object 1844108109a5f2f8bddcf2257b9f3675be5cfb22
type commit
tagger Patrick Schleizer <adrelanos@riseup.net> 1392320095 +0000

gpg: Signature made Thu 13 Feb 2014 07:34:55 PM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]

The warning.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

Is explained on the Whonix Signing Key page and can be ignored.

Beginning from git tag 9.6 and above, by convention, git tags should point to signed git commits. (forum discussion) It is recommended to verify the signature of the git commit as well. (Replace with the actual git tag you want to verify.)

## Debian Wheezy.
git log --show-signature -1 "$(git rev-list --max-count 1"

## Debian Jessie.
git verify-commit^{commit}

Output should look similar to this.

commit 5aa1c307c943be60e7d2bfa5727fa5ada3a79c4a
gpg: Signature made Sun 07 Dec 2014 01:22:22 AM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]
Author: Patrick Schleizer <adrelanos@riseup.net>
Date:   Sun Dec 7 01:22:22 2014 +0000


Choose Version[edit]

Git checkout, which version (or git branch) you want to build.

In case you want to build a specific git tag.

git checkout

You have to replace with the actual version you want to build. The stable version, the testers-only version or the developers version. Common sense is required while choosing the right version number. For example, the biggest version number is not necessarily the most recommended / latest stable version. You can learn about current versions reading Whonix News Blogs. New versions are also announced on the whonix-devel mailing list. So you could alternatively check its archives. Signing up for whonix-devel is another way to get informed about new releases.

Clean up and Sanitize[edit]

This is also important for security.

Get a list of eventually extraneous files and folders. [20]

git clean -ndff

And look if that looks sane. (Generally should, unless you are modifying Whonix's source code, then you should understand git a bit better and know what you are doing.) If it looks like the following, everything is fine.

Would remove packages/apparmor-profile-gwenview/
Would remove packages/kde-privacy/

Now get rid of these folders.

git clean -dff

Should show.

Removing packages/apparmor-profile-gwenview/
Removing packages/kde-privacy/

Make sure you have checked out the right commit for each git submodule.

git submodule update --init --recursive

Check if there are no extraneous files. This is important for security.

git status

Should only show and nothing else.

# Not currently on any branch.
nothing to commit (working directory clean)

Otherwise we'd need to get rid of these files first.

Build Configuration (Optional)[edit]

Introduction (Optional)[edit]


Usually you do not have to change the build configuration. Whonix build from source code comes with safe defaults. Whonix's APT Repository will NOT be used.

The most interesting build configurations (Terminal-Only, NoDefaultApps etc.) are documented in the following chapters below.

If you are interested, click on Expand on the right.

If you used build configurations earlier, it might be better to delete your build configuration folder since a few example files names change changed in meanwhile.

sudo rm -r /etc/whonix_buildconfig.d

Alternatively, if you know what you are doing, you can of course also manually get into the /etc/whonix_buildconfig.d folder, examine and change its contents to your linking.

/etc/whonix_buildconfig.d is a modular flexible .d style configuration folder.

Less popular build configurations are documented in the buildconfig.d folder and on the Dev/Source_Code_Intro#Build_Configuration page in a less user friendly documented way.

It is recommended to copy and paste text when creating build configuration files to avoid typos. Also keep care, that your editor even when you are using copy and paste, won't capitalizes variable names which are supposed to be lower case.

Terminal-Only Builds (Optional)[edit]


Advanced users can build a no-default-gui / no-KDE / terminal-only Whonix-Gateway and/or Whonix-Workstation.

If you are interested, click on Expand on the right.

terminal-only builds are less tested due to lack of contributor manpower. Should work well in principle.

## Whonix 10

## Whonix 11
--gui none

NoDefaultApps Builds (Optional)[edit]


Advanced users can install fewer recommended packages to make the resulting build smaller and more customizable. (recommended as in useful to have, not necessary to have them for some other reason.)

If you are interested, click on Expand on the right.

NoDefaultApps builds are less tested due to lack of contributor manpower. Should work well in principle.

NOTE: You most likely want to combine this with terminal-only builds, see above.

NOTE: Such a NoDefaultApps system would for example not include Arm on Whonix-Gateway. So please do not create a NoDefaultApps build and then complain, that packages are missing.

To learn, what packages for example the whonix-gateway-packages-recommended package would install, search in the debian/control file for Package: whonix-gateway-packages-recommended.

We're just excluding a few meta packages. (Meta packages are packages, which do not hold files on its own, but only instruct apt-get to install other packages.)


CurrentSources Builds (Optional)[edit]


Advanced users could install from Current Sources (custom) instead of from Frozen Sources (default in 7.4.0 and above). Both options have security advantages and disadvantages.

If you are interested, click on Expand on the right.

CurrentSources builds are rarely tested due to lack of contributor manpower. Should work reasonably well in principle as long as no packages are removed from Debian. The worst thing that can probably happen, is that the build fails due to missing packages.

Frozen Sources:

  • Whonix's build script will use http://snapshot.debian.org instead of the more popular ftp.us.debian.org.
  • Snapshot.debian.org will never change, i.e. their packages and versions will remain the same forever*[currentsources 1] [currentsources 2].
  • Using Frozen Sources has the advantage that all builders end up with a very similar [currentsources 3] image. This gives builders more confidence, that they have ended up with an intact image.
  • Are a precondition for the Verifiable Builds security feature.
  • It follows, when building a fresh image it will contain outdated packages. (You can upgrade after booting for the first time.)
  • Package downloads are still verified, but we have to ignore the valid-until field. Which means, a man-in-the-middle attack capable adversary could feed you with packages even older than configured in the version of Whonix you are building. Any packages which were ever signed with the APT repository signing key of that codename[currentsources 4]. You might not like that and therefore prefer building from Current Sources.
  • At some point, for example if remotely exploitable vulnerabilities are found in the apt-get version (defined by Frozen Sources) it may be dangerous to continue building that version.
  • We should compare our images with each other to ensure no man-in-the-middle attack has happened while building Whonix.

Current Debian APT repository:

  • Packages and versions may change over time. Packages may be removed, replaced with others, versions get security other other updates.
  • Build script may break the older the Whonix source code version release becomes. (Break as in the build won't finish - not as in creating images containing bugs.)
  • Each builder ends up with an individual image.
  • Valid-until field gets verified.

If you prefer to build from Current Sources, please add the following build script command line argument.



  1. Besides a few rare exceptions.
  2. As long the great snapshot.debian.org service lasts.
  3. Timestamps, temporary files and who knows what else (open research question) differ.
  4. Codename as in Testing, Wheezy, Jessie.

64bit Builds (Optional)[edit]


Advanced users can create 64bit instead of 32bit builds.

If you are interested, click on Expand on the right.

64bit builds are less tested due to lack of developer manpower. Should work well in principle.

By default, Linux 32 bit is used and linux-image-686-pae linux-headers-686-pae linux-image-486 linux-headers-486 kernel is installed. This can be changed using any of the following command line parameters.

Linux 64 bit. Less tested. Only installs linux-image-amd64 linux-headers-amd64 kernel.

## Whonix 10

## Whonix 11
--arch amd64 --kernel linux-image-amd64 --headers linux-headers-amd64

Linux 32 bit. Only installs linux-image-686-pae linux-headers-686-pae kernel. Does not install linux-image-486 linux-headers-486 kernel.

## Whonix 10

## Whonix 11
--arch i386

Linux 32 bit. Only installs linux-image-486 linux-headers-486 kernel. Does not install linux-image-686-pae linux-headers-686-pae kernel.

## Whonix 10

## Whonix 11
--kernel linux-image-amd64 --headers linux-headers-amd64

kFreeBSD 64 bit. Entirely untested.

## Whonix 10

kFreeBSD 32 bit. Entirely untested.

## Whonix 10

Whonix APT Repository (Optional)[edit]


Whonix's APT Repository is disabled by default since Whonix 7.3.3. You may enjoy this for Trust reasons. You can later update Whonix debian packages from source code if you want. If you are interested in enabling Whonix's APT repository right after building (you could do that also after booting your build for the first time if you wanted) for convenience while sacrificing the extra security of not updating from source code, click on Expand on the right side.

Do you want to opt-in for Whonix's APT Repository?

--whonix-apt-repository-distribution wheezy
--whonix-apt-repository-distribution testers
--whonix-apt-repository-distribution developers

Only Minimal Report (Optional)[edit]


By default Whonix's last build step creates a report file of all hdd contents. (See Verifiable Builds for details.) This step is optional. First introduced in Whonix 7.4.8. Whonix should work fine without that step. It is used for extra security. This step takes quite some time. This step is recommended. If you want to disable it, click on Expand on the right side.

Do you want to opt-out of the report creation build step?


APT Cache (Optional)[edit]


When building in a virtual machine, builders can use their own http proxy (apt cache) on the host, which will greatly improve build speed when building several times in a row (debugging, development).

If you are interested, click on Expand on the right.

This isn't required when you are building virtual machine images, because then apt-cacher-ng is automatically set up for you. Only useful when using --install-to-root in a virtual machine.

Requires Whonix or above.


On the host.

sudo apt-get install apt-cacher-ng

Be sure to have a firewall, so not the whole internet can use your apt-cacher-ng service.

Inside your Virtual Machine.

Don't forget to replace with your host's internal IP (use "sudo ifconfig" on your host to find out what your internal IP is).

export http_proxy=

Don't forget to add -E to sudo, so environment variables are preserved. Examples.

sudo -E ./whonix_build --install-to-root --tor-gateway --build
sudo -E ./build-steps.d/1100_prepare-build-machine --install-to-root --tor-gateway

Custom Build Tags[edit]

Only if you are using your own git tags! In that case click on Expand on the right.

If you created for example a git tag "9.1" and want to receive Whonix News for "9", apply this.

Please look into packages/whonixcheck/etc/whonix.d/30_whonixcheck_default. Look for.

## Override what version whonixcheck will show in its window title and which
## Whonix News will be downloaded. Change only if you know what you are doing.

Create a file /etc/whonix.d/50_whonixcheck_user and add for example. (You still have to replace "7" with the custom git tag you are using.


When you later update from Whonix debian packages from for example "9.1" to "10", these settings have to be commented out.

VM Settings (Optional)[edit]


Only relevant for VM builds.

Examples below. Values can be changed.

VirtualBox's --vmsize option (virtual RAM).

--vmram 128

VirtualBox's --vram option (virtual video RAM).

--vram 12

grml-debootstrap's --vmsize option.

--vmsize 200G

grml-debootstrap's --filesystem option.

--file-system ext4

grml-debootstrap's --hostname option. (The anon-base-files package will change that later again.)

--hostname host

grml-debootstrap's --password option.

--os-password changeme

grml-debootstrap's --debopt option.

--debopt "--verbose"

Skip Steps (Optional)[edit]



Source Code Changes[edit]

Only in case you made changes to the Whonix source folder! In that case click on Expand on the right.
Not required if you only added using your own build configuration in /etc/whonix_buildconfig.d folder.

Whonix 9

If you made changes to the Whonix source code, those have to be git committed before building Whonix. Otherwise you'll get an error message. (Which looks like this: [21])

To git commit changes, some basic git knowledge would be of help. To give you an idea, the workflow could look like this.

git status
git add *
git status
#git add path-to-file
## Preview.
#git diff --cached
git commit -a
git status

Whonix 10 and above

If you made changes to the Whonix source code, it is the easiest to use the following build parameter.

--allow-uncommitted true

Otherwise changes would have to be committed to git first.

Network Verification[edit]

Before running the whonix_build script make sure eth1 and eth0 refer to the correct interfaces.

## May be helpful.
dmesg | grep eth

Otherwise you have to change the variables in the configuration files. To find the affected files, the following commands may be helpful. [22]

grep -r eth0 *
grep -r eth1 *

Minor Things[edit]

Most configuration files work well inside Virtual Machines and on hardware. Only minor things such as deactivating powersaving, passwordless reboot, shutdown etc. are only recommended for Virtual Machines. You can easily comment them out by putting a hash # in front of them. They are marked, to find them, grep can be used. Skip this for now. You can change these files later after building Whonix. (Simpler.)

grep -r VMONLY* *

Run Build Script[edit]

It is recommended that you create a log of the build process by redirecting all the output to a log file. Be aware that by doing so no build progress will appear on the screen - instead a text log file will be created in your home folder.

sudo ./whonix_build --flavor whonix-gateway -- --target root --build >> ~/log-phyiso 2>&1

To optionally watch the progress, open a second virtual console and type.

tail -f ~/log-phyiso

If don't want to create a log of the build process (the build progress will then appear on screen) use the following command.

This is not recommended because if anything goes wrong during the build, it will be harder to pinpoint the exact error without the actual log file.

sudo ./whonix_build --flavor whonix-gateway -- -- target root --build

Final Steps[edit]


sudo reboot

Login as new user "user". (If you didn't install as user "user", your old user and home folder does of course still exist.)

  • Whonix 11: The build script will have replaced your /etc/network/interfaces with the respective file from whonix-gw-network-conf /etc/network/interfaces.whonix. Your original network configuration file can still be found under /etc/network/interfaces.whonix-orig. Should you require specific changes (those you might have required to add in the network configuration step above, such as eventually setting up WiFi), you need to make them again in /etc/network/interfaces. Restart your network again (sudo service networking restart) or reboot.
  • Whonix 12: This is untested since use /etc/network/interfaces.d instead of /etc/network/interfaces was implemented. Please test and leave feedback. whonix-gw-network-conf ships a file /etc/network/interfaces.d/30_non-qubes-whonix. Usually it should not conflict with your /etc/network/interfaces. If it does, consider removing source-directory /etc/network/interfaces.d from /etc/network/interfaces (if there are no other files in /etc/network/interfaces.d folder) or moving /etc/network/interfaces.d/30_non-qubes-whonix out of the way. (sudo mv /etc/network/interfaces.d/30_non-qubes-whonix ~/)




Remove temporary files.


How To Install Whonix-Gateway in a VM (UNTESTED / NOT RECOMMENDED)[edit]

It is advised to install a new OS just for hosting the Gateway VM, any OS that can run VirtualBox works but we recommend an Open Source system.

Download the Whonix-Gateway image. (Or build it from source code.)

Adapter 1 can be set up as a NAT network. Adapter 2 must either be set to NAT as well (but you will need to forward ports from the host to the guest) or much simpler: use bridged networking and set it to the second physical interface (the one that goes into the isolated network/point to point ethernet). See "NAT vs Bridging" below.

This configuration is entirely untested and not recommended unless you need to run Tor through a VPN (can't that be done without VMs?) or an unsupported 3G modem and can't afford a 3rd physical device.

When using NAT for a virtualized Gateway you need to set up port forwarding in VirtualBox. Using bridged network may be easier, but then the router may see the Whonix-Gateway MAC address which identifies as Whonix-Gateway. (Should not be of concern in home networks. Should be of concern in untrusted networks or when using a modem to connect.)

Install Whonix-Workstation in a VM (RECOMMENDED)[edit]

First Steps[edit]

Install and update a host operating system. On the host can run any OS that is capable of running VirtualBox, but be aware of Transparent Proxy Leaks. It is recommended against to use Windows or another other commercial proprietary system as host operating system.

Download the Whonix-Workstation image. (Or build it from source code.)

Note sure what we wanted to say with this sentence: If the physical network (between Whonix-Gateway and a router) uses 10.152.152.* you need to review and edit all shell scripts and switch the internal network to something else!

Host Network Adapter[edit]

The host has to be configured to use the static IP configuration.

## Whonix-Workstation
## /etc/network/interfaces for the host,
## when using Physical Isolation,
## with Whonix-Workstation in a VM.

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet static
   ## Increment last octet of address
   ## on optional additional hosts.
   #pre-up /usr/bin/whonix_firewall

   ## Out commented.
   ## For what do we require the network and broadcast
   ## instances anyway?

#auto eth0
#iface eth0 inet dhcp

## end of /etc/network/interfaces

If the physical network (between Whonix-Gateway and a router) uses 10.152.152.* you need to review and edit all /etc/network/interfaces.

NAT vs Bridging[edit]

Two Choices[edit]

In the default Whonix VirtualBox image, the network adapter setting for Adapter 1 (eth0) is set to internal network and will therefore not work out of the box. There are two choices to fix this. NAT (recommended) or bridged network.


If you use NAT you will have to edit the /etc/network/interfaces in Whonix-Workstation to use DHCP (easier, shown in the example below) or a static IP for VirtualBox NAT.

sudo nano /etc/network/interfaces

Replace it with.

## Whonix-Workstation
## /etc/network/interfaces in a VM
## when using Physical Isolation.

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

## end of /etc/network/interfaces

Bridged Network (UNTESTED / NOT RECOMMENDED)[edit]

If you use bridged networking things will (or should, we haven't tested anything yet) just work.

Since in the bridged network case, Whonix-Workstation can see the MAC address of whatever network adapter it is connected to, you should change the MAC address of the Workstation host and of the Whonix-Gateway.

See Whonix in public networks.

Install Whonix-Workstation on hardware (NOT RECOMMENDED)[edit]

Install Whonix-Workstation on hardware without using a VM is recommended against, because hardware serials would be visible to Whonix-Workstation.

The instructions are very similar, if not the very same, to those in "How To Install Whonix-Gateway on hardware" above. You have to use --tor-workstation instead of --tor-gateway.

After installing[edit]

Further required reading: Documentation. The host security chapter applies to both computers!

Read and apply the Post Installation Security Advice.

Stay tuned[edit]


Reading the latest news is important to stay on top of latest developments. Should security vulnerabilities ever be found in Whonix, any major issues (such as with the updater) happen or should an improved version be released, you should be informed.

Whonix News Blogs[edit]

For your convenience, there are multiple choices to get news. Choose at your preference.

  1. Whonix Important Blog Whonix Important Blog Rss - Most important stuff only. Security vulnerabilities and new stable versions only. For people with very limited time and interest in Whonix development and news.
  2. Whonix Feature Blog Whonix Feature Blog rss - Includes everything from Whonix Important Blog. Also testers-only and developers versions are announced. Has a relaxed posting policy. Also blog posts about updated articles, new features, future features, development, call for testing, general project thoughts and so on will be published.
  3. Other choices. [23]

It's recommended at least to read Whonix Important Blog if you are in a hurry. Have a look into Whonix Feature Blog if you are generally interested to learn about anonymity/privacy/security related things or to see what's going on with Whonix.

Operating System Updates[edit]

You should regularly check for operating system updates on your host operating system, on Whonix-Workstation and on Whonix-Gateway as highly recommended in the Security Guide.

Tor Browser[edit]

Tor Browser's built in update check mechanism also works in Whonix. Use it.

For additional information about Tor Browser updates see Tor Browser. Additionally it might also be wise to subscribe to https://blog.torproject.org for news.

Whonix Version Check and Whonix News[edit]

whonixcheck graphical user interface screnshot
Whonix Version Check (first rectangle in black) and
Whonix News
(second rectangle in green)

Furthermore you will be automatically notified about new Whonix versions and about the most important Whonix News updates [24] by Whonixcheck.

Running Whonixcheck[edit]

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

Even though Whonixcheck should run automatically from time to time (i.e. not every time the user starts a Whonix-Workstation), you may want to manually run Whonixcheck just to make sure that everything is in order. To do that, follow the directions below

How to manually run Whonixcheck[edit]

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

Qubes VM Manager -> right-click on Whonix AppVM you want to check -> select "Run command in VM"
type the following: whonixcheck

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:


Whonixcheck will take a few minutes to run. Assuming everything is good, you should get a print out where each heading "INFO" is in green (not red). See example printout below:

Example of Whonixcheck printout[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 2.5-1
√ Up to date: Whonix Build Version: 
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 https://www.whonix.org/wiki/Trust to understand the risk. If you want to change this, use: 
Start menu -> Applications -> System -> Whonix Repository 
INFO: Tor Browser Update Check Result: Up to date. 
INFO: Please consider making a small reoccurring donation. See: https://www.whonix.org/wiki/Donate

Social Media Profiles[edit]

There are some Whonix Social Media Profiles, but please don't rely on them for getting Whonix News and please don't use them to contact Whonix developers. (See Contact for contact information.)

Because some people will do so even though it is not recommended, messages from the Whonix Feature Blog will be automatically mirrored to Whonix Twitter Profile, to Whonix Facebook Profile and to Whonix Google+ Profile.

If you won't get into trouble by letting others learn about Whonix, feel free to follow or like those profiles (with your anonymous account) as a little way to Contribute. You can share this page on: Twitter | Facebook | Google+.

Source Code[edit]

In case you are interested in Whonix source code updates, subscribe to code changes.

Extra packages for better hardware support[edit]

Some packages for bare metal may or may not be missing. Here is a probably incomplete list of packages, which may or may not be useful for better hardware support. Some suggestions.







apt-cache show task-desktop
apt-cache show task-kde-desktop
apt-cache show task-laptop

If you have EFI bios.


To get a more complete list, install Debian (with KDE) on bare metal using the regular Debian installer medium.

  • diff "dpkg -l" with Whonix
  • diff "sudo lsmod" with Whonix
  • contribute your findings


  • Slow network speed? Eventually it's the fault of your wifi driver? We had such a report in the forum.
  • No connection between Whonix-Gateway and Whonix-Workstation? Could have something to do with Auto-MDIX. We had such a report in the forum.

Known bugs[edit]

Non-Qubes-Whonix means all Whonix platforms except Qubes-Whonix. That includes KVM, VirtualBox and Physical Isolation.

Mounting (CD/DVD) Devices[edit]

Device auto mounter is broken.

See if Start menu -> System Settings -> Removable Media helps.

You can use the following workaround.

sudo mkdir /mnt/cdrom
sudo mount -o ro /dev/cdrom /mnt/cdrom/

Using the ro flag will mount the CD/DVD read-only. If you are not mounting a CD/DVD, then you can drop the "-o ro" parameter.

Forum discussion:

Help fixing this bug is welcome! (ticket)

VLC / Video Player Crash[edit]

You can use this workaround.

VLC -> Tools -> Preferences -> Video -> Output -> X11 -> Save

Network Manager Systray Unmanaged Devices[edit]

Network manger question mark.png Short answer: unrelated. Forget about it.
Long answer: [25]

Proxychains Tor Browser Issue[edit]

Want to use Tor Browser in conjunction with proxychains for the connection scheme user -> Tor -> proxy -> internet?
This currently won't work. For more information, see Tunnel_Proxy_or_SSH_or_VPN_through_Tor#Tor_Browser.

"apt-get source package" will show "dpkg-source: warning: failed to verify signature"[edit]

This is not a security issue. It is only a warning. More info here (and in the following mails).

If you want, you can get rid of it with the following workaround.

1. Modify /etc/dpkg/origins/default.

sudo unlink /etc/dpkg/origins/default
sudo ln -s /etc/dpkg/origins/debian /etc/dpkg/origins/default

2. apt-get source package

3. Undo afterwards to prevent unexpected issues.

sudo unlink /etc/dpkg/origins/default
sudo ln -s /etc/dpkg/origins/whonix /etc/dpkg/origins/default

Footnotes / References[edit]

  1. https://en.wikipedia.org/wiki/Trusted_computing_base
  2. Just some hints to get started. It is difficult and beyond the scope of Whonix, because you don't have an Ethernet interface. Some (after market) firmwares support USB-host. (You can plug USB devices into your phone, such as an USB ethernet card. For example some rooted android smartphones can install Debian Linux.
  3. https://en.wikipedia.org/wiki/Ultra-mobile_PC
  4. https://en.wikipedia.org/wiki/Raspberry_Pi
  5. something like OpenWRT
  6. The other one may be either an Anonymous 3G modem; Anonymous WiFi adapter, another ethernet or wifi connected to your modem/router.
  7. Theoretically you could use any OS that supports iptables or pf. If you don't want to use Debian you will have to edit the source code. This will be easy for Debian derivatives but much more difficult for *BSD for example. In any case, the choice of OS shouldn't really matter because this system isn't used for anything but running Tor. A cheap plug computer, something like Raspberry Pi or the hardware used by Torouter would be sufficient.
  8. If you don't connect by wire, you significantly weaken isolation and security. One the Whonix-Workstation were infected, it could jump onto another network and start leaking.
  9. Any OS can be used. But this is not recommended! If you do anyway, read warning, especially for Windows: Transparent Proxy Leaks.
  10. From the Download page or build it yourself from source code.
  11. A generic VM image can neither leak identifying hardware serial numbers nor unique software fingerprints. (e.g. trough software updates).
  12. This ensures that you get the latest security features and most secure configurations. (Such as stream isolation that protects against Identity correlation through circuit sharing, XChat IRC hardening or Whonix's Protocol-Leak-Protection and Fingerprinting-Protection etc.)
  13. Debian ISO OpenPGP verification
  14. The build scripts could be adapted to run on other *NIX systems as well but currently they assume apt-get and grml-debootstrap to be available. You need about 15 GB of free space.
  15. By build-steps.d/1100_prepare-build-machine.))
  16. You need git to obtain the source code. Alternatively, you could also download a git tag as an archive using a (torified) browser: https://github.com/Whonix/Whonix/tags
  17. Get source code. Get into the source folder. Speedy parallel fetching of git submodules.
    (Credits: Thanks to Karmazzin for his answer on sourceforge.)
    git clone https://github.com/Whonix/Whonix && cd Whonix && cat .gitmodules | grep -Po '".*"' | sed 's/.\(.\+\).$/\1/' | while sleep 0.1 && read line; do git submodule update --init "$line" & done
  18. See Trust.
  19. Defined as per TUF: Attacks and Weaknesses:
  20. There currently is a small issue. (A limitation of git.)
  21. + true './build-steps.d/1200_create-debian-packages ERROR: Git reports uncommitted changes! '
    + true './build-steps.d/1200_create-debian-packages INFO: Running "git status" for your convenience. '
    + git status
    # On branch master
    # Changes not staged for commit:
    #   (use "git add <file>..." to update what will be committed)
    #   (use "git checkout -- <file>..." to discard changes in working directory)
    #       modified:   whonix_build_both
    no changes added to commit (use "git add" and/or "git commit -a")
    + true './build-steps.d/1200_create-debian-packages INFO: Running
    git "clean --dry-run -d --force --force" for your convenience. '
    + git clean --dry-run -d --force --force
    + true './build-steps.d/1200_create-debian-packages You most likely like to revert debian/control to run:
        git checkout -- debian/control
        make clean
    or if you know what you are doing:
        git clean --dry-run -d --force --force
        git reset --hard'
    + error 'Uncommitted changes! See above!'
    ./build-steps.d/1200_create-debian-packages: line 109: error: command not found
    ++ error_handler_general
    ++ local return_code=127
    ++ rm --force /etc/apt/sources.list.d/whonixtestingtemp.list
    ++ rm --force /etc/apt/apt.conf.d/90whonix-build-confold
    +++ caller
    ++ echo '
    BASH_COMMAND: error "Uncommitted changes! See above!"
    return_code: 127
    ERROR ./build-steps.d/1200_create-debian-packages: |
    caller: 109 ./build-steps.d/1200_create-debian-packages
    BASH_COMMAND: error "Uncommitted changes! See above!"
    return_code: 127
    ERROR ./build-steps.d/1200_create-debian-packages: |
    caller: 109 ./build-steps.d/1200_create-debian-packages
    ++ exit 1
  22. Should be really only a very few files. We used variables for eth0 and eth1 wherever possible.
  23. Other choices.
  24. Such as when a version becomes unsupported, if manual action is required, if major features break, or if security vulnerabilities are found. The policy is to use Whonix News as rarely as possible.
  25. Whonix doesn't use network manager to either manage eth0 or eth1. We do not want to port to network manager at this point, because there is no reason besides this issue. For one reason, because ifupdown works well with Whonix for a long time and is well tested. It is unclear if network manager, specifically cli, is ready for prime time yet. What network manager reports is that it does not manage these devices. It's not an error. Just an information. What we would like to do would be hiding that systray item by default. Or suppress that information. Or not starting that systray by default. Because that would cause less confusion. Network manager is installed to make it easier for users setting up VPNs using its graphical user interface.
    All attempts so far fixing it have failed. Help required for fixing it.
    Long standing known issue.
    Fix Unmanaged Devices Network Manager

Log in | OpenID | Contact | Impressum | Datenschutz | Haftungsausschluss | Investors | Donate

https | Mirror | Mirror | Share: Twitter | Facebook | Google+

This is a wiki. Want to improve this page? Help welcome, 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 (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.