What is the best Whonix workflow

I am wondering what could be the best/most appropriate workflow for a Whonix contributor?

The following are my findings and please educate me if I am wrong or there is a better approach. I will be really appreciate. Also, please feel free to share any useful additional information.

1.Fork https://github.com/Whonix/Whonix on Github

2.Clone your forked repository:
git clone git@github.com:YOUR_GITHUB_NAME/Whonix.git

3.Let’s say you would like to work on a Whonix component anon-connection-wizard:

fork anon-connection-wizard on Github: GitHub - Kicksecure/anon-connection-wizard

get anon-connection-wizard source code:

cd Whonix
git submodule update --init --recursive package/anon-connection-wizard

add your repository as origin:

cd package/anon-connection-wizard
git remote rename origin upstream
git remote add origin git@github.com:YOUR_GITHUB_NAME/Whonix.git

And that’s it. You can start your normal git flow now. :slight_smile:

4.Alternatively, if you would like to get all the source code of Whonix, simply:

cd Whonix
git submodule update --init --recursive

While nothing speaks against it, I don’t think it is usual practice / any useful to rename the origin which in this case is Whonix to anything else. Never saw this practice anywhere. Easier / β€œbetter” would be:

git remote add your-github-name git@github.com:YOUR_GITHUB_NAME/Whonix.git
git remote add irykoon git@github.com:YOUR_GITHUB_NAME/Whonix.git

It always makes sense to do that.

Fully optional, to speed up the process, add: --jobs=4

While this forum thread is not about building… Still… Useful from Whonix build documentation…


We suggest the following command to clone all of Whonix’s repositories.

cd; git clone --jobs=4 --recursive https://github.com/Whonix/Whonix

Once one has cloned all of Whonix’s source code, one could use the mygrep. Like changing the name of a variable or when renaming a file, it is useful to grep all the meaningful (that is excluding licenses and git folders etc) Whonix source files for references. That way any interaction between packages could be found.

Not sure if forking Whonix is convenient or if Whonix is doing something it could do better in order to make that process more standardized / simpler.


Preparation for future contribution guide use:

1 Like



1 Like

Due to the way Whonix does its packaging, files may be located very deep in different directories.

To easily view the structure of a package and found the desired file, I find tree very useful:

user@host:~/Whonix/packages/whonix-welcome-page$ tree
β”œβ”€β”€ changelog.upstream
β”œβ”€β”€ CONTRIBUTING.md
β”œβ”€β”€ COPYING
β”œβ”€β”€ debian
β”‚   β”œβ”€β”€ changelog
β”‚   β”œβ”€β”€ compat
β”‚   β”œβ”€β”€ control
β”‚   β”œβ”€β”€ copyright
β”‚   β”œβ”€β”€ rules
β”‚   β”œβ”€β”€ source
β”‚   β”‚   β”œβ”€β”€ format
β”‚   β”‚   └── lintian-overrides
β”‚   └── watch
β”œβ”€β”€ etc
β”‚   β”œβ”€β”€ profile.d
β”‚   β”‚   └── 20_whonix-welcome-page.sh
β”‚   └── X11
β”‚       └── Xsession.d
β”‚           β”œβ”€β”€ #20whonix-welcome-page#
β”‚           └── 20whonix-welcome-page
β”œβ”€β”€ GPLv3
β”œβ”€β”€ Makefile
β”œβ”€β”€ README.md
└── usr
    β”œβ”€β”€ lib
    β”‚   └── whonix-welcome-page
    β”‚       β”œβ”€β”€ #env_var.sh#
    β”‚       └── env_var.sh
    └── share
        └── homepage
            └── whonix-welcome-page
                β”œβ”€β”€ logo.png
                β”œβ”€β”€ stylesheet.css
                β”œβ”€β”€ #whonix.html#
                └── whonix.html

12 directories, 23 files

It can be installed by apt-get install tree.

Another trick that saves me tons of time navigating and jumping through the file in a Whonix package is to use projectile. It is an emacs package that will consider all the files in a directory as part of a project. When wanting to jump from one file to another, type C-c p f and hit TAB, one will see all the available files in a project (Whonix package).

1 Like

A lot files in the various packages I consider a burden. But necessary evil. Example excerpt:

β”œβ”€β”€ changelog.upstream
β”œβ”€β”€ CONTRIBUTING.md
β”œβ”€β”€ COPYING

These are repetitive among packages and make the package look complicated and deterrent than it really is.

The β€œreal” files (that is minus even the packaging overhead) are very few and look a lot simpler then.

1 Like

use dpkg -S file to figure out which package the file belongs.

1 Like
user@host:~$ grep "ProtectHome=" /lib/systemd/system/tor@default.service


β€œIf true, the directories /home, /root and /run/user are made inaccessible and empty for processes invoked by this unit”. This means systemd Tor can’t see anything in these file. Therefore, when testing a configuration file or a snowflake binary with Tor, don’t put it in these three directories.

1 Like

When writing a bash script, one may use a function call that is provided by another script. A uniformed looking comment will greatly help with the readability of code by telling the reader where this function call or variable is provided or set.

Whonix flavor comments are like this:

## provides: function_call_a # note it is not function_call_a()
source /path/to/another/script

(many lines away)

## sets: $variable_a

echo "$variable_a"

Therefore, whenever you have no clue where the function call or a variable is provided or set, simply search it within the same file.

This is taught by @Patrick : parse correct torrc files in tor_enabled_check() by irykoon Β· Pull Request #3 Β· Kicksecure/helper-scripts Β· GitHub

1 Like