Dev/Build Documentation/8 in VM

Documentation

This is a short set of instructions for building the stable version of Whonix 8 inside VirtualBox (as opposed to the traditional process of running these commands on a system that is installed directly on the hardware).

Advantages of this approach are that you can build Whonix on any OS that can run VirtualBox (you need Debian Stable for hardware type build) and that any potential system damage is limited to the VM. Using snapshots you can quickly revert a faulty state or a failed build and start again.

The focus here is to show the simplest way to build Whonix from source. Various security precautions such as GPG key verification are omitted.

Please read the full documentation in order to understand the process better.

Get and prepare Debian and VirtualBox

Download and verify Debian Stable/Wheezy 32 bit network install (netinst) ISO.

Download the latest version of VirtualBox and verify the downloaded packages by comparing SHA256 checksums.

After you install VirtualBox create a new virtual machine with the following specifics:

Name: Debian
Type: Linux
Version: Debian
Memory size: (go with recommended memory size) / Next
Hard Drive: Create a virtual hard drive now / Create
Hard drive file type: VDI (VirtualBox Disk Image) / Next
Storage on physical hard drive: Dynamically allocated / Next
File location and size: 50 GB / Create

Start the newly created virtual machine, select the ISO of Debian 7.6 stable (debian-7.6.0-i386-netinst.iso) and click Start.

OPTIONAL.

If you are interested in seeing a visual walk-through of the Virtual Machine preparation, click on Expand on the right.

Create a new virtual machine by clicking "New".

Click "Next".

Set name to "Debian".

Leave the memory as recommended.

New hard disk.

"VDI".

Choose "Dynamically allocated"

Set the size to 50GB. You won't use all of it.

Check if all is correct.

Create the virtual machine.

Start the VM.

Capture notification.

Welcome screen.

Locate Wheezy netinst ISO.

Check if all is correct.

Install Debian

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: (choose 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
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 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. layout.

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

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.

Preparing the system for build

## (host) login with "root"
root

## Take an image of your installation in case the build script fails in the middle. "Machine / Take snapshot". Name it "Snapshot 1".

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

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

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

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

## Reboot the system to apply the changes
shutdown -r now

OPTIONAL.

If you are interested in seeing a visual walk-through of the system preparation, click on Expand on the right.

Logging as root.

Taking a snapshot of the VM.

Adding repository to sources and running update & upgrade.

Installing git and sudo.

Adding "user to "sudo" group

Rebooting.

Building from source

## (host) login with "user"
user

## Here you can take another snapshot to avoiding doing system preparation again next time when you build. "Machine / Take snapshot". Name it "Snapshot 2".

#Get source code.
git clone https://github.com/Whonix/Whonix

## Go into the git directory
cd Whonix

## Get a list of available git tags.
git tag

## Choose which version you want to build.
git checkout 8

OPTIONAL.

If you are interested in seeing a visual walk-through of the build from source, click on Expand on the right. Pictures are shown using the tag 7.7.6.4 but you must use Template:Version

Logging as user.

Taking a snapshot of the VM.

Cloning the git source.

Entering the git directory and getting git tags.

All available tags displayed.

Checkout out Template:Version

VM Creation

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.

Build a Whonix-Gateway virtual machine image.

sudo ./whonix_build --build --tor-gateway >> ~/log-gateway 2>&1

Build a Whonix-Workstation virtual machine image.

sudo ./whonix_build --build --tor-workstation >> ~/log-workstation 2>&1

The resulting .ova images can be found in ~/whonix_binary folder.

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

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.

For Workstation

sudo ./whonix_build --build --tor-workstation 

For Gateway

sudo ./whonix_build --build --tor-gateway

OPTIONAL.

If you are interested in seeing a visual walk-through of the VM creation, click on Expand on the right.

Enter the Gateway build command

Provide sudo password

VM image export

After a few hours (depending on your disk speed, CPU clock rate, available download bandwidth, ...) the image (either Workstation or Gateway) will be created in ~/whonix_binary directory. This will take from 3 to 7 hours per image.

You need to export the OVA image and then use it in VirtualBox.

To transfer the images you can use VirtualBox's Shared Folders Functionality or USB transfer.

Export to a shared folder

To use shared folder functionality you must have Guest Additions installed.

Before installing Guest Additions read the official manual page and Whonix's wiki page.

If you still want to use it, download the ISO (VBoxGuestAdditions_4.3.6.iso) and set up folder as described in the manual.

Export via USB

Unless you install VirtualBox Extension Pack, USB 2.0 won't be supported. USB 1.1 transfer speed is very low, usually 0,5 - 1 MB/s.

Extension pack install (optional)

Before installing the extension pack read the official manual page.

To proceed, download the vbox file (Oracle_VM_VirtualBox_Extension_Pack-4.3.6-91406.vbox-extpack). Import the file in VirtualBox (File/Preferences/Extensions then locate the file). After installing, "Oracle VM VirtualBOx Extension Pack" entry will appear as "Active", resulting in a green arrow icon in front of the name.

USB transfer

Make your USB key available to the VM through selecting it in the Devices/USB devices menu. Plug it in first of course ;)

You can automount your USB or set it up manually. The former involves typing up a long command but on some computers usbmount might, for some reason, only reach speeds of USB 1.0, meaning it will take five to six hours to transfer the file. Test it out.

Using usbmount

## Install usbmount that will automatically mount your USB to media/usb0
sudo apt-get install usbmount

## Check if the USB is present and mounted
cd /media/usb0

## Copy the OVA file to USB. 
sudo cp /home/user/whonix_binary/Whonix-Workstation-8.ova /media/usb0

## or if you have been building the Gateway
sudo cp /home/user/whonix_binary/Whonix-Gateway-8.ova /media/usb0

## Unmount the USB
sudo umount /media/usb0

Deselect your USB key in the VM's Devices/USB devices menu to make it available to your host system again.

Mounting USB manually

## Create a mount point
sudo mkdir /media/usb

## Mount your USB key to /media/usb
sudo mount -t vfat /dev/sdb1 /media/usb -o uid=1000,gid=1000,utf8,dmask=027,fmask=137

## Check if the USB is present and mounted
cd /media/usb

## Copy the OVA file to USB. 
sudo cp /home/user/whonix_binary/Whonix-Workstation-8.ova /media/usb

## or if you have been building the Gateway
sudo cp /home/user/whonix_binary/Whonix-Gateway-8.ova /media/usb

## Unmount the USB
sudo umount /media/usb

Finishing up

You are done! OVA file is now on your USB key/in your shared folder. All you have to do is use it in VirtualBox.

If you want to build another image (presuming you have build only Workstation or Gateway this time) revert the VM state to Snapshot 2.

From there follow the steps as you previously did and build the image you still need Workstation or Gateway.

Footnotes

---

Random News:

We are looking for help in managing our social media accounts. Are you interested?

---

https | (forcing) onion

Share: Twitter | Facebook

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

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