Dev/Build Documentation/8 in VM
- 1 Documentation
- 1.1 Get and prepare Debian and VirtualBox
- 1.2 Install Debian
- 1.3 Preparing the system for build
- 1.4 Building from source
- 1.5 VM Creation
- 1.6 VM image export
- 1.7 Finishing up
- 2 Footnotes
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.
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.
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".
Set name to "Debian".
Leave the memory as recommended.
New hard disk.
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.
Locate Wheezy netinst ISO.
Check if all is correct.
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
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.
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.
"No thanks" to survey participation.
Deselect (no star) the given option (using Space).
Select your disk.
Finishing the installation.
Done! The system will reboot.
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
If you are interested in seeing a visual walk-through of the system preparation, click on Expand on the right.
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
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 22.214.171.124 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
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 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.
sudo ./whonix_build --build --tor-workstation
sudo ./whonix_build --build --tor-gateway
If you are interested in seeing a visual walk-through of the VM creation, click on Expand on the right.
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 indirectory. 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.
To use shared folder functionality you must have Guest Additions installed.
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.
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.
## 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
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.
https | (forcing) onion
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.