[edit]

Authoring Notes:

Start with a general description below each headline. Be as general as possible and try to avoid using terms like 'Tor'.
Next, carefully describe the Whonix ™ Example Implementation. Show exactly how Whonix ™ implements the goals stated above.
See Dev/Documentation_Guidelines for the preferred formatting style and grammatical considerations.

Last updated git[edit]

4a70f4868d683a08b73c6236b36684220d704d97

Get Build Dependencies[edit]

Install a tool to create Virtual Machine images (such as grml-debootstrap) and tools for mouting and apply other useful build configurations.

Whonix ™-Example-Implementation:

Configure APT and dpkg, to ask no questions while installing the build dependencies.
Update the build machine's operating system.
Configure apt-cacher-ng to speed up downloading when building multiple times (for debugging).
Install tools used in the build process.
- https://github.com/Whonix/Whonix/blob/master/build-steps.d/15_prepare-build-machine ^[archive]

Get Base Operating System[edit]

Use a tool to create a Virtual Machine base installation, which contains a secure operating system and which is bootable.

Whonix ™-Example-Implementation:

Used Debian for reasons explained on the Dev/Operating System design page.
Whonix ™ uses grml-debootstrap to build .img Virtual Machine images. The .img images are still virtualizer agnostic, can be run in a variety of virtualizers such as Qemu or Qubes OS. They can (and will in Whonix ™-Example-Implementation case) be converted to other formats to support other virtualizers (such as the .img format, which VirtualBox uses in case of Whonix ™).

Other Implementations:

Old Whonix ™ versions up to 0.3.0 used Ubuntu as base operating system.
Old Whonix ™ versions up to 0.3.0 used Preseed ^[archive], installed the operating system from DVD inside a Virtual Machine.
This step can also be done manually, i.e. the user could be told to manually install some operating system.
Whonix ™ with Physical Isolation.

Backup Base Operating System[edit]

Make a backup of that image. This is not strictly required, but you will want to modify that image often and want to start fresh often.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/build-steps.d/25_backup-img ^[archive]

Mount Image[edit]

Mount the image, so files can be copied into it.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/mount-img ^[archive]

Copy Files Into Image[edit]

Copy configuration files and chroot scripts into the Virtual Machine image to transform it into a Gateway or Workstation.

Whonix ™-Example-Implementation:

Copying script: https://github.com/Whonix/Whonix/blob/master/build-steps.d/30_copy-into-img ^[archive]
Verification script: https://github.com/Whonix/Whonix/blob/master/build-steps.d/32_verify_copied_files ^[archive]
All files from whonix_gateway will get copied into Whonix-Gateway ™.
All files from whonix_workstation will get copied into Whonix-Workstation ™.
All files from whonix_shared will get copied into Whonix-Gateway ™ and Whonix-Workstation ™.

Chrooting[edit]

As preparation for the next step, there must be a method to chroot the mounted image.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/chroot-img ^[archive]

Running Scripts inside Chroot[edit]

The base operating system has to be modified. Some scripts need to be executed inside the virtual machines. This is called running chroot scripts.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/build-steps.d/35_run-chroot-scripts-img ^[archive]

Unchrooting[edit]

The process of chrooting must be undone after the chroot scripts were executed.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/unchroot-img ^[archive]

Unmounting[edit]

The image must be unmounted after the copying files into it or after chrooting, running chroot scripts and unchrooting.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/unmount-img ^[archive]

Creating a Virtual Machine package[edit]

It is useful to deploy the Virtual Machine images through a package format, which makes it easy to import them for users.

Whonix ™-Example-Implementation:

Uses VirtualBox.
VirtualBox does not support .img images, only .vdi (and others).
- Therefore the .img image has to be converted to .vdi.
  - https://github.com/Whonix/Whonix/blob/master/build-steps.d/40_convert-img-to-vdi ^[archive]
- The next step is to create a virtual machine description file.
  - After creating it, the Virtual Machine could be started.
  - https://github.com/Whonix/Whonix/blob/master/build-steps.d/45_create-vbox-vm ^[archive]
- An easy way to deploy Virtual Machine images is through the Open Virtualization Format ^[archive] format (.ova images)
  - https://github.com/Whonix/Whonix/blob/master/build-steps.d/50_export-vbox-vm ^[archive]

Files[edit]

Essential[edit]

Username, FQDN, hostname[edit]

Hosts file. Use non-identifying values for FQDN and hostname, because some applications may leak it. (Mixmaster is known to leak it.) Set FQDN to "host.localdomain" and set hostname to "host". It is best when they are shared among anonymity focused distributions. ^[archive]

It is recommended to work as non-privileged user and not using one will get into usability trouble (desktop environments don't like running as root). For usability, consistency, defence in depth, name it "user". It is better to say non-saying operating system user account names and ideally share them among anonymity focused distributions since the user could accidentally leak it (ex: ssh).

Whonix ™-Example-Implementation:

Set FQDN to "host.localdomain" and set hostname to "host": https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/hosts ^[archive]
adding user account "user": https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/30_adduser_user ^[archive]
configuring hostname "host": https://github.com/Whonix/Whonix/blob/master/build-steps.d/20_create-debian-img ^[archive]
Even though grml-debootstrap already creates /etc/hostname with content "host", it is useful for physical isolation users, who set up the wrong host while installing: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/hostname ^[archive]
More information about the shared user name "user": Protocol-Leak-Protection and Fingerprinting-Protection

Operating System Updates[edit]

Configure the package manager.

Configure software repositories.

Do not use the default automatic updates mechanism and use higher timeouts. It is better to disable the operating system's default automatic update mechanism, because times of automatic run are too predictable. The network fingerprint (not web fingerprint) could help an ISP guessing, that there is a network hidden operating system.

Notify about operating system updates in a safe way.

Misc settings, higher timeouts, more retries when package download or DNS resolution fails. This is useful because anonymity networks are slow and otherwise updating would occasionally fail due to network problems.

Must have a secure operating system updater (package manager), i.e. must not fall through the TUF Threat Model ^[archive] (w ^[archive]). Additionally, downloading should go thought an anonymity network, with changing exit relays. This makes an adversary less likely to interfere with the update process, because updates go through different ISPs, which makes it much more difficult to mount a man-in-the-middle attack over an extended amount of time.

The package manager shouldn't confuse the user with questions to keep the locally installed configuration file or to install the new version from the upstream package contributor.

Whonix ™-Example-Implementation:

Gateway and Workstation updates go through Tor. (Due to Firewall, Network Configuration and Stream Isolation Wrapper, details in Design-Shared/Gateway/Workstation.)
Whonix ™ uses Debian ftp.us.debian.org and security.debian.org repositories.
- https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/apt/sources.list ^[archive]
Disable the operating system's default automatic update mechanism.
- https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/apt/apt.conf.d/20whonix-noperiodic ^[archive]
- https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/kde/share/config/apper ^[archive]
Higher timeouts, more retries.
- https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/apt/apt.conf.d/90whonix-timeout ^[archive]
For the safe update notification, see check mechanism (whonixcheck) below.
Disable Apper (packagekit) automatic download of package lists (due to upstream bugs https://bugs.freedesktop.org/show_bug.cgi?id=62575 ^[archive] and https://bugs.freedesktop.org/show_bug.cgi?id=62576 ^[archive])
- https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/kde/share/config/apper ^[archive]

TimeSync[edit]

Add a secure method with distributed trust to obtain date and time, because a clock which is drift, is bad for anonymity.

Whonix ™-Example-Implementation:

General Information

TimeSync
tails_htp configuration file: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/default/htpdate ^[archive]
When timesync is run by cron, it adds a random delay to prevent having a predictable network (not web) fingerprint. Essentially runs tails_htp every hour at a random time.

Start Hooks

tails_htp init script: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/init.d/htpdate ^[archive]
Using cron to start it every hour: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/cron.hourly/30_timesync ^[archive]
The file https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/timesync_hourly ^[archive] gets run by https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/cron.hourly/30_timesync ^[archive] cron every hour.
Auto start Boot Clock Randomization: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/etc/init.d/bootclockrandomization ^[archive]
Auto start timesync status notification after (auto) login Whonix-Gateway ™: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/profile.d/30_timesync.sh ^[archive]
Workstation specific
- Auto start timesync status notification after (auto) login Whonix-Workstation ™: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/home/user/.config/autostart/timesync.desktop ^[archive]

Install Hooks

Adding tails_htp daemon user account and init script: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_htp ^[archive]
Install Boot Clock Randomization init script: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_bootclockrandomization ^[archive]
Install Time Sanity Check init script: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_timesanitycheck ^[archive]

Supporting Files

/etc/sudoers.d/
- Allow Network Time Synchronization (tails htpdate) without password: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/sudoers.d/htpdate ^[archive]
- Allow "sudo service bootclockrandomization status" without a password: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/sudoers.d/bootclockrandomization ^[archive]
- Allow "sudo service timesanitycheck status" and "restart" without a password: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/sudoers.d/timesanitycheck ^[archive]
Delay console output a bit when run after login. This ensures /etc/motd is shown earlier and introduces the status notifications gracefully. Better look and feel: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/delay ^[archive]
Icon. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/icons/timesync.ico ^[archive]

Script

htpdate (tails_htp) itself: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/sbin/htpdate ^[archive]
Combined graphical and text user interface "timesync" main script. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/timesync ^[archive]
Combined graphical and text user interface "timesync" scripts folder. https://github.com/Whonix/Whonix/tree/master/whonix_shared/usr/bin/timesync-scripts ^[archive] and some from https://github.com/Whonix/Whonix/tree/master/whonix_shared/usr/bin/whonixcheck-scripts ^[archive] (which are sourced becomes clear by reading the main https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/timesync ^[archive] script)

Banned Packages[edit]

Some packages aren't suited for an anonymous operating system. Reasons are privacy issues or messing with network settings. Ensure, that those get removed, if they got installed by the virtual machine image creation tool. This shouldn't be the case because of the hand selected package selection. Just in case upstream dependencies change or custom packages get added by users who build from source code. Ensure that those packages won't get installed by accident. Since it is documented, advanced users can overwrite these recommendations if they know better.

Whonix ™-Example-Implementation:

Stream Isolation Wrapper[edit]

Stream isolate different applications to prevent identity correlation through circuit sharing. To my knowledge, only the anonymizer Tor supports this feature.

Whonix ™-Example-Implementation:

See Stream Isolation.
uwt ^[archive] is a wrapper arround torsocks: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/uwt ^[archive]
uwt / timeprivacy master wrapper: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/uwtwrapper ^[archive]
uwt configuration folder (.d-style): https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/systemcheck.d/ ^[archive]
Application wrapper symlinks to the master wrapper (If the application is not installed, the wrapper doesn't do anything. So having one more installed than necessary, doesn't matter.): https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_uwt ^[archive]

Extra[edit]

Time Privacy[edit]

Applications such as gpg and git embed time stamps in their output. For improved privacy it may make sense to fake this data. The user should enable it oneself, otherwise it could be very surprising and may not do what the user wants. Experimental design and implementation. Disabled by default.

Whonix ™-Example-Implementation:

Disabled by default.
timeprivacy script: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/timeprivacy ^[archive]
uwt / timeprivacy master wrapper: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/uwtwrapper ^[archive]
Time Privacy configuration folder (.d-style): https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/systemcheck.d/ ^[archive]
Application wrapper symlinks to the master wrapper (If the application is not installed, the wrapper doesn't do anything. So having one more installed than necessary, doesn't matter.): https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_uwt ^[archive]

hdd configuration / swap / Disk uuid / dbus machine-id[edit]

Since the virtual machine creation tool won't create a swap partition (which is actually good because it simplifies the setup) but the system could run out of memory, add a swap file. The is optional depending on the operating system and available RAM. Configure swap to be used as little as possible to improve speed.

Whonix ™-Example-Implementation:

Swap file creation. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_create_swap_file ^[archive]
Activating swap in fstab. https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/fstab ^[archive]
Only swap to disk if really necessary. https://github.com/Whonix/Whonix/blob/master/whonix_gateway/etc/sysctl.d/whonix.conf ^[archive]
Less Important Identifies (Defined as per Protocol-Leak-Protection and Fingerprinting-Protection.)
- Share Disk UUIDs.
  - In /etc/fstab. https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/fstab ^[archive]
  - Also share uuid for swap file. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_create-swap-file ^[archive]
- Chang partition uuid. "tune2fs /dev/mapper/loop0p1 -U 26ada0c0-1165-4098-884d-aafd2220c2c6" https://github.com/Whonix/Whonix/blob/master/build-steps.d/35_run-chroot-scripts-img ^[archive]
- Change disk uuid: https://github.com/Whonix/Whonix/blob/master/build-steps.d/45_create-vbox-vm ^[archive]
- Share dbus machine-id: https://github.com/Whonix/Whonix/blob/master/whonix_shared/var/lib/dbus/machine-id ^[archive]

Base Files[edit]

Perhaps only required for Debian and derivatives. Whonix ™ was asked to replace the default dpkg origin symlink.

Whonix ™-Example-Implementation:

Usability[edit]

check mechanism[edit]

Recommended, not strictly required.

Whonix ™-Example-Implementation:

General Information

systemcheck
Whonixcheck essentially runs whonixcheck at least once very day.
Whonixcheck, although run on each boot and every hour by cron, itself is rate limited and stops running checks, if it was run less than one day ago. The user can always manually perform all whonixcheck checks.

Start Hooks

The file https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/whonixcheck_hourly ^[archive] gets run by cron.hourly https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/cron.hourly/40_whonixcheck ^[archive]
Allowing messages to tty (setting "mesg y") while an application was started in background (by cron): https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/profile.d/20_mesg.sh ^[archive]
Whonix-Gateway ™ specific
- https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/profile.d/40_whonixcheck.sh ^[archive] gets run on every (automatic) login.
Whonix-Workstation ™ specific
- Since Whonix-Workstation ™ is graphical, it is better to use the event by the desktop environment than using profile.d for autostart. https://github.com/Whonix/Whonix/blob/master/whonix_workstation/home/user/.config/autostart/whonixcheck.desktop ^[archive]

Supporting Files

Allows running apt update as user (non-root): https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/sudoers.d/apt-get-update ^[archive]
Allow wall (with -nobanner option) without password: https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/sudoers.d/wall ^[archive]
Version file to let the whonixcheck find out which version of Whonix ™ is locally installed. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/version ^[archive]
apt-get-update (which has an sudoers exception) runs apt update. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/apt-get-update ^[archive]
When automatically run by autostart or cron, whonixcheck adds a random delay (to prevent having a predictable network (not web) fingerprint.
gpg key of Whonix ™ contributor adrelanos to verify Whonix ™ News. https://github.com/Whonix/Whonix/tree/master/whonix_shared/usr/local/share/whonix/gpg-pubkeys ^[archive]
Icon. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/icons/whonix.ico ^[archive]
xhost exception. https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/X0.hosts ^[archive]

Script

The whonixcheck main script. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/whonixcheck ^[archive]
The folder with the various checks. https://github.com/Whonix/Whonix/tree/master/whonix_shared/usr/bin/whonixcheck-scripts ^[archive]

Desktop Environment[edit]

Optional.

It is useful to have a desktop preconfigured to make it as easy as possible for users who use Linux for the first time.

Whonix ™-Example-Implementation:

shared
gateway specific
- Changing default skin and wallpaper: https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/share/whonix/kde/share/apps/plasma-desktop/init/00-defaultLayout.js ^[archive]
- Start menu favorites: https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/share/whonix/kde/share/config/kickoffrc ^[archive]
- Desktop Icons: TODO
- Creating desktop icons: https://github.com/Whonix/Whonix/blob/master/whonix_gateway/usr/local/share/whonix/chroot-scripts/70_desktopicons ^[archive]
workstation specific
- Changing default skin and wallpaper: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/kde/share/apps/plasma-desktop/init/00-defaultLayout.js ^[archive]
- Start menu favorites: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/kde/share/config/kickoffrc ^[archive]
- Desktop Icons: https://github.com/Whonix/Whonix/tree/master/whonix_workstation/usr/local/share/whonix/kde/share/applications ^[archive]
- Creating desktop icons: https://github.com/Whonix/Whonix/blob/master/whonix_workstation/usr/local/share/whonix/chroot-scripts/70_desktopicons ^[archive]

sudoers[edit]

Optional. For convenience. Only recommended for Virtual Machines.

Allow shutdown, reboot and poweroff without a password. Allow starting Tor Controller arm without password. (No effect on Workstation, since arm is only Gateway.) Allow mixmaster-update without password. (No effect on Gateway, since mixmaster is only installed on Gateway.)

Whonix ™-Example-Implementation:

Console Autologin[edit]

Optional. Only recommended for virtual machines.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/inittab ^[archive]

Console Default Password Hint[edit]

Optional.

The system will be shipped with a default password (which users are suggested to change in documentation). To prevent user frustration when not knowing the password it greatly reduced (from Whonix ™ experience) support requests if the default password is displayed right above the password prompt.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/issue ^[archive]

Console Welcome Message[edit]

Optional.

Contains general information about derivative, licensing, default passwords, how to open the help file.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/motd ^[archive]

Deactivate display power saving in Virtual Machines[edit]

Since it is confusing and not useful and not saving any energy. (Needs to be applied on host.)

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/etc/profile.d/20_disable_powersaving.sh ^[archive]

boot manager configuration[edit]

Optional. For higher boot resolution, it is required to run update-grub after changing grub configuration files.

Whonix ™-Example-Implementation:

update command not found[edit]

Optional.

Initially update the command not found database, to prevent showing "please run update-command-not-found" in case a non-existent command gets entered in console.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_update_command_not_found ^[archive]

Secure/SSL Command Line Downloader[edit]

Add a command line downloader, which enforces using https (SSL).

Whonix ™-Example-Implementation:

A simple curl wrapper. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/scurl ^[archive]
Documented under scurl - SSL command line downloader
The user starts scurl, the wrapper will run the curl uwt wrapper (/usr/bin/curl), which stream isolates and finally calls curl.

Slim Down[edit]

Optional. To safe space and to prevent (some) development related leaks, remove cache, temporary files, dhcp leases, package manager cache, logs, history.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/80_slimdown ^[archive]

Icons[edit]

Optional.

Some pretty icons for the start menu and the desktop for custom applications, which are only useful in a Gateway/Workstation design.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/tree/master/whonix_shared/usr/local/share/whonix/icons ^[archive]

Debugging[edit]

Sanity Checks[edit]

Recommended, not strictly required.

Some simple tests to check for example, if all files have been correctly copied into the image, if the package manager is fully functional, because some virtual machine creation tools build broken images. Package integrity checks.

Whonix ™-Example-Implementation:

Misc[edit]

Optional.

Whonix ™-Example-Implementation:

Chroot Script Skeleton, not strictly required, might just be useful to explain how to create chroot-scripts: https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_skeleton ^[archive]
Create a list of all files inside Whonix ™ source folder. https://github.com/Whonix/Whonix/blob/master/release/list_source_files ^[archive]
List of all files inside Whonix ™ source code with comments: https://github.com/Whonix/Whonix/blob/master/development/files_list ^[archive]
Commented list of files inside Whonix ™ source code that may require special treatment when creating a Whonix-Gateway ™/Workstation.deb (which is planned): https://github.com/Whonix/Whonix/blob/master/development/files_list_short ^[archive]

Variables[edit]

Recommended, not strictly required.

It is useful to configure the system, not to ask any questions which require user interaction such as when you plan to run the package manager from within chroot. This is because interaction is not useful when automating things.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/variables ^[archive]

Package Cache[edit]

Optional.

If the package manager is used inside chroot, it makes sense to run it though a cache, so debugging steps can be done faster.

Whonix ™-Example-Implementation:

apt.conf which can be used in case APT gets used inside chroot. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/apt.conf ^[archive]

What is /usr/local/share/whonix/apt.conf good for?

This apt.conf is only used inside chroot and currently only in effect for "./debug-steps/download-source -tg" and "./debug-steps/download-source -tw".

It points to http://10.152.152.11 ^[archive] :3142, which is expected to be a Whonix-Workstation ™ with apt-cacher-ng running. It is useful for running "apt install" and "apt source" inside chroot, because downloads are cached, which speeds up the build process when building several times in a row. (Debugging with only minor changes.)

In case you don't want to use it or to use another proxy, edit /home/user/Whonix/whonix_shared/usr/local/share/whonix/apt.conf (comment out with a # or change proxy settings). Don't forget "sudo ./build-steps.d/30_copy-into-img -tX" after modifying the file.

Script to run apt-cacher-ng through uwt for Stream Isolation. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/bin/apt-cacher-ng_uwt ^[archive]

Prevent daemons from starting inside chroot[edit]

Optional.

Only in case you want to install something inside chroot for debugging purposes. Otherwise they can lock the chroot folder and you won't be able to unchroot.

Whonix ™-Example-Implementation:

policy-rc.d blocks daemons from starting. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/policy-rc.d ^[archive]
policy-rc.d gets copied into chroot when chrooting. https://github.com/Whonix/Whonix/blob/master/help-steps/chroot-img ^[archive]
policy-rc.d gets deleted inside chroot when leaving chroot. https://github.com/Whonix/Whonix/blob/master/help-steps/unchroot-img ^[archive]

Indicate last chroot script[edit]

Not strictly required. A chroot script, which indicates that all went well.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/90_end ^[archive]

Lower priority while building[edit]

Optional. Not strictly required.

Using ionice and renice.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/pre ^[archive]

Enable debugging[edit]

Optional. Not strictly required.

When using bash, set -x to show each command that gets executed.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/help-steps/pre ^[archive]

Error handling[edit]

Optional. Not strictly required.

It is important to ensure that there are no error while copying files into the images or while running the chroot scripts because many steps are essential. Stop and loudly complain if any unexpected error occurs.

Whonix ™-Example-Implementation:

general trap: https://github.com/Whonix/Whonix/blob/master/help-steps/pre ^[archive]
using traps and exit 1 everywhere

Delete Virtual Machine files[edit]

Optional. Not strictly required.

So they can be re-created for debugging purposes.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/debug-steps/delete-vbox-vm ^[archive]

Interactive Chroot[edit]

Optional. Not strictly required.

After creating the base operating system image, after copying files into it or after applying the chroot scripts, it is useful to have a command, which allows to look around inside the image without having to boot the image. Adrelanos calls this Interactive Chroot.

Whonix ™-Example-Implementation:

https://github.com/Whonix/Whonix/blob/master/debug-steps/interactive-chroot-img ^[archive]

Licensing[edit]

Only required for builds, which will be redistributed in public.

Make a list of GPLed software.

Whonix ™-Example-Implementation:

Added damngpl ^[archive]. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/damngpl ^[archive]
Creating a list of GPLed software. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/chroot-scripts/70_sources ^[archive]
A script to download all GPLed software, which can be run inside the virtual machine or inside chroot. https://github.com/Whonix/Whonix/blob/master/whonix_shared/usr/local/share/whonix/whonix_download_sources ^[archive]
The source code needs a License file. https://github.com/Whonix/Whonix/blob/master/COPYING ^[archive]

Build Automation[edit]

Optional. Not strictly required.

Since many steps are required to build a Gateway or Workstation, it is useful to automate build creation.

Whonix ™-Example-Implementation:

Release Automation[edit]

Optional. Not strictly required.

Since many steps are required to redistribute a Gateway or Workstation, it is useful to automate releases.

Whonix ™-Example-Implementation:

Release maintenance folder: https://github.com/Whonix/Whonix/blob/master/release/README ^[archive]
sourceforge.net Download Readme: https://github.com/Whonix/Whonix/blob/master/release/README ^[archive]
Whonix ™ News File: https://github.com/Whonix/Whonix/blob/master/release/whonix_news ^[archive]
Script to automate gpg signing, verification (as sanity check) and upload sourceforge.net Download Readme: https://github.com/Whonix/Whonix/blob/master/release/upload_download_readme ^[archive]
Script to automate gpg signing, verification (as sanity check) and upload Whonix ™ News File: https://github.com/Whonix/Whonix/blob/master/release/upload_whonix_news ^[archive]
Building and uploading of Virtual Machine Images. Fully documented on Dev/Redistribution and https://github.com/Whonix/Whonix/blob/master/release/whonix_release ^[archive].

Other important things[edit]

The things on this (Design-Shared) page are supposed to be added to the Gateway and the Workstation.

To build a Gateway, also things from the Dev/Design-Gateway page have to be added.

To build a Workstation, also things from the Dev/Design-Workstation page have to be added.

Justify other design decisions, what the project doesn't and what it doesn't do. Have loads of documentation. Have a source code hacking guide and source code introduction.

Whonix ™-Example-Implementation:

Whonix ™ is Supported by Evolution Host DDoS Protected VPS. Stay private and get your VPS with Bitcoin or Monero.