Actions

Build Documentation: Physical Isolation

From Whonix

< Dev‎ | Build Documentation



Digital-art-191226640.jpg


Introduction[edit]

FREE

Ambox warning pn.svg.png Warning: It is essential to read the Security and Support Status, Warnings and First Time Users entries in this chapter.

Overview[edit]

Physical isolation requires:

First Time Users[edit]

Whonix / Kicksecure ™ default admin password is: changeme default username: user
default password: changeme

Whonix first time users warning 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.

Technical Introduction[edit]

The default Whonix ™ configuration consists of two virtual machines (VMs) running on the same physical host. This means any exploits targeting the VM implementation or the host can still break out of the torified client VM and expose the IP address of a user. Further, any malware running on the host has full control over all VMs. To protect against these attacks a different approach is required -- physical isolation. In this configuration the gateway system is installed on separate hardware, which drastically reduces the trusted computing base (TCB) [archive] by more than half.

The following instructions describe how to install and configure two computers and set up an isolated point to point network between them. [1] This way one computer acts as the client (Whonix-Workstation ™), while the other is the proxy (Whonix-Gateway ™) which transparently routes all the Whonix-Workstation ™ traffic via Tor.

The Whonix-Gateway ™ on its own physical device can be run either directly on hardware or inside a VM. Both options have distinct advantages and disadvantages, but using an additional VM for the Whonix-Gateway ™ is unrecommended. In contrast, the Whonix-Workstation ™ should always be installed in a VM because this will hide hardware serial numbers. Also read the wiki entry recommending use of multiple VM Snapshots for better security.

In this configuration the host operating system(s) should only be used for downloading operating system updates, hosting Whonix-Gateway ™ or Whonix-Workstation ™ and nothing else. The configuration is also more secure if the physical systems are exclusively used for hosting Whonix ™, or if storage devices are separated for Whonix ™ and non-Whonix ™ use cases. The reason is this avoids any potential infection of the Whonix ™ hard drive by another operating system.

Warnings[edit]

Please note the following warnings about physical isolation:

Configuration[edit]

Physical Isolation Configuration[edit]

Table: Physical Isolation Configuration Comparison

Configuration Advantages Disadvantages
Spare Hardware and VM
  • A graphical host can be installed.
  • The Whonix ™ download version is used.
  • The graphical network manager on the host can be used, for example to connect to WiFi.
  • A VPN can be easily set up on the host. Tor will then be tunneled through the VPN.
  • This has a higher attack surface because VM code is involved.
Spare Hardware without VM
  • This is more secure because less code is involved.
  • The setup is slightly more complicated.
  • It is more difficult to set up a VPN.
  • It is more difficult to set up 3G/4G/5G networking compared to using a Windows host.

Hardware Configuration[edit]

It is recommended that two dedicated computers are utilized for Whonix ™ that are never used for activities that could reveal your identity. Alternatively, an existing computer that is already in use can be utilized for Whonix-Gateway ™. To offer some isolation, all internal and external drives should be disconnected, with boots occuring from an eSATA, USB or another internal drive into a clean environment.

For non-anonymous use, the physical arrangement can be used as is without any modification. This includes the use of a non-anonymous home (dial-up) Internet router, without any changes. In contrast anonymous use requires:

  1. Whonix-Gateway ™
  2. an anonymous 3G/4G/5G modem or an anonymous WiFi adapter (see below)
  3. Whonix-Workstation ™

In terms of the specific hardware used for Whonix-Gateway ™, various devices are feasible and it does not have to be a big desktop computer or ordinary server. Alternatives include:

How to utilize devices like a Linux server is beyond the scope of this chapter and better resources already exist on the Internet. Similarly for Whonix-Workstation ™, a device that is suitable should be chosen.

Pre-installation Prerequisites[edit]

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

Prerequisites[edit]

Physical isolation has several prerequisites:

  1. System requirements: Available hardware must meet the minimum specifications.
  2. Whonix-Gateway ™: A device with at least two network adapters -- at least one of them ethernet [6] -- capable of running Linux. The Whonix-Gateway ™ will run Debian. [7]
  3. Whonix-Workstation ™: A device connected via ethernet to the Whonix-Gateway ™. It must only have this one NIC and no other network connectivity! It must also be connected by wire. [8] This will be the torified client system or Whonix-Workstation ™ and it must be capable of running Debian. [9]
  4. VM client: It is recommended to use a VM as the client, namely the same Whonix-Workstation ™ that most "normal" (non-physical isolation) Whonix ™ users rely upon. [10] [11] [12]
  5. Host build environment: The build environment must have a working Internet connection to Debian mirrors.
  6. Virtual console: Although optional, it is also useful to know how to open a second virtual console.

Host Preparation[edit]

1. Prepare to build on Debian bullseye.

To obtain Debian safely, see: Debian ISO OpenPGP verification. Around 15 GB of free space is required. [13]

2. Adjust terminal settings.

It is recommended to set the terminal (such as Konsole) to unlimited scrollback, so it is possible to watch the full build log.

3. Install build dependencies.

Install build dependencies and get the source code.

Update the package lists. 

sudo apt update

Install build dependencies. 

sudo apt install git time curl apt-cacher-ng lsb-release fakeroot dpkg-dev fasttrack-archive-keyring

System Preparation[edit]

1. Confirm prerequisites are met.

  • Debian bullseye is installed.
  • User account user exists.

2. Become root. [14] [15] 

su -

3. Install sudo and adduser packages.

1. Update the package lists. 

apt update

2. Upgrade the system. 

apt full-upgrade

3. Install sudo and adduser packages. 

apt install --no-install-recommends sudo adduser

4. Set user rights.

The following commands must be run either by root or using sudo.

Create group console. 

addgroup --system console

Add user user to group console. 

adduser user console

Add user user to group sudo. 

adduser user sudo

5. Reboot. [16] 

reboot

How-to: Install Whonix-Gateway ™[edit]

Recommended: On Hardware[edit]

Get Debian[edit]

Download a Debian bullseye 64-bit installation ISO [archive]. Detailed instructions for this procedure are not part of this chapter, but the Debian Host Operating System Tips chapter provides some steps.

It is possible to choose an ISO for any desktop environment (KDE, LXDE, Xfce, ...). However, because the command line is extensively used the Debian bullseye network install (netinst) version is recommended (it is the most minimal).

Install Debian[edit]

In the installer boot menu of Debian bullseye, press "Install" and choose the 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

Installation Screenshots[edit]

For a visual walk-through of the minimal Debian bullseye installation, click on Expand on the right. For up-to-date screenshots of this process, refer to the The Debian Administrator's Handbook: 4.2. Installing, Step by Step [archive]. If utilizing this guide, remember to set:

  • the English language
  • the United States location
  • hostname to "host"
  • an empty domain name
  • a strong root password
  • full name to "user"
  • username to "user"
  • a strong user password
  • full disk encryption (recommended)
  • installation without a mirror
  • refuse survey participation

Figure: Select "Install"

20.png


Figure: Set English Language

21.png


Figure: Set United States Location

22a.png


Figure: Keyboard Selection

23.png


Figure: Additional Content Installation

53.png


Figure: Network Auto-configuration [17]

24.png


Figure: Set Hostname to "host"

25.png


Figure: Set Empty Domain Name

26.png


Figure: Enter a Strong Root Password

27.png


Figure: Re-enter the Password

28.png


Figure: Set Full Name to "user"

29.png


Figure: Set Username to "user"

30.png


Figure: Enter a Strong user Password

31.png


Figure: Re-enter the Password

32.png


Figure: Network Time Procedure

33.png


Figure: Use a Guided Partitioning Method with the Whole Disk [18]

34.png


Figure: Select the Suggested Disk

35.png


Figure: Partition all Files in One Partition

36.png


Figure: Finish Partitioning

37.png


Figure: Confirm Changes

38.png


Figure: Wait for Base System Installation [19]

39.png 40.png


Figure: Do not Select a Mirror [20]

41.png


Figure: Confirm Continuation without a Mirror

42.png


Figure: APT Configuration

43.png


Figure: Refuse Survey Participation [21]

44.png


Figure: Deselect (no star) the Given Option [22]

45.png 46.png


Figure: Install GRUB

47.png


Figure: Select the Disk

48.png


Figure: Finish Installation

49.png


Figure: Automatic System Reboot

50.png


Figure: Operating System Screen

51.png


Figure: Login Screen

52a.png

Optional: Customizing Full Disk Encryption[edit]

If you wish to configure a custom encryption algorithm to enhance security during the minimal Debian bullseye installation, click on Expand on the right.

1. Under "Partitioning method", select Manual.

2. Select the installation disk.

  • Highlight the installation disk and press "Enter" → Select <Yes> to create a new empty partition table

3. Create a new partition.

  • Select the "FREE SPACE" of the destination drive you are installing to → Press "Enter" → "Create a new partition" should already be selected → Press "Enter" again

4. Create a boot partition.

This is the unencrypted partition the system boots from; the standard size is 254.8 MB.

  • Type "254.8 MB" (without the quotes) → Press "Enter"

5. Select partition type and location.

  • Check "Type for the new partition:" -- "Primary" should already be selected → Press "Enter" → Under "Location for the new partition:" -- "Beginning" should already be selected → Press "Enter" → Navigate to the Partition settings screen

Use the following settings for the boot partition: 

Use as:         Ext4 file system

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

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

6. Select encrypted volumes option.

  • Choose "Configure encrypted volumes" → Press "Enter" → Select <Yes> when asked to write the changes to disk and configure encrypted volumes

7. Configure the encrypted partition.

  • Ensure "Create encrypted volumes" is already selected → Press "Enter" → Select the free space of the installation drive by pressing the spacebar → Select <Continue> and press "Enter" again

After additional components load, a configuration page for the encrypted partition will appear. At this stage it is possible to customize the 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. Write the changes to disk.

After completing the configuration step:

  • Select "Done setting up this partition" → Press "Enter" → Select <Yes> and press Enter to write the changes to disk → On the next screen select "Finish" and press "Enter"

9. Optional: Erase the partition.

It is strongly recommended to erase the partition before continuing. Please note this may take a while for large drives. If the device was securely wiped before starting this installation, this step can be skipped. To erase the partition, select <Yes> and press Enter.

10. Choose a strong password.

Refer to this entry for advice on generating strong passwords with sufficient entropy; at least a 7-word diceware passphrase is recommended. [23] [24] Remember: the stronger the passphrase, the stronger your encryption (and vice-versa). After entering the passphrase and confirming it, you will be brought back to the main partitioning menu.

11. Configure the physical volume.

  • Inspect the 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) → Press "Enter" → Under "Use as:" -- change this to "physical volume for LVM" → Press "Enter" → Select "Done setting up the partition" → Press "Enter" again to be brought back to the main partitioning menu

12. Select "Configure the Logical Volume Manager" and press Enter.

13. Configure the volume group.

  • Highlight "Create volume group" and press "Enter" → Under "Volume group name:" -- enter HOST_VG and press "Enter

14. Use the spacebar to select the 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. Create the logical volume.

Highlight "Create logical volume" → Press "Enter" → Select HOST_VG → Press "Enter" → Type ROOT → Press "Enter"

16. Under the "Logical volume size:", the 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. The new partition for ROOT should be 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. Select the preferred filing system.

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

Use as:             XFS journaling file system

Mount point:     / 
Mount options: defaults
Label:               none

20. When the preceding configuration is finished, 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. Finalize the partitioning.

  • Highlight "Finish partitioning and write changes to disk" → Press "Enter" → Select <Yes> when asked to confirm the changes

The 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, for example static or simply left to use DHCP if the gateway is connected to a DHCP-capable router. For wlan, refer to upstream wiki documentation:

Check that the Internet is working.

Log On and Upgrade Debian[edit]

1. Install security updates.

Log on, install all security updates and reboot.

2. Log in with "root".

3. Add the bullseye main repository source. 

echo "deb http://deb.debian.org/debian bullseye main" >> /etc/apt/sources.list

4. Add the bullseye updates repository source. [25] 

echo "deb http://security.debian.org bullseye/updates main" >> /etc/apt/sources.list

5. Refresh package lists and upgrade. 

apt update && apt full-upgrade -y

Firmware Updating and Security Problems[edit]

Processor microcode updates are recommended to address speculative execution flaws; see Firmware Updating and Security Problems for further information.

Update the package lists. 

sudo apt update

For Intel. 

sudo apt install --no-install-recommends intel-microcode

For AMD. 

sudo apt install --no-install-recommends amd64-microcode

Preparation[edit]

1. Install sudo and git. [26] 

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

2. Prepare the system for the Whonix ™ build.

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

3. Optional: Consider taking an image of the installation in case the build script fails partway through.

Get the Source Code[edit]

Get the Signing Key[edit]

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

Get the Whonix ™ Signing Key.

Get the Source Code[edit]

FREE

Ambox warning pn.svg.png Note: By proceeding, you acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement. Ambox warning pn.svg.png

Install git. 

sudo apt update && sudo apt install git

Get the source code including git submodules. [27] [28]

Note: Replace 16.0.3.7-stable with the actual tag you want to build. 

git clone --depth=1 --branch 16.0.3.7-stable --jobs=4 --recurse-submodules --shallow-submodules https://gitlab.com/whonix/Whonix.git

OpenPGP Verify the Source Code[edit]

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

Git fetch. [30] 

git fetch

Verify the chosen tag to build. Replace with tag you want to build.

Note: Replace 16.0.3.7-stable with the actual tag you want to build. 

git verify-tag 16.0.3.7-stable

The output should look similar to this.

object 1844108109a5f2f8bddcf2257b9f3675be5cfb22

type commit tag 16.0.3.7 tagger Patrick Schleizer <adrelanos@whonix.org> 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@whonix.org>" [ultimate]

warning Check the GPG signature timestamp makes sense. For example, if you previously saw a signature from 2021 and now see a signature from 2020, then this might be a targeted rollback (downgrade) or indefinite freeze attack. [31]

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 safely ignored.

By convention, git tags should point to signed git commits. [32] (forum discussion [archive]) It is advisable to verify the signature of the git commit as well (replace 16.0.3.7 with the actual git tag being verified). 

git verify-commit 16.0.3.7-stable^{commit}

The 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@whonix.org>" [ultimate] Author: Patrick Schleizer <adrelanos@whonix.org> Date: Sun Dec 7 01:22:22 2014 +0000

.

Choose Version[edit]

Retrieve a list of available git tags. 

git --no-pager tag

Use git checkout to select the preferred version to build.

Note: Replace 16.0.3.7-stable with the actual tag you want to build. 

git checkout --recurse-submodules 16.0.3.7-stable

Check Git[edit]

Check if you really got the version you want. 

git describe

The output should show.

16.0.3.7-stable

Check if the source folder is pristine. 

git status

The output should show nothing.

HEAD detached at 16.0.3.7-stable
nothing to commit, working tree clean

If it shows something else, do not continue.

Optional Build Configuration[edit]

Refer to Optional Build Configuration for additional configuration options like:

  • 32-bit vs 64-bit builds
  • Whonix ™ APT repository
  • APT onion build sources
  • torified or host APT cache
  • build variables changes
  • skipping steps
  • source code changes

Network Verification[edit]

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

## May be helpful.
dmesg | grep eth

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

Info The following procedure should also be possible with non-default network interface names, but that is more difficult. Note this procedure is untested and not fully documented.

One method is figuring out how to change a network interface name such as wlan0 to eth0.

Another method is to consider changing the network interface names in the configuration files. To discover components that require configuration changes in the Whonix ™ source folder, the following commands may be helpful. Note that only a few files should require modification and the variables eth0 and eth1 have been used 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 ~/{{project_name_short}}
grep $exclude -r eth1 ~/{{project_name_short}}

grep -l $exclude -r eth0 ~/{{project_name_short}}
grep -l $exclude -r eth1 ~/{{project_name_short}}

If you decide to edit these files in Whonix ™ source folder, remember to apply the build parameters from the Source Code Changes section here.

The final and perhaps best method is changing the network interface names after the Whonix ™ build script has finished; see below.

1. Note the location for network interfaces.

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.

2. Create a firewall drop-in configuration snippet.

  • Do not edit /usr/bin/whonix_firewall.
  • Instead, create a drop-in config snippet here: /etc/whonix_firewall.d/30_default.conf.

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

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

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

3. Add the external and internal network interface names.

In the example below, replace eth0 and eth1 with the respective (actual) external and internal network interface names. 

EXT_IF="eth0"
INT_IF="eth1"

Save the file.

4. Edit the network interfaces file.

  • Manually edit /etc/network/interfaces.d/30_non-qubes-whonix.

Open file /etc/network/interfaces.d/30_non-qubes-whonix in an editor with root rights.

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

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

Replace the interface names and save the file.

5. Create a uwtwrapper drop-in configuration snippet. [33]

  • Do not edit /uwt/usr/lib/uwtwrapper.
  • Instead, create a drop-in config snippet here: /etc/uwt.d/50_user.conf.

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

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

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

6. Add the external and internal network interface names.

In the example below, replace the eth0 interface name. 

bindp_interface="eth0"

Save the file.

7. Optional: Edit the leaktest file.

This step is not important, but /usr/bin/leaktest can be manually edited as per previous steps.

Open file /usr/bin/leaktest in an editor with root rights.

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

sudoedit /usr/bin/leaktest

Make necessary changes and save the file.

8. Edit the systemcheck network interfaces file.

  • Manually edit /usr/lib/systemcheck/check_network_interfaces.bsh.
  • This will break when systemcheck is upgraded, meaning it needs to be edited again. This is configurable in Whonix ™ 14 and above so the setting survives systemcheck upgrades.

Open file /usr/lib/systemcheck/check_network_interfaces.bsh in an editor with root rights.

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

sudoedit /usr/lib/systemcheck/check_network_interfaces.bsh

Make necessary changes and save the file.

9. Create a sudoers drop-in configuration snippet.

  • Do not edit /etc/sudoers.d/systemcheck.
  • Instead, create a drop-in config snippet here: /etc/sudoers.d/systemcheck-user.

Use any preferred editor. 

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

10. Add the external and internal network interface names.

In the example below, replace the eth0 and eth1 interface names. 

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

Save the file.

11. Edit the onion-grater configuration file.

  • Manually edit /usr/lib/systemd/system/onion-grater.service.d/30_cpfpy.conf.
  • Systemd may fail to start onion-grater if this file is not configured properly.
  • As per previous steps, replace any interface names with your corresponding interface names and save the file.

TODO: it is better to use a drop-in /usr/lib/systemd/system/onion-grater.service.d/50_user.conf file; see Configuration Files.

12. Restart onion-grater.service and confirm active status. 

systemctl restart onion-grater.service
systemctl status onion-grater.service

Minor Issues[edit]

Info It is currently recommended to skip this step. It is simpler to change these files later on after building Whonix ™.

Most configuration files work well inside VMs and on hardware. Minor issues such as deactivating powersaving, passwordless reboot, shutdown and so on are only recommended for VMs. They can be easily commented out by putting a hash # in front of them. Since they are marked, use grep to locate them. 

grep -r VMONLY* *

Run Build Script[edit]

It is recommended to 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 the home folder. 

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

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

tail -f ~/log-phyiso

Use the following command to avoid creating a log of the build process; the build progress will then appear on screen. Note this is unrecommended because if anything goes wrong during the build, it is harder to pinpoint the exact error without a log file. 

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

Final Steps[edit]

Info This is untested since use /etc/network/interfaces.d instead of /etc/network/interfaces [archive] was implemented; see footnote. [34] Please test and leave feedback.

Reboot. 

sudo reboot

Login as new user user. (If you didn't install as user user, the old user and home folder will still exist.)

Done.

Cleanup[edit]

Info This step is optional.

Remove temporary files.

Warning: This command will run git clean -d --force --force in Whonix's main source code folder [archive] (~/Whonix) as well as in all subfolders of the Whonix packages folder [archive] (~/Whonix/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. [35] 

./help-steps/cleanup-files


Experimental: On the Raspberry Pi 3 B (RPI3)[edit]

Raspberry Pi Logo

Introduction[edit]

Procedure[edit]

1. Get the source code.

2. Build Whonix-Gateway ™.

Run this command inside the Whonix ™ source folder. 

sudo ./whonix_build --target raw --flavor whonix-gateway-rpi --build --arch arm64 --kernel linux-image-arm64 --headers linux-headers-arm64

3. Burn the image to a micro SD card.

After a successful build, burn the whonix_gw_rpi.img image to a micro SD card using gnome-disk-utility.

  1. Within gnome-disk-utility select the SD card.
  2. At the top panel select "options" (next to the poweroff button).
  3. Click "restore disk image" and choose the respective file.
  4. Click "start restoring" and wait until it is finished.
  5. Put the SD card into the RPI3, attach an HDMI monitor, an USB-ethernet adapter as well as a keyboard and boot it.

4. Configure interfaces.

After login, run. 

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

Change the address and the gateway of eth0 corresponding to the local network / upstream router. As an example, our ISP router uses 192.168.0.1/24 for the internal network. In this case the eth0 settings would look like the following: 

auto eth0
iface eth0 inet static
    address 192.168.0.11
    netmask 255.255.255.0
    gateway 192.168.0.1

5. Set up network cables.

By default eth0 is the native ethernet connection of the RPI3. Hence, connect a network cable from there to the router. eth1 is the USB-ethernet adapter which should also be connected via cable to the computer running Whonix-Workstation ™.

6. Manually set the time.

The RPI3 lacks a real time clock, so it is necessary to manually set the current UTC date and time. Example: 

sudo date -s "10 JUL 2021 17:00:00"

7. Connect to the Tor network.

Restart the networking service. 

sudo service networking restart

Restart the Tor service. 

sudo service tor restart

Note: Depending on the hypervisor it is necessary to change network settings on Whonix-Workstation ™ in order to connect it to Whonix-Gateway ™ (see next section).

Unrecommended: In a VM[edit]

Ambox warning pn.svg.png This configuration is entirely untested.

1. Install a new operating system.

  • It is advisable to install a new operating system just for hosting the Whonix-Gateway ™ VM.
  • Any operating system that can run VirtualBox works, but an open source system is preferable.

2. Download the Whonix-Gateway ™ image. [36]

3. Configure networking.

  • Adapter 1 can be set up as a NAT network.
  • Adapter 2 must either:
    • Be set to NAT as well -- but ports must be forwarded from the host to the guest; or
    • It is much simpler to 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.

4. Note the following warnings.

  • This configuration is not recommended unless Tor must be run through an unsupported 3G/4G/5G modem and a third physical device is unaffordable.
  • Using NAT for a virtualized Whonix-Gateway ™ requires setting up port forwarding in VirtualBox. Using a bridged network may be easier, but then the router may see the gateway MAC address which identifies as Whonix-Gateway ™. [37]

How-to: Install Whonix-Workstation ™[edit]

Recommended: In a VM[edit]

First Steps[edit]

  1. Install and update the host operating system. It can be any operating system that is capable of running VirtualBox, but be aware of Transparent Proxy Leaks [archive]. Windows or other commercial proprietary systems are not recommended.
  2. Download the Whonix-Workstation ™ image. [38]
  3. If the physical network between Whonix-Gateway ™ and a router uses 10.152.152.* then review and edit all shell scripts and switch the internal network to something else! [39]

Host Network Adapter[edit]

Configure the host to use a static IP configuration. 

## {{workstation_product_name}}
## /etc/network/interfaces for the host,
## when using Physical Isolation,
## with {{workstation_product_name}} 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.*, then review and edit all /etc/network/interfaces.

NAT vs Bridging[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 ways to fix this: NAT (recommended) or using a bridged network (unrecommended).

Recommended: NAT[edit]

To use NAT, edit /etc/network/interfaces in Whonix-Workstation ™ to utilize either DHCP (easier, shown in the example below) or a static IP for VirtualBox NAT. 

sudoedit /etc/network/interfaces

Replace it with. 

## {{workstation_product_name}}
## /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

Unrecommended: Bridged Network[edit]

Ambox warning pn.svg.png This is untested.

If bridged networking is configured, then everything should work by default. [40] The reason is Whonix-Workstation ™ can see the MAC address of whatever network adapter it is connected to.

For this reason it is recommended to change the MAC address for both the Workstation host and the Whonix-Gateway ™; see Changing MAC Addresses.

Macvtap on KVM[edit]

Change the network source of the ethernet nic to "macvtap" and the source mode to "passthrough". Be aware that you cannot use networking on the host anymore.

Attach a USB-ethernet Adapter to the VM[edit]

Remove the network adapter from the VM and instead attach a USB-ethernet adapter to the host and redirect it to the VM.

Unrecommended: On Hardware[edit]

Installing Whonix-Workstation ™ on hardware without using a VM is recommended against, because hardware serials are visible to Whonix-Workstation ™.

The instructions are very similar, if not identical, to those in the How-to: Install Whonix-Gateway ™ - Recommended: On Hardware section. The only difference is replacing --flavor whonix-gateway with --flavor whonix-workstation in relevant steps.

Expected Build Warnings[edit]

None of the following warnings affect the build. Refer to relevant footnotes for further information. 

dpkg-source: warning: extracting unsigned source package

dpkg-source: warning: extracting unsigned source package (anon-gw-anonymizer-config_5.0-1.dsc)

[41] 

Can not write log, openpty() failed (/dev/pts not mounted?)

[42] 

[....] Your system does not have the CPU extensions required to use KVM. Not doing anything. ...[ FAIL ]

[43] 

[....] Stopping VirtualBox kernel modules [ ok ].
[....] Starting VirtualBox kernel modules[....] No suitable module for running kernel found ...[ FAIL ]
invoke-rc.d: initscript virtualbox, action "restart" failed.

[44] 

WARNING: The character device /dev/vboxdrv does not exist.
	 Please install the virtualbox-ose-dkms package and the appropriate
	 headers, most likely linux-headers-486.

	 You will not be able to start VMs until this problem is fixed.

[45] 

dpkg: warning: failed to open configuration file '/root/.dpkg.cfg' for reading: Permission denied

[46] 

sudo: unable to resolve host host

[47]

Related forum topic: Expected Build Warnings [archive]

Post-installation Advice[edit]

Info It is recommended to consult the Whonix ™ Documentation in further depth. The Essential Host Security and Post-installation Security Advice chapters apply to both computers!

Stay Tuned[edit]

It is absolutely crucial to subscribe to and read the latest Whonix ™ news category 'important-news' to stay in touch with ongoing developments. This way users benefit from notifications concerning important security advisories, potential upgrade issues and improved releases which address identified issues, like those affecting the updater or other core elements.

See Stay Tuned for further information.

Extra Packages for Better Hardware Support[edit]

Some packages for bare metal could be missing. Below is an incomplete list of packages, which may or may not be useful for better hardware support. [48] 

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 compile a more complete list, install Debian (with Xfce) on bare metal using the regular Debian installer medium. Then compare the package list against those installed in Whonix ™.

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

Troubleshooting[edit]

Known Bugs[edit]

To learn about known bugs affecting all platforms, see here. Refer to the issue tracker for a list of all all open issues affecting Whonix ™.

Security and Support Status[edit]

Currently there is no dedicated contributor for Whonix ™ physical isolation. This configuration is a remnant from earlier times when no other supported platforms were available. Despite this reality, the setup and instructions are still functional and a small percentage of the Whonix ™ user population relies upon it.

Lead Whonix ™ developer, Patrick Schleizer, has shifted his focus to Qubes-Whonix ™, but grave security issues are unlikely due to the Whonix ™ design. Unfortunately there are no Whonix ™ contributors testing Whonix ™ physical isolation. As a consequence, no progress on the Whonix ™ Physical Isolation development task list [archive] should be expected. Until this situation changes the supported platforms table will continue to list physical isolation's security status as "experimental".

Help Wanted[edit]

Footnotes / References[edit]

  1. ↑ Alternatively an ordinary, completely isolated, LAN behind the Whonix-Gateway ™ can be set up.
  2. ↑ This refers to staying anonymous while building Whonix ™ from source code. Since building Whonix ™ requires a unique selection of software to be downloaded, the ISP can likely guess that a user is building Whonix ™.
  3. ↑ Due to the lack of an ethernet interface this is a difficult configuration and beyond the scope of the Whonix ™ documentation. However, as a tip some (after market) firmwares support USB-host. This makes it possible to plug USB devices into your phone, such as an USB ethernet card. For example, some rooted Android smartphones can install [archive] Debian Linux.
  4. ↑ A contributor or maintainer is required, see: Whonix - Raspberry Pi [archive] development thread.
  5. ↑ For example, something like OpenWRT [archive].
  6. ↑ The other one may be either an Anonymous Mobile Modem, an Anonymous WiFi Adapter, or another ethernet or WiFi device connected to the modem/router.
  7. ↑ Theoretically any operating system that supports iptables or pf (packet filter) could be used. Advanced users who do not want to utilize Debian need to edit the source code. This is easy for Debian derivatives, but much more difficult for other distributions such as *BSD. In any case, the operating system choice does not really matter because this system is only used for running Tor. A cheap plug computer like the Raspberry Pi, or the hardware used by Torouter would be sufficient.
  8. ↑ If wire connections are not configured, isolation and security is significantly weakened. If the Whonix-Workstation ™ were infected, it could jump onto another network and start leaking information.
  9. ↑ Any operating system can be used, but this is not recommended! If this advice is ignored, read the following Transparent Proxy Leaks [archive] warning, especially for Windows.
  10. ↑ Either Download the image or build it from source code.
  11. ↑ A generic VM image cannot leak identifying hardware serial numbers or unique software fingerprints via software updates [archive].
  12. ↑ This ensures the VM client has the latest security features and most secure configurations, for example stream isolation to protect against identity correlation through circuit sharing, HexChat IRC hardening, Whonix ™ protocol leak protection and fingerprinting protection, and so on.
  13. ↑ The build scripts can be adapted to run on other *NIX systems, but they currently assume apt and grml-debootstrap are available.
  14. ↑ Parameter - is required to set the correct paths to /usr/sbin. https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=833256 [archive]
  15. ↑ Other methods are possible.
  16. ↑ Usability. Otherwise after installation is complete, user might not be able to login. Needs further testing if still required. Can be avoided for remote servers.
  17. ↑ This should occur by default.
  18. ↑ Full disk encryption (FDE) is recommended if planning to use physical isolation or the installation as the main system.
  19. ↑ It takes a few minutes for the base system installation to finish.
  20. ↑ Extra packages are not required, so do not select a mirror; "Go back".
  21. ↑ Select "No thanks".
  22. ↑ Using the space bar.
  23. ↑ This yields ~90 bits of entropy against classical computing attacks. To protect against hypothetical quantum computer attacks that halve the key search space, utilize a 14-word diceware passphrase.
  24. ↑ This section previously recommended a passphrase of at least 26 characters, including symbols.
  25. ↑ TODO: check whether this step is still required.
  26. ↑ git is needed to obtain the source code. Alternatively, a git tag can be downloaded as an archive using a (torified) browser: https://github.com/Whonix/Whonix/tags [archive]
  27. ↑ Optional git parameters:
    • --depth=1: Used to speed up download.
    • --branch 16.0.3.7-stable Usability. Used to speed up download.
    • --jobs=4: Used to speed up download.
    • --recurse-submodules --shallow-submodules: Usability.
    Knowledgeable git users are free to drop any of these optional parameters.
  28. ↑ Alternatively, this can be achieved with the following commands in several steps. This is useful if network issues arise. 
    git clone --depth=1 --branch 16.0.3.7-stable https://gitlab.com/whonix/Whonix.git

    cd Whonix

    git submodule update --init --recursive --progress --jobs=4
  29. ↑ See Trust.
  30. ↑ Optional. [...]
  31. ↑ As defined by TUF: Attacks and Weaknesses:
  32. ↑ Beginning from git tag 9.6 and above.
  33. ↑ This is required for Whonix-Workstation ™ in Whonix ™ 14 and above.
  34. ↑ whonix-gw-network-conf [archive] ships a file /etc/network/interfaces.d/30_non-qubes-whonix [archive]. Normally it should not conflict with /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 the /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 ~/)
  35. ↑ https://github.com/Whonix/Whonix/blob/master/help-steps/cleanup-files [archive]
  36. ↑ Or build it from source code.
  37. ↑ This is not a concern in home networks, but is a risk in untrusted networks or when using a modem to connect.
  38. ↑ Or build it from source code.
  39. ↑ TODO: check whether this step is still required.
  40. ↑ At least it should work, although it is untested by developers.
  41. ↑ end-to-end signed debs. debsign, debsig and dpkg-sig [archive]
  42. ↑ This is nothing to be concerned about; it only happens because commands are run inside chroot. Research of this "issue" indicates it is purely cosmetic.
  43. ↑ KVM is installed as a dependency of the build dependency libguestfs-tools. KVM is not needed to build the actual images.
  44. ↑ This only means that VirtualBox cannot be started. VirtualBox kernel modules could not be compiled because the linux-headers-$(uname -r) package was not installed prior to installing VirtualBox (before starting Whonix's build script). The build script does not start VirtualBox, hence does not affect the build. The build script only uses VBoxManage for creation of virtual machine description files and that tool does not need VirtualBox kernel modules.
  45. ↑ This is caused by the same issue referenced above.
  46. ↑ This happens because debuild is run as user, not root. It is probably a bug in dpkg. Research of this issue reveals there are many similar bugs in dpkg.
  47. ↑ The hostname is changed intentionally to host inside the VM image. The cause is probably package anon-base-files postinst running hostname "$my_host_name" / hostname host. This change should only happen inside the change root chroot. This issue might be resolved by porting from chroot to systemd-nspawn, but it is not very important.
  48. ↑ These are suggestions only and individual users may need to undertake further research in their personal circumstances.
Fosshost is sponsors Kicksecure ™ stage server 100px
Fosshost About Advertisements

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

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

Support: Discourse logo.png

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

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

Twitter-share-button.png Facebook-share-button.png Telegram-share.png link=mailto:?subject=Dev/Build Documentation/Physical Isolation&body=../../Dev/Build_Documentation/Physical_Isolation link=https://reddit.com/submit?url=../../Dev/Build_Documentation/Physical_Isolation&title=Dev/Build Documentation/Physical Isolation link=https://news.ycombinator.com/submitlink?u=../../Dev/Build_Documentation/Physical_Isolation&t=Dev/Build Documentation/Physical Isolation link=https://mastodon.technology/share?message=Dev/Build Documentation/Physical Isolation%20../../Dev/Build_Documentation/Physical_Isolation&t=Dev/Build Documentation/Physical Isolation

Follow us on Twitter.png Twitter / Facebook.png Facebook.

https link onion link Priority Support | Investors | Professional Support

Whonix ™ | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

Retrieved from "https://www.whonix.org/w/index.php?title=Dev/Build_Documentation/Physical_Isolation&oldid=71041"
By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent.
More information