Whonix Networking Implementation - Developer Documentation - Feedback Wanted!

The diff between Debian buster and Whonix related to changes to network configuration.

Whonix Networking Implementation - Developer Documentation was just now updated.

On above page you can find all changes that Whonix applies related to networking:

  • Location of the files on the disk in installed Whonix.
  • The location of the file in Whonix source code on the disk.
  • A link to the web version of the file on github.
  • A comment if
    • not installed by default
    • gateway or workstation only
    • Non-Qubes-Whonix or Qubes-Whonix only
  • And most importantly, a summary of what that file is supposed to do.

That might give you a pretty good overview how Whonix implements its networking. By following the links to the actual files and reviewing them, you might gather enough information so you could create your own Whonix manually. That may not be necessary but it can never hurt to have more people who understand Whonix well since through this review process, issues might be revealed and fixed.


Feedback Wanted!

Does this wiki page make it easier to understand how networking is implemented in Whonix?

Anything about the formatting that could be improved? Such as should each file get its own chapter or is that too much?

If the first category networking which got documented here is helpful, also other categories can be documented. And of course, it would also be trivial to have a wiki page “all-in-one” which documents all changes by Whonix to Debian.


Qubes-Whonix (package qubes-whonix) is not yet fully documented on that wiki page but the there are extensive comments in the source code.


This time this will be easier to maintain and keep updated.

There were previous attempts to document how Whonix is implemented. But since source code changes over time (packages are reorganized, source files move around), it was too much effort to keep the design documentation in sync, so that didn’t happen. Also it was too much. Whonix does not only reconfigure the network but also enhances other parts such as security and usability. These pages were too long and therefore not convenient enough. Therefore not too many people were reading it.


The way this works is having a simple markup as comments.

For example /etc/network/interfaces.d/30_non-qubes-whonix contains:

#### meta start
#### project Whonix
#### category networking
#### non_qubes_whonix_only yes
#### gateway_only yes
#### description
## network interfaces configuration eth0 (external network interface) and eth1 (internal network interface)
##
## static network configuration
##
## eth0
#address 10.0.2.15
#netmask 255.255.255.0
#gateway 10.0.2.2
##
## eth1
#address 10.152.152.10
#netmask 255.255.192.0
#### meta end

These comments are then processed by packaging-helper-script function pkg_descr_creator and pkg_descr_merger which autogenerates a wiki source code that can simply be copied/pasted to the wiki.

The field #### category allows to reuse the same documentation for different categories. For example is /etc/sysctl.d/tcp_hardening.conf network configuration or security configuration? It’s both. Therefore it can be mentioned on a wiki page which documents Whonix networking implementation as well as on another wiki page which documents any security related changes by Whonix.

2 Likes

Possible enhancements:

  • skip those packages / files which are not installed by default (such as anon-gw-dhcp-conf) (but keep on separate all-in-one wiki page)

  • Don’t mix documentation for gateway and workstation. There could be two or three pages.
    • gateway networking only
    • workstation networking only
    • (gateway and workstation networking on same page - can be any combination)

  • Skip package description text?

But this needs some feedback.

If we concentrate on one subject (“category”) only such as networking and maybe on one VM only such as gateway, it is not such a massive amount of related files / changes done by Whonix in that category. It just be reviewable. Just need to get the presentation done right.

1 Like

I’d say it is easier to keep all network related packages in one place, but it’s helpful to declare which ones aren;t defaults.

Have them on the same page filed under their namesake headings.

How else would you describe it though? Descriptions make a good starting point for knowing what’s what then you can elaborate more on the ones where you feel it is appropiate.

1 Like

Maybe having the descriptions for the Gateway and Workstation networking, for example, and then in a small paragraph after have a couple useful notes about how it would differ from a fresh Buster networking scenario?
Since networks can be managed by many tools (ifupdown, systemd-networkd, dhcp, or various guis like network-manager) just focus on what we use in Whonix (ifupdown) and say how if you make this in your own operating system, the file of note would be /etc/network/interfaces and (if you want internal as well) /etc/network/interfaces.d/
In the description paragraph you can say all the packages that are included to make networking work. Then like HulaHoop says, just specify which are only in Whonix.
That’s just one example. I would say that when I was learning, I found the wiki pages to be invaluable so do not deviate too much from that kind of format because in my opinion it is very well done and well-explained

= gateway =
== anon-gw-anonymizer-config  ==
== security-misc ==
== uwt ==
= workstation =
== anon-ws-disable-stacked-tor ==
== security-misc ==
== uwt ==

Like this?

That would lead to some duplication. For example security-misc and uwt are installed on both, gateway and workstation.

Would be better anyhow?

By package description text I mean for example this:

## anon-ws-disable-stacked-tor
### Prevents Tor over Tor in Anonymity Distribution Workstations
Supposed to be installed on Workstations, which prevents installing the real Tor package from upstream (ex: Debian, The Tor Project) APT repositories. Its purpose is to prevent, running Tor over Tor. 
...

It would still be described on a file by file basis…

### /debian/anon-ws-disable-stacked-tor.displace
...
### /debian/anon-ws-disable-stacked-tor.postinst
...

…but the text from debian/control description could be left out.

This is already the case.
For example Whonix Networking Implementation Documentation lists only what Whonix does.

But I see an issue. Debian installer and or various desktop environments (gnome etc.) might be using systemd-networkd and/or network manager (GUI) to set up networking. This might differ depending on Debian flavors and/or Debian installer options.

The Debian base config assumed in this developer documentation is a our minimal (grml-)debootstrap created Debian image. These don’t come with any network configuration at all. Using our minimal base image would have no networking configuration to begin with.

Someone who wanted to build Whonix manually and from scratch would have to start with a minimal base Debian image. Not with for example a Debian XFCE installed with Debian installer DVD since that already comes with functional/different network configuration.

Whonix is ifupdown with static network only by default and no dhcp.

I see. Well, the contents need to be auto generated. Otherwise they’ll fall out of date quickly. Time has proven these are unmaintainable if created manually.

Better to have a third section for packages shared by both, to avoid duplication and for brevity.

That is a very important point that would make sense under a baseline title heading explaining the starting point for all packages. I know this is included in te dev docs in git but on the wiki makes it more visible - which is the point of this exercise.

1 Like

Right; to add on what HulaHoop said, you could start with saying something like," we start with a basic Debian image which does not have a default network setup. Many different network setups can be used in Debian, and in Whonix we use the ifupdown tools.Here is how the networking works in Gateway: and in Workstation:" Another thing I notice is, even if a specific flavor comes with default networking packages, simply uninstalling them and then setting up ifupdown is no problem. Like a network manager install can be converted to ifupdown with a couple simple file modifications and removing the appropriate packages. Same for Wicd also in the case of LXDE.

And @Patrick, I understand what you mean about the auto generated contents. Keeping things up to date is important, and doing it manually is unfeasible I agree

1 Like

This was implemented.

  • Now separated by
    • Whonix-Gateway
    • Whonix-Workstation
    • Shared by Whonix-Gateway and Whonix-Workstation
  • Base image is now also mentioned.
1 Like

Updated.