Jump to: navigation, search

Dev/Source Code Intro

< Dev


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. It can be quite difficult to get started with hacking existing big complex projects.


This is a high level overview. Whonix-Example-Implementation can currently be build in nine steps. (There is also a whonix_build script, which automates these eight steps for your convenience.)

  • 1100_prepare-build-machine
  • 1150_export-libvirt-xml
  • 1200_create-debian-packages
  • 1300_create-raw-image
  • 1700_install-packages
  • 2300_run-chroot-scripts-post-d
  • 2400_convert-raw-to-qcow2
  • 2500_convert-raw-to-vdi
  • 2600_create-vbox-vm
  • 2700_export-vbox-vm
  • 2800_create-report


Boring methods, which are required by the build-steps above.

  • delete-vbox-vm
  • mount-raw
  • mount-vdi
  • chroot-raw
  • unchroot-raw
  • unmount-raw
  • unmount-raw-force
  • unmount-vdi
  • unmount-vdi-force
  • pre gets sourced by all other scripts.
  • variables gets sourced by all other scripts.


Is a script, which simply runs all other build-steps. Actually it's "optional". It has very little functionality besides running all other steps. You are free to run all steps one by one. That is useful for learning and for debugging purposes. In case you want to fix a bug or in case you want to upgrade the distribution or in case you want to switch the operating system or whatever you are better off running the steps manually. Run it with -help to see available switches. It has also has a --fast1 and --fast2 switch which skips certain steps, which is useful for debugging purposes if these steps were already run.


  1. prepare-build-machine: installs build dependencies and applies a few other required settings for building from source.
  2. export-libvirt-xml: Copies files from libvirt folder to ~/whonix_binary folder and adds version numbers to them.
  3. create-debian-packages: Recursively works through packages folder, builds them one by one and adds them to a local APT repository.
  4. create-raw-image: grml-debootstrap creates virtual machine images in .raw image format. It keeps care of creating the image, the partition table, grub boot manager, minimal system debootstrap and apt-get installing all Whonix packages. This step requires most time in the build process.
  5. install-packages: Installs meta .deb packages whonix-shared-packages-dependencies/recommended, desktop, desktop-kde, kde-accessibility and whonix-*-packages-dependencies/recommended and whonix-workstation-default-applications. Those only include dependencies and recommended packages which are pulled from Debian's apt repository.
  6. backup-raw-after-meta-package-install
  7. run-chroot-scripts-post-d: Post Chroot Scripts are applied.
  8. convert-raw-to-qcow2: Only having effect when using --qocw2 switch. The .raw image gets converted to a .qcow2 image. Actually not converted, a new file will be created and the old .raw remains available until cleanup is run or manually deleted or grml-debootstrap runs again. The .raw format is more "generic". VirtualBox does not support raw (.raw) images, but .vdi and .vmdk (and others).
  9. convert-raw-to-vdi: The .raw image gets converted to a .vdi image. (Actually not converted, as explained above.)
  10. create-vbox-vm: A virtual machine (VirtualBox) will be created and the .vdi image will be attached.
  11. export-vbox-vm: The virtual machines get exported to a .ova images. (Technically the .ova format seams to require .vmdk files. Therefore VirtualBox automatically creates it. So anyone using or extracting the .ova image will see that it includes a .vmdk image.)
  12. create-report: Analyses the .ova the the build script created and creates a report for Verifiable Builds.


All steps could be easily replaced to add support for additional virtualizers, operating systems and so on. The numbers before the script names (20_..., 25_..., 30..., ...) are honored by whonix_build (using run-parts), which runs these steps in lexical order. Therefore you can easily add steps to the beginning or the end or even wretch steps in between.

File sizes:

Do not get shocked by file sized. Initially the .raw is created with a size of 100 GB, but it will actually only take a fraction of that space on the harddrive. This is because .raw .vdi and .vmdk are all sparse files, which means they do not take their maximum size, but only as much data as really is inside these images.

Chroot Scripts

  • packages/anon-*-build-*/usr/lib/anon-dist/chroot-scripts-post.d/


Thus, given the nature of the build step orientated scripts, you can easily work on the different aspects of Whonix. For example, once you have created a clean virtual machine with the operating system only, you can make a copy, run either the gateway or the workstation copy routine or Chroot Scripts as often as you need to test your changes and if something goes wrong, go back to backup. You don't have to build everything from scratch again. [1]

Another Introduction:

It's really not that difficult after all. If you like, you could read Manually Creating Whonix, which is a similar topic, which covers part of this in other words.

OpenPGP keys[edit]

OpenPGP public keys required for building Whonix are stored inside various packages. These include.

To find out what the keys are good for, simply grep the source code.

cd /home/user/Whonix
grep -r tbb-keys.d *
grep -r tpoarchive-keys.d *
grep -r whonix-keys-revoked *
grep -r whonix-keys.d *

If you are in luck, you never have to update the keys yourself and the Whonix maintainer will keep them updated. Otherwise and also as a good precaution you can verify these keys manually. Follow the instructions from torproject.org to obtain the key. Then simply check if the keys match or update the old key with the new one.

Torproject's archive key expires on '2018-08-30.

gpg --fingerprint A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
pub   2048R/886DDD89 2009-09-04 [expires: 2020-08-29]
      Key fingerprint = A3C4 F0F9 79CA A22C DBA8  F512 EE8C BC9E 886D DD89
uid       [ unknown] deb.torproject.org archive signing key
sub   2048R/219EC810 2009-09-04 [expires: 2018-08-30]

Chroot Scripts[edit]

What are Chroot Scripts?[edit]

Some operations for building Whonix cannot run as part Debian maintainer scripts (preinst, postinst, prerm, postrm). Those are installed by whonix-initializer to /usr/lib/anon-dist/chroot-scripts-post.d. When those scripts are just installed, they do nothing. Those scripts are run in lexical order after package installation by a later build step of Whonix's build script (see #Introduction for overview).

How many chroot-scripts are there and what are they used for?[edit]


To get an always up to date list of packages that do ship chroot-scripts, you could run find from within Whonix's source code folder.

find . -type f -ipath *chroot-script* | sort

Here is the result that has been written at time of Whonix git tag


So let's go through them one by one.



This is actually not a chroot-script, it's the build-steps.d/2300_run-chroot-scripts-post-d build step, which is responsible of running all these chroot-scripts at Whonix build time.








Stuff you may find helpful for debugging.

Build Configuration[edit]

Build Configuration Folder[edit]

You can drop configuration file either in:

  1. buildconfig.d or in
  2. /etc/whonix_buildconfig.d
  3. ../buildconfig.d folder.

Files should have the extension .conf.

Method 2. is recommended for users.

  1. Contains examples. It's more difficult to use, since you would have to git commit your build config files. Rather use.
  2. sudo mkdir --parents /etc/whonix_buildconfig.d
  3. When /home/user/Whonix is your Whonix source folder, you could use /home/user/buildconfig.d as your Whonix build configuration folder. It's easier to use, since you don't have to git commit your build config files.


Skipping Build Steps[edit]

Rebuild the .ova images, while skipping the slow prepare-build-machine and create-debian-raw steps. (Of course, this assumes that these steps where run at least once previously.)

The sudo ./build-steps/1300_create-debian-raw -tX [3] step takes far most of the build creation time. As long as no packages have been added or removed, you can repeat all other steps from a backup, which has been automatically created for you, by using.

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

## or --tor-workstation

There is also --fast2, which skips all steps up to and including 1700_install-meta-packages.

sudo ./whonix_build --tor-gateway --build --fast2
## or --tor-workstation

Skipping Chroot and Postinst Scripts[edit]

Some chroot scripts, especially the 70_update_command_not_found and 70_torbrowser take very long, while they are non-critical. You can either run update-command-not-found and the Tor Browser Updater after Whonix has been build and booted, or if you don't wish to use them at all, just don't use it at all. Therefore you can conveniently disable them, to safe some time, which is useful for debug builds.

Create your own build configuration, see buildconfig.d folder. For see example buildconfig.d/30_skip_torbrowser, which contains

#export SKIP_SCRIPTS+=" 70_torbrowser "

You could create a folder file ../buildconfig.d and a file ../buildconfig.d/50_skip_torbrowser and add.

export SKIP_SCRIPTS+=" 70_torbrowser "

This works for the following folders.

  • whonix_*/usr/share/whonix/postinst.d
  • whonix_*/usr/share/whonix/chroot-scripts-pre.d
  • whonix_*/usr/share/whonix/chroot-scripts-post.d

Look at the file names and add them. export SKIP_SCRIPTS+=" another_file_name ". Don't forget empty spaces ( ) before and after ". [4]


Mount and inspect images[edit]

Mount and inspect images

Interactive Chroot[edit]


  • Interactively chroot Whonix-Gateway.

Open a bash shell inside the Whonix-Gateway .raw image.

sudo ./debug-steps/interactive-chroot-raw -tg
  • Interactively chroot Whonix-Workstation.

Open a bash shell inside the Whonix-Workstation .raw image.

sudo ./debug-steps/interactive-chroot-raw -tw
  • Check Whonix version number.

Important before building builds for redistribution.

Build config variable.

cat /usr/share/whonix/build_version

Less Important Goodies[edit]

Unpacking .ova images[edit]

If you want for some reason to unpack an .ova, for example to get the .vdmk image, you can use tar.

tar -xvf Whonix-Gateway.ova

Converting .vmdk images to .raw images[edit]

#qemu-img info Whonix-Gateway-disk1.vmdk

qemu-img convert Whonix-Gateway-disk1.vmdk -O raw Whonix-Gateway.raw

#qemu-img info Whonix-Gateway.raw


These are some random notes about porting Whonix update debs to rpm.

What would have to be done:

  • create rpm package
  • Find a replacement for config-package-dev, a package which allows third party packages (Whonix) to own files which are owned by other packages. Such as /etc/tor/torrc is owned by tor, but whonix-shared-files includes its own config file.
  • add init scripts (currently done by debhelper)
  • add man pages (currently done by debhelper and ronn, see debian/rules)
  • minor: replacement for dh_apparmor


  1. If something would go wrong, you would have to reinstall the whole operating system every time again. That's why we use separate steps.
  2. This is because .. means "one level below this folder".
  3. (replace X with g or w)
  4. We are expanding a bash array.

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.