Dev/Build Documentation/0.4.0

< Dev‎ | Build Documentation(Redirected from BuildDocumentation 0.4.0)

This is an outdated version. Go to Dev/Build Documentation.

Source Code: 0.4.4 -

Download: 0.4.4 -

# Copyright:
# adrelanos (aka proper)
# License:
# GPL v3 or any later
# Any changes you pull into this source will be also licensed
# under GPL v3 or any later. Additionally you grant adrelanos the right to
# re-license your work under a different license. If that is not acceptable,
# you can either fork this source under GPL v3 or any later or contact
# adrelanos. Contact adrelanos, if you require this source code under
# different license.
# Authors:
# adrelanos (aka proper)
# Big contributions from anonymous.
# Leaktest and other stuff contributed by smarm.

This page documents how the binary distribution images are built. If you have any questions or need help let us know on Dev/Archived Discussions.

Following these instructions will build version Whonix based on Tor 0.2.3 and Debian Wheezy.

Knowledge assumed: Virtualization and networking basic principles; operation of your platform; Linux knowledge: how to install Debian and basic command line knowledge.

Only one prerequisites: you need a working internet connection.

For discussion related to the development and build process of Whonix images go Dev/Archived Discussions.

Build Anonymity[edit]

While downloading the required tools for building Whonix your internet service provider could if he want notice that you want to build Whonix. This is especially interesting, if you want to redistribute Whonix, but still want to stay anonymous. The full story can be read in the chapter Build Anonymity.

Build Security[edit]

  • Build on a dedicated build system, install security updates...
  • All install media and all downloaded/used code must be verified (including all software on the host).
  • Hashes, fingerprints in the scripts and the wiki is not to be trusted. Verify everything.
  • Read Trust

Host preparation[edit]

Building on Linux[edit]

We recommend you to use a dedicated OS installation just for hosting the Whonix VMs. (See Security Guide)

You need to use Debian. The build scripts could be adapted to run on other *NIX systems as well but currently they assume apt-get to be available. You need about 15 GB of free space.

Install the latest security updates, install VirtualBox (and qemu-kvm which is required to mount the VirtualBox .vdi images). Reboot to apply kernel updates.

sudo apt-get update && sudo apt-get dist-upgrade
sudo apt-get install virtualbox qemu genisoimage apt-cacher-ng grml-debootstrap parted kpartx debootstrap mksh dialog git
sudo reboot

Building on Windows[edit]

Building on Windows is no longer supported. Redistributed Whonix builds should be build on Linux. If you want to port the Whonix build scripts to Windows, please contact us. Running Whonix on a Windows host with VirtualBox installed should is still possible.

Using an apt cache to speed up downloading[edit]

If you want to build multiple times (for debugging etc.), it makes sense to install a local apt proxy on your build machine.1 That safes download time and traffic.2 If you build Whonix on Whonix, apt-cacher-ng will go through Tor's TransPort.

,, 1 Thanks to source. 2 It would be possible to download without an apt-cacher. But why? If you want so ignore this chapter and change the mirror settings in grml configuration file. 

Open /etc/apt/apt.conf.

sudo nano /etc/apt/apt.conf

Add the following.

# /etc/apt/apt.conf
Acquire::http { Proxy ""; };

Restart apt-cacher-ng. Should not be required, but it was for me.

sudo service apt-cacher-ng restart

Safe and test if it is working.

sudo /usr/bin/apt-get update

Source Code Intro[edit]

This chapter is dedicated to give an introduction into the Whonix source code. If you prefer to read and understand the source code just by reading scripts you may skip this optional chapter.

Moved to Dev/Source Code Intro.

Build as user "user"[edit]

You need a user account named "user". If you don't already have it, create it.

sudo adduser user

During the build process "user" also needs root.

sudo addgroup user sudo

Log in as "user".

This is because the source code is far from perfect. The username "user" and /home/user/Whonix is hardcoded and expected as source folder. Bug: no longer hardcode user folder 

Get the Whonix source code[edit]

git clone

Verify the Whonix source code with gpg[edit]

This is recommended but not required. See Trust.

  1. Learn about Whonix signing key.

(1.1) Get into the correct git branch.

##Not required. Still using the master branch.
##Next Whonix version will reflect the new branching model.
#git checkout stable
  1. Get a list of available git tags.

    git tag

  2. Verify the tag you want to build.

    Replace with tag you want to build.[edit]

    git tag -v

  3. Output should look like the following.

    object 13870efc29018065267788f9f23026e6ff489684 type commit tag tagger adrelanos invalid@invalid 1348681401 -0400 gpg: Signature made Wed Sep 26 17:43:26 2012 UTC using RSA key ID 713AAEEF gpg: Good signature from "adrelanos <email @ removed>"

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

Create the Images[edit]


  1. Git checkout, which version you want to build.

    git checkout

  2. Make the build script executable:

    chmod +x ~/Whonix/whonix_*

  3. Make sure there aren't any VMs in VirtualBox already called "Whonix-Gateway" or "Whonix-Workstation" (TODO: automate that)

  4. Check if /home/user/Whonix/usr/share/version for version number.

VM Creation[edit]

  1. Open a shell and type:

    sudo ~/Whonix/whonix_build -all

  2. Check if all went ok.

The scripts can fail for many reasons, please report back any issues!


OPTIONAL (Only in case something goes wrong or you want to audit or develop Whonix.)

How to use the ova images[edit]

Reboot both VMs. Please read the Documentation!

Final Steps (Only Required For Redistribution)[edit]

See Release Folder in Whonix source code.

No user support in comments. See Support.

Comments will be deleted after some time. Specifically after comments have been addressed in form of wiki enhancements. See Wiki Comments Policy.

Add your comment
Whonix welcomes all comments. If you do not want to be anonymous, register or log in. It is free.

Random News:

Are you proficient with iptables? Want to contribute? Check out possible improvements to iptables. Please come and introduce yourself in the development forum.

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

Whonix is provided by ENCRYPTED SUPPORT LP. See Imprint.