Jump to: navigation, search

Dev/Build Documentation/13 full


Build Documentation[edit]

Introduction[edit]

This page documents how to build Whonix VirtualBox .ova or .qcow2 images (for KVM). For Qubes-Whonix, see Dev/Qubes#Build_Qubes-Whonix_Templates. If you have any questions or need help, get in Contact.

It documents how to build the stable of Whonix.

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

Only one prerequisite: you need a working internet connection.

For discussion related to the development and build process of Whonix images get in contact.

How to use the resulting images, is documented in the Documentation.

Warning[edit]

  • 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: Gnome user? Please disable device auto mounter and the file indexing service. You can do this by running the following commands. (If you don't know if you are a Gnome user or not, just run this command, it won't hurt.)

Long: [1]

  • Run the following command.
gsettings set org.gnome.desktop.media-handling automount-open false
  • System Tools -> Settings -> System Settings -> Details -> Removable Media -> Uncheck "Never prompt or start programs on media insertion"
  • System Tools -> Settings -> System Settings -> Search and Indexing -> Uncheck "Monitor file and directory changes"


  • Short: KDE user? It is recommended to disable nepomuk.You can do this by running the following command.

Long: [2]

Start menu -> System Settings -> Desktop Search -> uncheck Enable Nepomuk Sematic Desktop -> Apply


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

Long: [3]


  • Short: Check if the OpenPGP public keys are still up to date. If you are in luck, you never have to update the keys yourself and the Whonix maintainer will keep them updated.

Long: For better security.


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

true

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


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]

Especially, but not exclusively, if you want to distribute Whonix images, you should improve the security of your build environment.

  • Build on a dedicated build system, install security updates... (Security Guide)
  • All installation medium[4] 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]

  • You need to build on Debian stable (currently: jessie). (How to obtain Debian safely: [5]) [6]
  • Build dependencies and configurations get automatically applied, so you don't have to worry about that. [7]
  • 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. When you build inside a Virtual Machine using sparse files such as VirtualBox, consider assigning 100 GB free space. (Sparse files will grow as space is actually used. Won't take up space if it's not used. Easier to have the option to use more space than growing the image later.) More info: [8]

Building Whonix in Whonix[edit]

You only have to read this, if you want to build Whonix in Whonix.
If you are interested, click on Expand on the right.

Building Whonix in Whonix is possible as well (if the Whonix version you are using as host is also based on Debian stable (currently: wheezy)). Unfortunately, apt-cacher-ng does not like Whonix's apt repository on sourceforge.net. Patrick already reported a bug. As long as this bug isn't fixed, you need to disable Whonix's apt repository while building Whonix. You can do this using the whonix_repository tool.

sudo whonix_repository --disable

Introduction into Whonix Source Code[edit]

If you prefer to read and understand the source code just by reading scripts you may skip this optional chapter.

When you like to mess with the source code, it would probably help a lot if you at least know what .img, .vdi, .vmdk and .ova are being used for. See Source Code Introduction.

Preparation Steps[edit]

Only required if you want to redistribute (official) Whonix builds.

See Redistribution Pre Building.


Get the Signing Key[edit]

This chapter is recommended for better security, but not strictly required. (See Trust)

Download the key.

curl --tlsv1 --proto =https -o patrick.asc https://www.whonix.org/patrick.asc

Check fingerprints/owners without importing anything.

gpg --with-fingerprint patrick.asc

Verify it shows the following.

pub  4096R/2EEACCDA 2014-01-16 Patrick Schleizer <adrelanos@riseup.net>
      Key fingerprint = 916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA
sub  4096R/CE998547 2014-01-16 [expires: 2016-10-05]
sub  4096R/119B3FD6 2014-01-16 [expires: 2016-10-05]
sub  4096R/77BB3C48 2014-01-16 [expires: 2016-10-05]

If it checks out, import the key.

gpg --import patrick.asc

Only getting the signing key from one source, from the download you want to verify isn't safe. For better security, Learn about Whonix Signing Key.

Get the Source Code[edit]

Install git and curl

sudo apt-get install git curl

Get source code including git submodules. Whonix 13 / jessie.

git clone --recursive https://github.com/Whonix/Whonix

Get source code including git submodules. Whonix 14 / stretch.

git clone --jobs=200 --recursive https://github.com/Whonix/Whonix

Remember it's Whonix, not whonix! If you are prompted for a username for github, it means you have mistyped the web address.

Get into the source folder.

cd Whonix

OpenPGP Verify the Source Code[edit]

This chapter is recommended for better security, but not strictly required.[9]

Get a list of available git tags.

git tag

Verify the tag you want to build.

## ... Replace with tag you want to build.
git verify-tag 13.0.0.1.4-stable

Output should look similar to this.

object 1844108109a5f2f8bddcf2257b9f3675be5cfb22
type commit
tag 13.0.0.1.4
tagger Patrick Schleizer <adrelanos@riseup.net> 1392320095 +0000

.
gpg: Signature made Thu 13 Feb 2014 07:34:55 PM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]

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.

By convention, git tags should point to signed git commits. [11] (forum discussion) It is recommended to verify the signature of the git commit as well. (Replace 13.0.0.1.4 with the actual git tag you want to verify.)

git verify-commit 13.0.0.1.4-stable^{commit}

Output should look similar to this.

commit 5aa1c307c943be60e7d2bfa5727fa5ada3a79c4a
gpg: Signature made Sun 07 Dec 2014 01:22:22 AM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]
Author: Patrick Schleizer <adrelanos@riseup.net>
Date:   Sun Dec 7 01:22:22 2014 +0000

    .

Choose Version[edit]

Git checkout, which version (or git branch) you want to build.

In case you want to build a specific git tag.

git checkout 13.0.0.1.4-stable

You have to replace 13.0.0.1.4 with the actual version you want to build. The stable version, the testers-only version or the developers version. Common sense is required while choosing the right version number. For example, the biggest version number is not necessarily the most recommended / latest stable version. You can learn about current versions reading Whonix News Blogs.

Clean up and Sanitize[edit]

This is also important for security.

Get a list of eventually extraneous files and folders. [12]

git clean -ndff

And look if that looks sane. (Generally should, unless you are modifying Whonix's source code, then you should understand git a bit better and know what you are doing.) If it looks like the following, everything is fine.

Would remove packages/apparmor-profile-gwenview/
Would remove packages/kde-privacy/

Now get rid of these folders.

git clean -dff

Should show.

Removing packages/apparmor-profile-gwenview/
Removing packages/kde-privacy/

Make sure you have checked out the right commit for each git submodule.

git submodule update --init --recursive

Check if there are no extraneous files. This is important for security.

git status

Should only show and nothing else.

# Not currently on any branch.
nothing to commit (working directory clean)

Otherwise we'd need to get rid of these files first.


Build Configuration (Optional)[edit]

Introduction (Optional)

Usually you do not have to change the build configuration. Whonix build from source code comes with safe defaults. Whonix's APT Repository will NOT be used.

The most interesting build configurations (Terminal-Only, NoDefaultApps etc.) are documented in the following chapters below.

If you are interested, click on Expand on the right.

If you used build configurations earlier, it might be better to delete your build configuration folder since a few example files names change changed in meanwhile.

sudo rm -r /etc/whonix_buildconfig.d

Alternatively, if you know what you are doing, you can of course also manually get into the /etc/whonix_buildconfig.d folder, examine and change its contents to your linking.

/etc/whonix_buildconfig.d is a modular flexible .d style configuration folder.

Less popular build configurations are documented in the buildconfig.d folder and on the Dev/Source_Code_Intro#Build_Configuration page in a less user friendly documented way.

It is recommended to copy and paste text when creating build configuration files to avoid typos. Also keep care, that your editor even when you are using copy and paste, won't capitalizes variable names which are supposed to be lower case.

Platforms Choice (Optional)

Advanced users can create 64bit instead of 32bit builds.

If you are interested, click on Expand on the right.

By default, Linux 32 bit is used. [13] 64bit builds are less tested due to lack of developer manpower. Should work well in principle. Whonix 14 will be 64 bit by default. Forum discussion: State of offical 64 bit builds

Note, you cannot build 64 bit if you are running a 32 bit kernel. [14] In that case, try installing the packages linux-image-amd64 and linux-headers-amd64. Then boot that amd64 kernel by choosing it in your boot menu. (This does not require re-installation of the whole system. Just make sure you boot with an amd64 kernel.)

Linux 64 bit. To build Whonix 64 bit, add the following build parameter. [15] [16]

--arch amd64

kFreeBSD. entirely untested and most likely needs work. See footnotes. [17]

Whonix for arm64 development discussion:
https://forums.whonix.org/t/whonix-for-arm64

Whonix APT Repository (Optional)

Non-Qubes-Whonix:
Whonix's APT Repository is disabled by default since Whonix 7.3.3. You may enjoy this for Trust reasons. You can later update Whonix debian packages from source code if you want. If you are interested in enabling Whonix's APT repository right after building (you could do that also after booting your build for the first time if you wanted) for convenience while sacrificing the extra security of not updating from source code, click on Expand on the right side.

Do you want to opt-in for Whonix's APT Repository? You can do this using an environment variable or build configuration. Below is an example using an environment variable.

WHONIX_APT_REPOSITORY_OPTS='--enable --repository stable'
WHONIX_APT_REPOSITORY_OPTS='--enable --repository testers'
WHONIX_APT_REPOSITORY_OPTS='--enable --repository developers'
WHONIX_APT_REPOSITORY_OPTS='--enable --codename jessie'

Add an environment variable as one can usually do that on the Linux platform. For example, if you wanted to enable Whonix stable repository during build, you could set WHONIX_APT_REPOSITORY_OPTS by interjecting it between sudo and the ./whonix_build command. Below is an example. Do not use [...]. Replace it with your other build parameters (such as --build, <code>--target etc.) after ./whonix_build.

sudo WHONIX_APT_REPOSITORY_OPTS='--enable --repository stable' ./whonix_build [...]

APT Cache (Optional)

Using an apt cache will greatly improve build speed when building several times in a row (debugging, development).

If you are interested, click on Expand on the right.

In short: just get an apt cache running and set the REPO_PROXY environment variable.

Example.

sudo apt-get install apt-cacher-ng

Be sure to have a firewall, so not the whole internet can use your apt-cacher-ng service.

sudo REPO_PROXY=http://127.0.0.1:3142 ./whonix_build ...

If you are building inside a non-Whonix VM, you could use an apt cache on the host. In that case adjust the IP accordingly. (And manually test it is reachable.) If you are building inside a (Whonix) VM, you can just install the apt cache inside the VM and the point to a localhost apt cache.

VM Settings (Optional)

Only relevant for VM builds.

Examples below. Values can be changed.

VirtualBox's --vmsize option (virtual RAM).

--vmram 128

VirtualBox's --vram option (virtual video RAM).

--vram 12

grml-debootstrap's --vmsize option.

--vmsize 200G

grml-debootstrap's --filesystem option.

--file-system ext4

grml-debootstrap's --hostname option. (The anon-base-files package will change that later again.)

--hostname host

grml-debootstrap's --password option.

--os-password changeme

grml-debootstrap's --debopt option.

--debopt "--verbose"


Skip Steps (Optional)

--sanity-tests false

Source Code Changes

Only in case you made changes to the Whonix source folder! In that case click on Expand on the right.
Not required if you only added using your own build configuration in /etc/whonix_buildconfig.d folder.

If you made changes to the Whonix source code, it is the easiest to use the following build parameter.

--allow-uncommitted true

Or if you are not building from a git tag, it is the easiest to use the following build parameter.

--allow-untagged true

Otherwise changes would have to be committed to git first and then a git tag would have to be created.


VM Creation[edit]

Open a terminal (such as Konsole).

The whonix_build script can invoke the help-steps/whonix_build_one help step multiple times to build multiple virtual machines at once. The syntax is.

whonix_build <parameters for whonix_build> -- <parameters for help-steps/whonix_build_one>

Don't worry too much about the syntax, you'll see hands-on examples below.

The help-steps/whonix_build_one help step needs a parameter to know your build target. 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 ~/Whonix/whonix_build --flavor whonix-gateway -- --clean --target virtualbox

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

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

From now, you have two options. If you do not wish to use different build configurations for Whonix-Gateway and Whonix-Workstation (for example, if you do not wish to create a terminal-only Whonix-Gateway and a full Whonix-Workstation), to build both virtual machines at once, you could use.

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

If you wish to use different build configurations, you must build one after the other as described below.

Build a Whonix-Gateway virtual machine image.

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

Eventually, if you wish to use a different build configuration for Whonix-Workstation, change the contents in your /etc/whonix_buildconfig.d folder.

Build a Whonix-Workstation virtual machine image.

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

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.

Check if all went ok.

Please report back any issues!

Build Verification (Optional)[edit]

OPTIONAL!

Since Whonix 7.5.2, advanced users who build Whonix from source code can increase certainty, that their image is free from perhaps anonymity critical bugs, by verifying, that their image is very similar to redistributed Whonix .ova's. This is optional, but can improve security.

If you are interested, click on Expand on the right.

Congratulations, you already created your own build of Whonix. If you want, you can compare your build with official builds for better security. See Verifiable Builds.

Cleanup[edit]

OPTIONAL!

Remove temporary files.

Warning, this will run git clean -d --force --force in Whonix's main source code folder (~/Whonix) as well as in all sub folders of the Whonix packages folder ~/Whonix/packages. This means, if you knowingly added any files to any of these folders that have not been committed to git, these will be deleted.

[18]

./help-steps/cleanup-files


Debugging[edit]

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

See Debugging.

Final Steps[edit]

Only required if you want to redistribute (official) Whonix builds.

See Redistribution Post Building.

Source Code / Hacking / Development Tickets[edit]

See Developer Portal.

Contact[edit]

Development Forum | Developer Mailing List | github | Contact

Expected Build Warnings[edit]

Can not write log, openpty() failed (/dev/pts not mounted?)

Does not affect the build. [19]

[....] Your system does not have the CPU extensions required to use KVM. Not doing anything. ...[ FAIL ]

Does not affect the build. [20]

[....] Stopping VirtualBox kernel modules [ ok ].
[....] Starting VirtualBox kernel modules[....] No suitable module for running kernel found ...[ FAIL ]
invoke-rc.d: initscript virtualbox, action "restart" failed.

Does not affect the build. [21]

WARNING: The character device /dev/vboxdrv does not exist.
	 Please install the virtualbox-ose-dkms package and the appropriate
	 headers, most likely linux-headers-486.

	 You will not be able to start VMs until this problem is fixed.

Does not affect the build. [22]

dpkg: warning: failed to open configuration file '/root/.dpkg.cfg' for reading: Permission denied

Does not affect the build. [23]

Related forum topic:
Expected Build Warnings

Footnotes[edit]

  1. Otherwise a file manager may open Whonix's chroot folder (the directory, in which the image which is currently build is mounted) while building Whonix which could lead to failing umount because the device is still busy.
  2. Nepomuk indexing the whonix_binary folder wastes some time indexing.
  3. Because the build script would fail, because it tries to create VMs either named Whonix-Gateway or Whonix-Workstation.
  4. Such as DVD or USB.
  5. Debian ISO OpenPGP verification
  6. The build scripts could be adapted to run on other *NIX systems as well but currently they assume apt-get and grml-debootstrap to be available.
  7. By build-steps.d/1100_prepare-build-machine.))
  8. ~ 25 GB might suffice as well. We haven't messured that in detail yet. Less space required, if you only want to build either Whonix-Gateway or Whonix-Workstation. Less space for Whonix-Gateway required than for Whonix-Workstation.
  9. See Trust.
  10. As defined by TUF: Attacks and Weaknesses:
  11. Beginning from git tag 9.6 and above.
  12. There currently is a small issue. (A limitation of git.)
  13. And linux-image-686-pae linux-headers-686-pae linux-image-486 linux-headers-486 kernel is installed. The 486 kernel only gets installed for compatibility reasons. If you have modern hardware, you can omit linux-image-486 linux-headers-486. Or if you have ancient hardware, you could omit linux-image-686-pae linux-headers-686-pae.
  14. https://github.com/grml/grml-debootstrap/pull/13
  15. Only installs linux-image-amd64 linux-headers-amd64 kernel.
  16. For --arch amd64, the following is implicitly added unless you manually set these.
    --kernel linux-image-amd64 --headers linux-headers-amd64
    
  17. Lacks --kernel and --headers. kFreeBSD 64 bit.
    --arch kfreebsd-i386
    

    kFreeBSD 32 bit.

    --arch kfreebsd-amd64
    
  18. https://github.com/Whonix/Whonix/blob/master/help-steps/cleanup-files
  19. This is nothing to worry about. It only happens because we are running commands inside chroot. If you research this "issue", you'll find that it is purely cosmetic.
  20. KVM gets installed as a dependency of our build dependency libguestfs-tools. We don't need KVM for building the actual images.
  21. This only means that VirtualBox cannot be started. VirtualBox kernel modules could not be compiled, because the linux-headers-$(uname -r) package was not installed prior to installing VirtualBox (prior to starting Whonix's build script). The build script doesn't start VirtualBox, hence does not affect the build. The build script only uses VBoxManage for creation of virtual machine description files and that tool doesn't need VirtualBox kernel modules.
  22. The same issue referenced above.
  23. This happens because we are running debuild as user, not root. It is probably a bug in dpkg. If you research this, you'll find there are many similar bugs in dpkg.

Random News:

Bored? Want to chat with other Whonix users? Join us in IRC chat (Webchat).


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.