Introduction[edit]

This assumes you are updating Whonix ™ debian packages while you are using Whonix ™.

Prerequisites[edit]

Might be a good idea to create a backup and/or clone before trying to update.

If you haven't done already, disable Whonix ™ APT repository. ^[1]

sudo repository-dist --disable

Upgrade from Debian packages.

sudo apt update && sudo apt --yes full-upgrade

Get the Source Code[edit]

Get the Signing Key[edit]

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

Get the Whonix ™ Signing Key.

Get the Source Code[edit]

FREE

Note: By proceeding, you acknowledge that you have read, understood and agreed to our Terms of Service and License Agreement.

Install git.

sudo apt update && sudo apt install git

Get the source code including git submodules. ^[2] ^[3]

Note: Replace 16.0.9.8-stable with the actual tag you want to build.

git clone --depth=1 --branch 16.0.9.8-stable --jobs=4 --recurse-submodules --shallow-submodules https://github.com/Whonix/derivative-maker.git

Change Directory[edit]

Get into the Whonix source code folder because later on package build commands using ./derivative-maker are expected to be run from the root of the source folder.

cd derivative-maker

OpenPGP Verify the Source Code[edit]

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

Change directly into source code folder.

cd derivative-maker

Git fetch. ^[4]

git fetch

Verify the chosen tag to build. Replace with tag you want to build.

git verify-tag 16.0.9.8-stable

The output should look similar to this.

object 1844108109a5f2f8bddcf2257b9f3675be5cfb22

type commit tag 16.0.9.8 tagger Patrick Schleizer <adrelanos@whonix.org> 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@whonix.org>" [ultimate]

Check the GPG signature timestamp makes sense. For example, if you previously saw a signature from 2020 and now see a signature from 2019, then this might be a targeted rollback (downgrade) or indefinite freeze attack. ^[5]

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 safely ignored.

By convention, git tags should point to signed git commits. ^[6] (forum discussion) It is advisable to verify the signature of the git commit as well (replace 16.0.9.8 with the actual git tag being verified).

git verify-commit 16.0.9.8-stable^{commit}

The 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@whonix.org>" [ultimate] Author: Patrick Schleizer <adrelanos@whonix.org> Date: Sun Dec 7 01:22:22 2014 +0000

.

Choose Version[edit]

Retrieve a list of available git tags.

git --no-pager tag

Use git checkout to select the preferred version to build.

Note: Replace 16.0.9.8-stable with the actual tag you want to build.

git checkout --recurse-submodules 16.0.9.8-stable

Check Git[edit]

Check if you really got the version you want.

git describe

The output should show.

{{{version}}}

Check if the source folder is pristine.

git status

The output should show nothing.

HEAD detached at {{{version}}}
nothing to commit, working tree clean

If it shows something else, do not continue.

Build Dependencies[edit]

Get all build dependencies.

sudo -E ./build-steps.d/1100_prepare-build-machine --internalrun --build --target root

Why --target root? This is correct, if you want to know why, see footnote. ^[7]

Create the Packages[edit]

If you're not debugging, create the packages with:

sudo -E ./build-steps.d/1200_create-debian-packages --build --internalrun --target root

If debugging, use the following command. Developers only! ^[8] Potentially insecure unless the untagged / uncommited changes are by you or by a trusted developer with a git gpg signature that you verified.

sudo -E ./build-steps.d/1200_create-debian-packages --build --allow-untagged true --allow-uncommitted true --internalrun --target root

Upgrade Whonix ™ Debian Packages[edit]

Upgrade Whonix ™ Debian Packages without contacting a Whonix ™ APT Repository, using your own locally created apt package repository.

For Whonix-Gateway ™.

sudo ./packages/kicksecure/developer-meta-files/debug-steps/locally-upgrade-whonix-debian-packages --build --target root --flavor whonix-gateway

^[9]

For Whonix-Workstation ™.

sudo ./packages/kicksecure/developer-meta-files/debug-steps/locally-upgrade-whonix-debian-packages --build --target root --flavor whonix-workstation

There will be a lot debug output. ^[10]

If everything went well, you will see ^[11] ^[12]

########################################################################
## INFO: Successfully configured (postinst script) Whonix-Workstation ™. #
########################################################################

The last few highlighted messages will be similar to:

+ true 'INFO: Skipping script, because --target root: /home/user/whonix_dot/Whonix/help-steps/unmount-img'
+ true 'INFO: End of: ./debug-steps/locally-upgrade-whonix-debian-packages | exit_code: 0 | error(s) detected: 0 | benchmark: 00:01:40'

In case any error is caught, the script will loudly complain by echoing in a red colored error message:

ERROR in ./debug-steps/locally-upgrade-whonix-debian-packages! Aborted.

Lets hope it works well. Please get in Contact should there be any issues. Leave feedback if you are using this, if it worked for you, which issues you may have had, so these instructions can be updated.

Cleanup[edit]

This step is optional.

Remove temporary files.

Warning: This command will run git clean -d --force --force in Whonix's main source code folder (~/derivative-maker) as well as in all subfolders of the Whonix packages folder (~/derivative-maker/packages). This means if any files were purposefully added to any of these folders that have not been committed to git, these will be deleted. ^[13]

./help-steps/cleanup-files

Footnotes[edit]

↑ Project-APT-Repository#Disable_Whonix ™_APT_Repository
↑
Optional git parameters:
- --depth=1: Used to speed up download.
- --branch 16.0.9.8-stable Usability. Used to speed up download.
- --jobs=4: Used to speed up download.
- --recurse-submodules --shallow-submodules: Usability.
Knowledgeable git users are free to drop any of these optional parameters.
↑ Alternatively, this can be achieved with the following commands in several steps. This is useful if network issues arise. git clone --depth=1 --branch 16.0.9.8-stable https://github.com/Whonix/derivative-maker.git cd derivative-maker git submodule update --init --recursive --progress --jobs=4
↑ Optional. [...]
↑
As defined by TUF: Attacks and Weaknesses:
- https://theupdateframework.io/security/
↑ Beginning from git tag 9.6 and above.
↑ Setting the --target parameter to root will result in installing fewer build dependencies. For example VirtualBox will not be installed. These are only required to build full images, but since we just want to create updated Whonix ™ Debian Packages, this is unnecessary. Not much harm done when forgetting to use --target root, because the user is free to remove any build dependencies later.
↑ Packages are possibly not matching the quality for redistributable testes or stable builds. This is because the package will potentially built from git master, which has no proper debian/changelog release version, and no signed git tag. There may be another package of that version in the repository that is different. Distinguishing these packages is hard and would cause confusion. Therefore this is considered unclean and only developers may do this for debugging purposes.
↑ Why use --target root"? Technical explanation: --target root in context of Whonix ™ source code means "do it on the system currently running, i.e. do it directly on the root folder "/[...]", don't do it inside "vm_image/[...]".
↑ Unless you log in as root and run export WHONIX_DEB_DEBUG=0.
↑ Or saying Whonix-Gateway ™ respectively
↑ It won't, if you have export WHONIX_DEB_DEBUG=0 set.
↑ https://github.com/Whonix/derivative-maker/blob/master/help-steps/cleanup-files

Whonix ™ The most watertight privacy operating system in the world.

Donate

FREE · PLUS · PREMIUM Support

Dark mode

At Whonix we believe in freedom and trust. That's why we fully support Open Source and Freedom Software.

Whonix ™ is supported by Evolution Host DDoS Protected VPS.

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole. By using this website, you acknowledge you have read, understood, and agree to be bound by these these agreements: Terms of Service , Privacy Policy , Cookie Policy , E-Sign Consent , DMCA , Imprint Whonix

ENCRYPTED SUPPORT LP, 2023

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 10 year success story and maybe DONATE!

[1] Project-APT-Repository#Disable_Whonix ™_APT_Repository

[2] Optional git parameters:
--depth=1: Used to speed up download.

--branch 16.0.9.8-stable Usability. Used to speed up download.

--jobs=4: Used to speed up download.

--recurse-submodules --shallow-submodules: Usability.
Knowledgeable git users are free to drop any of these optional parameters.

[3] --depth=1: Used to speed up download.

[4] --branch 16.0.9.8-stable Usability. Used to speed up download.

[5] --jobs=4: Used to speed up download.

[6] --recurse-submodules --shallow-submodules: Usability.

[3] Alternatively, this can be achieved with the following commands in several steps. This is useful if network issues arise. git clone --depth=1 --branch 16.0.9.8-stable https://github.com/Whonix/derivative-maker.git cd derivative-maker git submodule update --init --recursive --progress --jobs=4

[4] Optional. [...]

[5] As defined by TUF: Attacks and Weaknesses:
https://theupdateframework.io/security/

[10] ttps://theupdateframework.io/security/

[6] Beginning from git tag 9.6 and above.

[7] Setting the --target parameter to root will result in installing fewer build dependencies. For example VirtualBox will not be installed. These are only required to build full images, but since we just want to create updated Whonix ™ Debian Packages, this is unnecessary. Not much harm done when forgetting to use --target root, because the user is free to remove any build dependencies later.

[8] Packages are possibly not matching the quality for redistributable testes or stable builds. This is because the package will potentially built from git master, which has no proper debian/changelog release version, and no signed git tag. There may be another package of that version in the repository that is different. Distinguishing these packages is hard and would cause confusion. Therefore this is considered unclean and only developers may do this for debugging purposes.

[9] Why use --target root"? Technical explanation: --target root in context of Whonix ™ source code means "do it on the system currently running, i.e. do it directly on the root folder "/[...]", don't do it inside "vm_image/[...]".

[10] Unless you log in as root and run export WHONIX_DEB_DEBUG=0.

[11] Or saying Whonix-Gateway ™ respectively

[12] It won't, if you have export WHONIX_DEB_DEBUG=0 set.

[13] ttps://github.com/Whonix/derivative-maker/blob/master/help-steps/cleanup-files

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

Upgrading Whonix ™ Deb Packages from Source Code

Contents

Introduction[edit]

Prerequisites[edit]