Build Configuration

Whonix ®

Download

Windows Linux Mac VirtualBox KVM Qubes Intel / AMD64 ARM64 PPC64 USB ISO Raspberry Pi More options Source Code

About

Overview Features Whonix vs VPNs Why Open Source? Project Activities Contributors Mission & Vision

Docs

Documentation FAQ Troubleshooting

Community

Forums Forum Best Practices Contribute

Support

Self Support First Policy Search Engines, Docs and AI Support (Limited) Reporting Bugs Contact (Restricted)

Tools Upload file Special pages Recent changes Print Version Page meta What links here Related changes Page information

Page Read Edit History Move Protection Unwatch Watch Delete Purge

User Preferences Watchlist Contributions Logout Create account Login

Donate

Non-Qubes-Whonix Build Configuration. APT Repository, Onion Sources, APT Cache, VM Settings, Skip Steps, Source Code Changes

Introduction

Usually the build configuration does not need to be changed. Whonix built from source code comes with safe defaults. The Derivative APT Repository will not be used.

The most interesting build configurations are documented in the following chapters.

If build configurations were used earlier, it might be better to delete the build configuration folder. A few example filenames may have changed since the last build.

sudo rm -r /etc/buildconfig-dist.d

/etc/buildconfig-dist.d is a modular flexible .d style configuration folder.

Less popular build configurations are documented in the derivative-maker buildconfig.d folder and on the Dev/Source_Code_Intro#Build_Configuration page, but it is less user-friendly.

To avoid typos, it is best to copy and paste text when creating build configuration files. Take care that editors do not capitalize variable names which are supposed to be lower case during copy and paste procedures.

Note: All of the following build configuration steps are optional.

Platforms Choice

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

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

• Whonix is 64-bit by default.

To build Whonix 32-bit, add the following build parameter.

--arch i386

• kFreeBSD is entirely untested and most likely needs additional work (see footnotes).

• Whonix for arm64 development discussion (working and tested with QEMU on Mac M1):

--arch arm64

• • https://forums.whonix.org/t/whonix-for-arm64-raspberry-pi-rpi/723
  • https://forums.whonix.org/t/whonix-on-mac-with-arm-m1/11310

• Generally speaking, 64-bit builds cannot be created if running a 32-bit host kernel. See footnotes.

Derivative APT Repository

Non-Qubes-Whonix:
Whonix APT Repository is disabled by default for builds from source code for reasons of Trust. Users can decide to update Whonix Debian packages by building them from source code (greater security). Alternatively, Whonix APT repository can be enabled right after building or after booting the build for the first time (greater convenience) using Whonix repository tool. To use the latter method which sacrifices security for convenience, click on Expand on the right side.

Do you want to opt-in Whonix APT Repository?

The easy way to add Whonix stable repository the following command line option can be used.

--repo true

Other settings can be set using an environment variable or build configuration. Below are examples using an environment variable.

DERIVATIVE_APT_REPOSITORY_OPTS='--enable --repository stable' DERIVATIVE_APT_REPOSITORY_OPTS='--enable --repository testers' DERIVATIVE_APT_REPOSITORY_OPTS='--enable --repository developers' DERIVATIVE_APT_REPOSITORY_OPTS='--enable --codename bookworm'

Add an environment variable as one normally does on that specific Linux platform. For example, to enable the Whonix stable repository during build, you could set DERIVATIVE_APT_REPOSITORY_OPTS by interjecting it between sudo and the ./derivative-maker command. Below is an example. Do not use [...]. Replace it with other chosen build parameters (such as --build, --target etc.) after ./derivative-maker.

sudo DERIVATIVE_APT_REPOSITORY_OPTS='--enable --repository stable' ./derivative-maker [...]

APT Onion Build Sources

For better build security, you can also use onions apt sources for building Whonix.

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

This does not ensure all of Whonix's build process will be torified! See Build Anonymity.

--connection onion

Torified or Host APT Cache

Using an apt cache will greatly improve build speed when building several times in a row (e.g. when debugging, during development). Whonix build script sets up an apt cache by default.

If you are interested in a torified apt-cacher-ng or host apt-cacher-ng, click on Expand on the right.

torified apt-cacher-ng

Notes:

• The following torified apt-cacher-ng setup only has to be applied, if you are building using onion apt sources using --connection onion.
• When building inside Whonix-Workstation^™, this is not required.

Note, this neither torifies all of the build script's connections nor hides Tor from your ISP! See Build Anonymity.

The goal of this is to torify apt-cacher-ng using torsocks so it will be able to connect to onions.

Note: This is currently broken. No fix available. Undocumented.

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

sudo apt install apt-cacher-ng torsocks tor

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

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

Select your platform.

Non-Qubes-Whonix^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

Note: Mousepad (or the chosen text editor) must be closed before running the sudoedit command.

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

Qubes-Whonix^™

NOTES:

• When using Qubes-Whonix, this needs to be done inside the Template.

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

• After applying this change, shutdown the Template.
• All App Qubes based on the Template need to be restarted if they were already running.
• This is a general procedure required for Qubes and unspecific to Qubes-Whonix^™.

Others and Alternatives

• This is just an example. Other tools could achieve the same goal.
• If this example does not work for you or if you are not using Whonix, please refer to this link.

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

4. Add.

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

5. Save.

6. Reload systemd.

sudo systemctl daemon-reload

7. Restart apt-cacher-ng.

sudo systemctl restart apt-cacher-ng

8. Done.

The process of torification of apt-cacher-ng has been completed.

9. Broken!

/etc/tor/torsocks.conf add:

AllowInbound 1 AllowOutboundLocalhost 1

But this is also insufficient.

sudo journalctl -f -u apt-cacher-ng

shows errors:

WARNING torsocks[17645]: Config file not found: /etc/tor/torsocks.conf. Using default for Tor (in config_file_read() at config-file.c:583)
Couldn't listen on socket: Operation not permitted
Error creating socket: Function not implemented

No fix available. Help welcome.

host apt-cacher-ng

This is probably only useful for developers. Most users will not need the complexity of an apt-cacher-ng running outside of the VM which runs derivative-maker or on another computer.

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

When building inside a non-Whonix VM, an apt cache can be used on the host. In that case, adjust the IP accordingly and manually test that it is reachable. When building inside a (Whonix) VM, just install the apt cache inside the VM and point to a localhost apt cache.

Prepend REPO_PROXY=http://127.0.0.1:3142 before the build command.

Replace the IP 127.0.0.1 with the IP address of your host. For security reasons, this should only be done over LAN and not over the internet.

sudo REPO_PROXY=http://127.0.0.1:3142 ./derivative-maker ...

VM Settings

Various VM settings can optionally be changed.

tested: Virtual RAM, virtual video RAM, hard drive size

untested: filesystem, hostname, password This is only relevant for VM builds.

Several examples are below. Values can be changed to suit user preferences.

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

--vmram 128

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

--vram 128

grml-debootstrap's --vmsize option.

--vmsize 200G

grml-debootstrap's --filesystem option.

--filesystem ext4

grml-debootstrap's --hostname option.

--hostname host

grml-debootstrap's --password option.

--os-password changeme

grml-debootstrap's --debopt option.

--debopt "--verbose"

Build Variables Changes

It is possible to add build configuration files snippets which can change build variables.

Build Configuration Folders:

You can drop configuration file either in:

1. buildconfig.d or in
2. /etc/buildconfig-dist.d
3. ../buildconfig.d folder.

Files should have the file extension .conf.

Method 2. is recommended for users.

1. Contains examples. It is more difficult to use. Rather use the following.
2. sudo mkdir --parents /etc/buildconfig-dist.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 is easier to use, since you don't have to git commit your build config files.

Below is an example how to use method 2.

sudo mkdir /etc/buildconfig-dist.d

Open file /etc/buildconfig-dist.d/50_user.conf in an editor with root rights.

Select your platform.

Non-Qubes-Whonix^™

See Open File with Root Rights for detailed instructions on why to use sudoedit for better security and how to use it.

Note: Mousepad (or the chosen text editor) must be closed before running the sudoedit command.

sudoedit /etc/buildconfig-dist.d/50_user.conf

Qubes-Whonix^™

NOTES:

• When using Qubes-Whonix, this needs to be done inside the Template.

sudoedit /etc/buildconfig-dist.d/50_user.conf

• After applying this change, shutdown the Template.
• All App Qubes based on the Template need to be restarted if they were already running.
• This is a general procedure required for Qubes and unspecific to Qubes-Whonix^™.

Others and Alternatives

• This is just an example. Other tools could achieve the same goal.
• If this example does not work for you or if you are not using Whonix, please refer to this link.

sudoedit /etc/buildconfig-dist.d/50_user.conf

Add. (Replace it with whatever build configuration variable you wish to set.)

Example 1.

export DERIVATIVE_APT_REPOSITORY_OPTS='--enable --repository stable'

Example 2.

export tbb_version=13.0.1

Save.

Done.

Build Variables

build results binary folder (derivative-binary) | binary_build_folder_dist | default: $HOMEVAR/derivative-binary

See #Build Variables Changes on how to set build variables.

Skip Steps

Advanced users can opt-in to skip certain build steps and/or Debian maintenance scripts (postinst, preinst, ...).

Skip Sanity Tests

Useful to speed up the build.

--sanity-tests false

Skipping Build Steps

export SKIP_SCRIPTS+=" 1300_create-raw-image "

Skipping Chroot and/or Postinst Scripts

export SKIP_SCRIPTS+=" dist-base-files.postinst "

Look at the file names and add them. export SKIP_SCRIPTS+=" another_file_name ". Do not forget empty spaces before and after ".

Source Code Changes

If changes were made to the derivative-maker source code folder, it is the easiest to use the following build parameter.

Notes:

• This is only required if changes were made to the derivative-maker source folder.
• This is not required if only a customized build configuration was added to the /etc/buildconfig-dist.d folder.

--allow-uncommitted true

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

--allow-untagged true

Otherwise, changes must be committed to git first, before creating a git tag.

Footnotes

Whonix The most watertight privacy operating system in the world.

Dark mode

Follow us on social media

Supported by Power Up Privacy

Whonix is proudly supported until 2025 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint 2012- 2025 ENCRYPTED SUPPORT LLC

Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 13 year success story and maybe DONATE!