Jump to: navigation, search

Dev/Build Documentation/14 full


This page documents how to build Whonix VirtualBox .ova or .qcow2 images (for KVM). For Qubes-Whonix, see Dev/Qubes#Build_Qubes-Whonix_Templates.

Host Preparation[edit]

  • You need to build on Debian stretch.
  • It is recommended to set your terminal (for example Konsole) to unlimited scrollback, so you can watch the full build log.
  • You need ~ 30 GB free disk space.
  • Short: Don't add private files to Whonix's source code folder! [...]

Long: [...] Unless you know what you are doing. Technically, it would work. This is recommended against. Those files would get managed by the respective package. When you later update Whonix debian packages, your files would get deleted by the package manager. Also adding private files to Whonix's source code folder, later contributing to Whonix's development and accidentally pushing the wrong git branch would be a disaster. Better add your private files to Whonix after building Whonix. Or add a custom build step adding your files, which then get copied from a folder outside of Whonix's source folder.

  • Short: Make sure there aren't any VMs in VirtualBox already called Whonix-Gateway or Whonix-Workstation!

Long: Because the build script would fail, because it tries to create VMs either named Whonix-Gateway or Whonix-Workstation.

  • Short: Do not try to build Whonix-Gateway and Whonix-Workstation at the same time!

Long: Building Whonix-Gateway and Whonix-Workstation at the same time is not supported due to limitations in the build script. In other words, do not try to run for example sudo ~/Whonix/whonix_build --flavor whonix-gateway -- --build --target virtualbox and sudo ~/Whonix/whonix_build --flavor whonix-workstation -- --build --target virtualbox at the same time. The build would probably fail.

  • Short: Don't use images created inside Continuous Integration (CI) environments for anything besides testing!

Usually you are not using CI environments without knowing.

You can find out if you are running inside a CI environment by running.

echo "$CI"

If it shows nothing, i.e.

Everything is fine.

Otherwise, if it were to show.


Then don't use these images for anything besides testing.

Reason: https://github.com/Whonix/Whonix/blob/master/build-steps.d/1100_prepare-build-machine#L577

sudo apt-get update
sudo apt-get install git curl

onion sources[edit]

If you are building behind a Tor transparent proxy such as Whonix-Gateway, you can skip the following steps.

Install apt-cacher-ng-, torsocks and tor.

sudo apt-get install apt-cacher-ng torsocks tor

Create folder apt-cacher-ng systemd drop-in folder /lib/systemd/system/apt-cacher-ng.service.d.

sudo mkdir -p /lib/systemd/system/apt-cacher-ng.service.d

Open /lib/systemd/system/apt-cacher-ng.service.d/50_user.conf in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run:

kdesudo kwrite /lib/systemd/system/apt-cacher-ng.service.d/50_user.conf

If you are using a terminal-only Whonix, run:

sudo nano /lib/systemd/system/apt-cacher-ng.service.d/50_user.conf


ExecStart=torsocks /usr/sbin/apt-cacher-ng SocketPath=/run/apt-cacher-ng/socket -c /etc/apt-cacher-ng ForeGround=1


Reload systemd.

sudo systemctl daemon-reload

Restart apt-cacher-ng.

sudo systemctl apt-cacher-ng restart

VM Creation[edit]

Open a terminal (such as Konsole).

The following build targets are available.

--target virtualbox
--target qcow2
--target raw
--target root

In context of build documentation for the current page you are reading, if you are interested in,

  • --target root you should look into our Physical Isolation Build Documentation instead.
  • .ova images (most likely for VirtualBox or VMware), then choose --target virtualbox
  • .qcow2 images (most likely for KVM or QEMU), then choose --target qcow2
  • .raw images (most likely for ports), then choose --target raw

--target virtualbox can be combined with --target qcow2 as well as --target raw, which is useful for redistributable builds. Note, that --target virtualbox is currently the most tested option.

Delete eventually already existing Whonix-Gateway virtual machine. Warning: This will delete a virtual machine named Whonix-Gateway from VirtualBox!

sudo REPO_PROXY= ~/Whonix/whonix_build --flavor whonix-gateway --target virtualbox --clean

Delete eventually already existing Whonix-Workstation virtual machine. Warning: This will delete a virtual machine named Whonix-Workstation from VirtualBox!

sudo REPO_PROXY= ~/Whonix/whonix_build --flavor whonix-workstation --target virtualbox --clean

Build a Whonix-Gateway virtual machine image.

sudo REPO_PROXY= ~/Whonix/whonix_build --flavor whonix-gateway --target virtualbox --build

Build a Whonix-Workstation virtual machine image.

sudo REPO_PROXY= ~/Whonix/whonix_build --flavor whonix-workstation --target virtualbox --build

The resulting .ova, .qcow2 and/or .raw images can be found in ~/whonix_binary folder.

While building, you might see a few Expected Build Warnings.

Random News:

Don't mind having your name connected to Whonix? Follow us on Twitter / Facebook / g+.

Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
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 (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, the content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.