Jump to: navigation, search

Template:Build Configuration

Build Configuration (Optional)[edit]

Introduction (Optional)[edit]

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.

Terminal-Only Builds (Optional)[edit]

OPTIONAL!

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]

OPTIONAL!

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.

The --apps switch was removed in Whonix 14 since broken and unmaintained!

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]

OPTIONAL!

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

Footnotes:

  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]

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. [1] 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. [2] 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. [3] [4]

--arch amd64

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

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

Whonix APT Repository (Optional)[edit]

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 [...]

Only Minimal Report (Optional)[edit]

OPTIONAL!

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]

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.

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.
#whonix_build_version="6"
#whonix_deb_package_version="2:7-debpackage1"

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.

whonix_build_version="9"
whonix_deb_package_version="3:0.4-1"

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]

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

OPTIONAL!

--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:

There are five different options for subscribing to Whonix source code changes.


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.

  1. 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.
  2. https://github.com/grml/grml-debootstrap/pull/13
  3. Only installs linux-image-amd64 linux-headers-amd64 kernel.
  4. For --arch amd64, the following is implicitly added unless you manually set these.
    --kernel linux-image-amd64 --headers linux-headers-amd64
    
  5. Lacks --kernel and --headers. kFreeBSD 64 bit.
    --arch kfreebsd-i386
    

    kFreeBSD 32 bit.

    --arch kfreebsd-amd64