Dev/Build Documentation/Physical Isolation

Whonix ®

Download

Windows Linux Mac VirtualBox KVM Qubes Intel / AMD64 ARM64 PPC64 USB ISO Raspberry Pi More options Source Code

About

Overview Features Whonix vs VPNs Why Open Source? Project Activities Contributors Mission & Vision

Docs

Documentation FAQ Troubleshooting

Community

Forums Forum Best Practices Contribute

Support

Self Support First Policy Search Engines, Docs and AI Support (Limited) Reporting Bugs Contact (Restricted)

Tools Upload file Special pages Recent changes Print Version Page meta What links here Related changes Page information

Page Read Edit History Move Protection Unwatch Watch Delete Purge

User Preferences Watchlist Contributions Logout Create account Login

Donate

WARNING: Please don't forget reading the #Security and Support Status, Warnings and First time user chapter.

Introduction

Basic

A supported platform that can run Whonix. There are also others.

See also Physical Isolation #Security and Support Status.

The following instructions are for Non-Qubes-Whonix. For Qubes-Whonix see:
https://forums.whonix.org/t/physical-isolation-is-back-qubes-whonix-style

Technical Introduction

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 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?

• Default username: user
• Default password: No password required. (Passwordless login.)

Warning:

• If you do not know what metadata or a man-in-the-middle attack is.
• If you think nobody can eavesdrop on your communications because you are using Tor.
• If you have no idea how Whonix works.

Then read the Design and Goals, Whonix and Tor Limitations and Tips on Remaining Anonymous pages to decide whether Whonix is the right tool for you based on its limitations.

Warnings

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:

• Protocol-Leak-Protection and Fingerprinting-Protection
• Whonix in public networks / MAC Address
  

WARNING: Joanna Rutkowska, security researcher, founder and developer emeritus of Qubes OS has completed a research paper comparing the security of software compartmentalization vs. physically separated computers (pdf). It concluded that in some cases, notably for specific, desktop-related workflows, Physical Isolation might be less secure than Qubes' compartmentalized approach. (See also: Qubes-Whonix.)

Using spare hardware + Virtual Machine

Advantages:

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

Disadvantages:

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

Using spare hardware without Virtual Machine

Advantages:

• More secure, because less code is involved.

Disadvantages:

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

Hardware

General

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

• 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

• Whonix-Gateway
  • This really does not have to be a big desktop computer or ordinary server. There are alternatives.
  • smartphone ,
  • UMPC
  • pad, tablet,
  • notebook, netbook,
  • Raspberry Pi: needs contributor, development thread
  • router ,
  • 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

Refer to the Computer Security Education chapters here and apply relevant steps.

Prerequisites

• System Requirements
• Whonix-Gateway: A device with at least two network adapters, at least one of them ethernet , capable of running Linux. It will run Debian.
• 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. This will be the torified client system or Whonix-Workstation. It must be capable of running Debian.
• We recommend to use a VM as the client, the same Whonix-Workstation, that most non Physical Isolation users use.
• 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

• You need to build on Debian Template:Stable Whonix based on Debian codename. (How to obtain Debian safely: )
• Build dependencies and configurations get automatically applied, so you don't have to worry about that.
• 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)

Get Debian

Download a Debian Template:Stable Whonix based on Debian codename 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 Template:Stable Whonix based on Debian codename network install (netinst) version is recommended (it is the most minimal).

(You could also use a Debian Template:Stable Whonix based on Debian codename 64 bit installation iso, these instructions should also work, but it is less tested.)

Install Debian

In the installer boot menu of Debian Template:Stable Whonix based on Debian codename 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 is 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

OPTIONAL.

If you are interested in seeing a visual walk-through of the minimal installation of Debian Template:Stable Whonix based on Debian codename, 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.

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

Install GRUB.

Select your disk.

Finishing the installation.

Done! The system will reboot.

OS screen.

Login screen.

OPTIONAL - CUSTOMIZING FULL DISK ENCRYPTION

If you are interested in configuring a custom encryption algorithm to enhance security during the minimal installation of Debian Template:Stable Whonix based on Debian codename, 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

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

Logon, install all security updates and reboot.

Login with "root"

Add a new repository source.

echo "deb http://ftp.us.debian.org/debian [[:Template:Stable Whonix based on Debian codename]] main" >> /etc/apt/sources.list

Add a new repository source. TODO: Is this needed?

echo "deb http://security.debian.org [[:Template:Stable Whonix based on Debian codename]]/updates main" >> /etc/apt/sources.list

Refresh package lists and upgrade.

apt-get update && apt-get dist-upgrade -y

Preparation

Install sudo and git.

## 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"
user

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

Network Verification

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

## May be helpful.
dmesg | grep eth

If you are using non-default network interface names, please click on Expand on the right.

Should be doable using non-default network interface names as well. Not as easy. Not fully documented. Untested.

One way would be to figure out how to change a network interface name such as wlan0 to eth0.

Otherwise you could consider to change the network interface names in the configuration files. To find the components that require configuration changes in the Whonix source folder, the following commands may be helpful. Should be really only a very few files. We used variables for eth0 and eth1 wherever possible.

exclude="--exclude=README.md --exclude=control --exclude=changelog.upstream --exclude-dir=.git --exclude-dir=whonix-developer-meta-files --exclude-dir=build-steps.d --exclude-dir=qubes-whonix"

grep $exclude -r eth0 ~/Whonix
grep $exclude -r eth1 ~/Whonix

grep -l $exclude -r eth0 ~/Whonix
grep -l $exclude -r eth1 ~/Whonix

Should you decide to edit these files in Whonix source folder, note to apply the build parameters from #Source Code Changes as well.

Another, perhaps better option might be to change the network interface names after Whonix build script finished.

For example /home/user/Whonix/packages/whonix-ws-network-conf/etc/network/interfaces.d/30_non-qubes-whonix becomes /etc/network/interfaces.d/30_non-qubes-whonix.

/usr/bin/whonix_firewall

Do not edit. We use a drop-in config snippet instead.

/etc/whonix_firewall.d/30_default.conf

Use a drop-in config snippet instead.

Open file /etc/whonix_firewall.d/50_user.conf in an editor with administrative ("root") rights.

1 Select your platform.

Non-Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.

3 Open the file with root rights.

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

Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.
• Template requirement: When using Qubes-Whonix, this must be done inside the Template.

3 Open the file with root rights.

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

4 Notes.

• Shut down Template: After applying this change, shut down the Template.
• Restart App Qubes: All App Qubes based on the Template need to be restarted if they were already running.
• Qubes persistence: See also Qubes Persistence
• General procedure: This is a general procedure required for Qubes and is unspecific to Qubes-Whonix.

Others and Alternatives

2 Notes.

• Example only: This is just an example. Other tools could achieve the same goal.
• Troubleshooting and alternatives: If this example does not work for you, or if you are not using Whonix, please refer to Open File with Root Rights.

3 Open the file with root rights.

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

Add. Replace eth0 with your actual external network interface name as well as eth1 with your actual internal network interface name.

EXT_IF="eth0"
INT_IF="eth1"

Save.

/etc/network/interfaces.d/30_non-qubes-whonix

Manual edit required.

Open file /etc/network/interfaces.d/30_non-qubes-whonix' in an editor with administrative ("root") rights.

1 Select your platform.

Non-Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.

3 Open the file with root rights.

sudoedit /etc/network/interfaces.d/30_non-qubes-whonix'

Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.
• Template requirement: When using Qubes-Whonix, this must be done inside the Template.

3 Open the file with root rights.

sudoedit /etc/network/interfaces.d/30_non-qubes-whonix'

4 Notes.

• Shut down Template: After applying this change, shut down the Template.
• Restart App Qubes: All App Qubes based on the Template need to be restarted if they were already running.
• Qubes persistence: See also Qubes Persistence
• General procedure: This is a general procedure required for Qubes and is unspecific to Qubes-Whonix.

Others and Alternatives

2 Notes.

• Example only: This is just an example. Other tools could achieve the same goal.
• Troubleshooting and alternatives: If this example does not work for you, or if you are not using Whonix, please refer to Open File with Root Rights.

3 Open the file with root rights.

sudoedit /etc/network/interfaces.d/30_non-qubes-whonix'

Replace interface names.

Save.

/uwt/usr/lib/uwtwrapper

Do not edit. Use a drop-in config snippet instead.

Required for Whonix-Workstation in Whonix 14 and above only.

Open file /etc/uwt.d/50_user.conf in an editor with administrative ("root") rights.

1 Select your platform.

Non-Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.

3 Open the file with root rights.

sudoedit /etc/uwt.d/50_user.conf

Qubes-Whonix

2 Notes.

• Sudoedit guidance: See Open File with Root Rights for details on why using sudoedit improves security and how to use it.
• Editor requirement: Close Featherpad (or the chosen text editor) before running the sudoedit command.
• Template requirement: When using Qubes-Whonix, this must be done inside the Template.

3 Open the file with root rights.

sudoedit /etc/uwt.d/50_user.conf

4 Notes.

• Shut down Template: After applying this change, shut down the Template.
• Restart App Qubes: All App Qubes based on the Template need to be restarted if they were already running.
• Qubes persistence: See also Qubes Persistence
• General procedure: This is a general procedure required for Qubes and is unspecific to Qubes-Whonix.

Others and Alternatives

2 Notes.

• Example only: This is just an example. Other tools could achieve the same goal.
• Troubleshooting and alternatives: If this example does not work for you, or if you are not using Whonix, please refer to Open File with Root Rights.

3 Open the file with root rights.

sudoedit /etc/uwt.d/50_user.conf

Add. Replace eth0 interface name.

bindp_interface="eth0"

/usr/bin/leaktest

Not important. Manual edit required.

/usr/lib/whonixcheck/check_network_interfaces.bsh

Manual edit required. Will break when whonixcheck gets upgraded. Then it needs to be edited again. This will be configurable in Whonix 14 so the setting survives whonixcheck upgrades.

/etc/sudoers.d/whonixcheck

Do not edit. Use a drop-in config snippet instead.

Use any editor of your choice.

sudo EDITOR=nano visudo -f /etc/sudoers.d/whonixcheck-user

Add. Replace eth0 and eth1 with your network interface names.

whonixcheck ALL=NOPASSWD: /sbin/ifconfig eth0
whonixcheck ALL=NOPASSWD: /sbin/ifconfig eth1

Save.

Minor Things

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

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

Reboot.

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

• 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 ~/)

Done.

Cleanup

This step is optional.

Remove temporary files.

Warning: This command will run git clean -d --force --force in Whonix's main source code folder (~/derivative-maker) as well as in all subfolders of the Whonix packages folder (~/derivative-maker/packages). This means if any files were purposefully added to any of these folders that have not been committed to git, these will be deleted.

./help-steps/cleanup-files

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

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 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)

First Steps

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

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.
   address 10.152.152.11 
   netmask 255.255.192.0
   gateway 10.152.152.10
   #pre-up /usr/bin/whonix_firewall

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

#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

Two Choices

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.

NAT (RECOMMENDED)

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)

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)

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 --flavor whonix-workstation instead of --flavor whonix-gateway.

After installing

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

Read and apply the Post Installation Security Advice.

Extra packages for better hardware support

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.

xorg
xserver-xorg-input-all
xserver-xorg-input-wacom
xserver-xorg-input-geode
xserver-xorg-input-vmmouse
xserver-xephyr

xserver-xorg-input-*
xserver-xorg-*

acpi-support-base
acpid
acpi

discover
discover-modprobe
discover-data

hwdata

mdetect

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

If you have EFI bios.

grub-efi-amd64

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

• See also: http://wiki.debian.org/HardwareAutodetection

Troubleshooting

• Slow network speed? Eventually it is 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.

Security and Support Status

Whonix Physical Isolation has no dedicated maintainer. It is a leftover from previous times, where no other supported platforms were supported. This setup, these instructions still work. Some users are still using them. But Patrick's focus has now moved to Qubes. Grave security issues are unlikely due to Whonix's design. There is no Whonix team member testing Whonix physical isolation. No progress on the Whonix Physical Isolation development task list should be expected. That's why the supported platforms table lists Physical Isolation in the column 'security' with 'experimental'.

Help Wanted

• work on the Whonix Physical Isolation development task list (not even filled up)
• Become Whonix Physical Isolation maintainer so the #Security and Support Status can be improved.

Footnotes / References

Tunnels/Connecting to a VPN before Tor Documentation Signing Key Previous page: Tunnels/Connecting to a VPN before Tor Index page: Documentation Next page: Signing Key

Whonix The most watertight privacy operating system in the world.

Dark mode

Follow us on social media

Supported by Power Up Privacy

Whonix is proudly supported until 2026 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint 2012- 2026 ENCRYPTED SUPPORT LLC

Your support makes
all the difference!

We believe security software like Whonix needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 14 year success story and maybe DONATE!