Jump to: navigation, search

Template:Build Configuration

Build Configuration (Optional)[edit]

Introduction (Optional)[edit]


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.

Terminal-Only Builds (Optional)[edit]


Advanced users can build a no-default-gui / no-KDE / terminal-only Whonix-Gateway and/or Whonix-Workstation.

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

terminal-only builds are less tested due to lack of contributor manpower. Should work well in principle.

--gui none

NoDefaultApps Builds (Optional)[edit]


Advanced users can install fewer recommended packages to make the resulting build smaller and more customizable. (recommended as in useful to have, not necessary to have them for some other reason.)

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

NoDefaultApps builds are less tested due to lack of contributor manpower. Should work well in principle.

NOTE: You most likely want to combine this with terminal-only builds, see above.

NOTE: Such a NoDefaultApps system would for example not include Arm on Whonix-Gateway. So please do not create a NoDefaultApps build and then complain, that packages are missing.

To learn, what packages for example the whonix-gateway-packages-recommended package would install, search in the debian/control file for Package: whonix-gateway-packages-recommended.

We're just excluding a few meta packages. (Meta packages are packages, which do not hold files on its own, but only instruct apt-get to install other packages.)

--apps false

CurrentSources Builds (Optional)[edit]


Advanced users could install from Current Sources (custom) instead of from Frozen Sources (default in 7.4.0 and above). Both options have security advantages and disadvantages.

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

CurrentSources builds are rarely tested due to lack of contributor manpower. Should work reasonably well in principle as long as no packages are removed from Debian. The worst thing that can probably happen, is that the build fails due to missing packages.

Frozen Sources:

  • Whonix's build script will use http://snapshot.debian.org instead of the more popular ftp.us.debian.org.
  • Snapshot.debian.org will never change, i.e. their packages and versions will remain the same forever*[currentsources 1] [currentsources 2].
  • Using Frozen Sources has the advantage that all builders end up with a very similar [currentsources 3] image. This gives builders more confidence, that they have ended up with an intact image.
  • Are a precondition for the Verifiable Builds security feature.
  • It follows, when building a fresh image it will contain outdated packages. (You can upgrade after booting for the first time.)
  • Package downloads are still verified, but we have to ignore the valid-until field. Which means, a man-in-the-middle attack capable adversary could feed you with packages even older than configured in the version of Whonix you are building. Any packages which were ever signed with the APT repository signing key of that codename[currentsources 4]. You might not like that and therefore prefer building from Current Sources.
  • At some point, for example if remotely exploitable vulnerabilities are found in the apt-get version (defined by Frozen Sources) it may be dangerous to continue building that version.
  • We should compare our images with each other to ensure no man-in-the-middle attack has happened while building Whonix.

Current Debian APT repository:

  • Packages and versions may change over time. Packages may be removed, replaced with others, versions get security other other updates.
  • Build script may break the older the Whonix source code version release becomes. (Break as in the build won't finish - not as in creating images containing bugs.)
  • Each builder ends up with an individual image.
  • Valid-until field gets verified.

If you prefer to build from Current Sources, please add the following build script command line argument.

--freshness current


  1. Besides a few rare exceptions.
  2. As long the great snapshot.debian.org service lasts.
  3. Timestamps, temporary files and who knows what else (open research question) differ.
  4. Codename as in Testing, Wheezy, Jessie.

64bit Builds (Optional)[edit]


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

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

64bit builds are less tested due to lack of developer manpower. Should work well in principle.

Note, you cannot build 64 bit if you are running a 32 bit kernel. [1] 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.)

By default, Linux 32 bit is used 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 it. Or if you have ancient hardware, you could ommit the 686 kernel. This can be changed using any of the following command line parameters.

Linux 64 bit. Less tested. Only installs linux-image-amd64 linux-headers-amd64 kernel. [2]

--arch amd64

Linux 32 bit. Only installs linux-image-686-pae linux-headers-686-pae kernel. Does not install linux-image-486 linux-headers-486 kernel.

--arch i386

Linux 32 bit. Only installs linux-image-486 linux-headers-486 kernel. Does not install linux-image-686-pae linux-headers-686-pae kernel.

--kernel linux-image-amd64 --headers linux-headers-amd64

You could also combine --arch with --kernel and --headers.

kFreeBSD. entirely untested and most likely needs work. Lacks --kernel and --headers.

kFreeBSD 64 bit.

--arch kfreebsd-i386

kFreeBSD 32 bit.

--arch kfreebsd-amd64

Whonix for arm64 development discussion:

Whonix APT Repository (Optional)[edit]


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?


(See build script --help.)

Only Minimal Report (Optional)[edit]


By opt-in Whonix's last build step creates a report file of all hdd contents. (See Verifiable Builds for details.) This step is optional. First introduced in Whonix 7.4.8. Whonix should work fine without that step. It is used for extra security. This step takes quite some time. If you want to enable it, click on Expand on the right side.

Do you want to opt-in of the report creation build step?

--report true

APT Cache (Optional)[edit]


When building in a virtual machine, builders can use their own http proxy (apt cache) on the host, which will greatly improve build speed when building several times in a row (debugging, development).

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

This isn't required when you are building virtual machine images, because then apt-cacher-ng is automatically set up for you. Only useful when using --install-to-root in a virtual machine.

Requires Whonix or above.


On the host.

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.

Inside your Virtual Machine.

Don't forget to replace with your host's internal IP (use "sudo ifconfig" on your host to find out what your internal IP is).

export http_proxy=

Don't forget to add -E to sudo, so environment variables are preserved. Examples.

sudo -E ./whonix_build --install-to-root --tor-gateway --build
sudo -E ./build-steps.d/1100_prepare-build-machine --install-to-root --tor-gateway

Custom Build Tags[edit]

Only if you are using your own git tags! In that case click on Expand on the right.

If you created for example a git tag "9.1" and want to receive Whonix News for "9", apply this.

Please look into packages/whonixcheck/etc/whonix.d/30_whonixcheck_default. Look for.

## Override what version whonixcheck will show in its window title and which
## Whonix News will be downloaded. Change only if you know what you are doing.

Create a file /etc/whonix.d/50_whonixcheck_user and add for example. (You still have to replace "7" with the custom git tag you are using.


When you later update from Whonix debian packages from for example "9.1" to "10", these settings have to be commented out.

VM Settings (Optional)[edit]


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)[edit]


--sanity-tests false

Source Code Changes[edit]

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.

Random News:

Did you know that anyone can edit Whonix's wiki?

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.

  1. https://github.com/grml/grml-debootstrap/pull/13
  2. For --arch amd64, the following is implicitly added unless you manually set these.
    --kernel linux-image-amd64 --headers linux-headers-amd64