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
## eth1
#### 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.


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
[Imprint] [Privacy Policy] [Cookie Policy] [Terms of Use] [E-Sign Consent] [DMCA] [Investors] [Priority Support] [Professional Support]