Jump to: navigation, search

Dev/Build Documentation/8 in VM

Documentation[edit]

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[edit]

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

1a.png


Click "Next".

2a.png


Set name to "Debian".

3a.png


Leave the memory as recommended.

4aa.png


New hard disk.

5a.png


"VDI".

6a.png


Choose "Dynamically allocated"

7a.png


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

8aa.png


Check if all is correct.

9aa.png


Create the virtual machine.

10aa.png


Start the VM.

11aa.png


Capture notification.

12a.png


Welcome screen.

13a.png


Locate Wheezy netinst ISO.

13aa.png


Check if all is correct.

14aa.png

Install Debian[edit]

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

Select a language: English
Select your location: United States
Configure the keyboard: (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"

20.png


Set language as English.

21.png


Set location as United States.

22a.png


Select your keyboard. layout.

23.png


Installing additional content.

53.png


Network will auto-configure (hopefully).

24.png


Set the hostname to "host".

25.png


Leave the domain name empty.

26.png


Pick a strong root password.

27.png


Reenter the password.

28.png


Full name should should be "user".

29.png


Username should also be "user".

30.png


Enter a strong user password.

31.png


Reenter the password.

32.png


Network time procedure.

33.png


Use a guided partitioning method with the whole disk (FDE is a good idea).

34.png


Select the suggested disk.

35.png


Partition all files in one partition.

36.png


Finish partitioning.

37.png


Confirm the changes.

38.png


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

39.png 40.png


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

41.png


Confirm that you want to continue without a mirror.

42.png


Configuring apt.

43.png


"No thanks" to survey participation.

44.png


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

45.png 46.png


Install GRUB.

47.png


Select your disk.

48.png


Finishing the installation.

49.png


Done! The system will reboot.

50.png


OS screen.

51.png


Login screen.

52a.png

Preparing the system for build[edit]

## (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.

1b.png


Taking a snapshot of the VM.

2b.png

2bb.png


Adding repository to sources and running update & upgrade.

3b.png 4b.png


Installing git and sudo.

5b.png 6b.png 7b.png


Adding "user to "sudo" group

8b.png


Rebooting.

9b.png

Building from source[edit]

## (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 9

Logging as user.

10b.png


Taking a snapshot of the VM.

2b.png

12bbb.png


Cloning the git source.

12b.png


Entering the git directory and getting git tags.

13b.png


All available tags displayed.

14b.png


Checkout out 9

15b.png

VM Creation[edit]

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


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

16b.png


Provide sudo password

18b.png

VM image export[edit]

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[edit]

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[edit]

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)[edit]

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[edit]

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[edit]
## 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[edit]
## 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[edit]

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[edit]



Random News:

Wondering why Whonix will always be Free? Check out Why Whonix is Free Software.


Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
This is a wiki. Want to improve this page? Help welcome, volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation. Whonix (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.