Whonix Documentation Introduction

From Whonix
Jump to navigation Jump to search

Introduction, User Expectations, Footnotes and References


Info Anonymity is not a program, setup, or final destination -- it is actually a continual process, influenced by new knowledge that is constantly gathered. [1]

Using Whonix with its default settings provides more security than Tor alone. Anonymity is a complex problem and there is no easy solution to the many complicated challenges that all users face. The more you know, the safer and more anonymous you can be. Whonix provides extensive documentation for those interested in learning more.

The goal of this documentation is to describe The Whonix Anonymous Operating System in an easy-to-understand and reasonably thorough manner. It is hoped readers will be exposed to a range of new and improved concepts/applications regarding anonymity and security on the Internet.

Note that all the applications included in Whonix are not fully documented. Usually an overview is provided, with further details on Whonix-specific configurations that might be necessary. In general, use the documentation as a reference guide for only those features you intend to use. For instance, if a user is interested in I2P over Tor, the introductory section on Other Anonymizing Networks should be read first, followed by the I2P chapter.

Wiki is the Primary Source of Information vs Forums[edit]

The goal of the wiki is to provide an up-to-date source of information. Should that not be possible, at least appropriate notices will be posted on top of the wiki page. In no case users are expected to read long forum threads, find instructions in forum posts on how to perform actions such as installing applications. This is because posts are seldom edited / kept up-to-date due forums being a different medium of information sharing than a wiki. Users are advised to view the wiki as the primary source of information.

The forums are used to ask for clarifications in case wiki instructions are unclear. The goal of forum discussions should be, if possible, on topic and appropriate, eventually an improved wiki page on that topic. Forum posts will likely and inevitable be outdated over time. It's better to check if the related wiki page has been updated meanwhile.

The wiki should always provide better instructions because collaborative editing of the wiki should result in higher quality documentation. Anyone can contribute. Improve the Documentation / Edit the Whonix Wiki.

User Expectations - What Documentation Is and What It Is Not[edit]

The documentation should be regarded as a showcase. It demonstrates what is possible, at least to a certain extent and with some recent developments. There is no attempt, nor is it feasible, to replace upstream documentation.

Documentation should not be perceived as an offer for all-inclusive technical support. Expectations of instant updates or continuous support are unrealistic.

There is no automated testing of instructions in documentation with quick fixes if necessary.

For instance, an author, while exploring how to set up DNSSEC and showcase unbound, dnssec-trigger, created a wiki page on DNS Securityarchive.org. The wiki initially serves as a personal notepad, but is later rewritten for the public's benefit. However, developers are not equipped to debug every possible issue in all conceivable scenarios.

Writing that wiki page did not transform the author into an expert on, or a developer of, the unbound DNS resolver software. Far from it.

Therefore, in case of issues (such as, theoretically, unbound causing a crash dump), the user is kindly asked to apply the Self Support First Policy and Generic Bug Reproduction.

Whonix Footnotes and References[edit]

Small text and footnotes like 1 are not that crucial. They contain clarifications, information sources, extra notes for people with higher security needs, additional details to dispel doubts (in the case of controversial issues), proof of something, references, links, and so on. Generally speaking, it is unnecessary to read all of the footnote links (particularly for beginners), but it is encouraged.

For further clarification, footnotes are typically used in the following circumstances:

  • Developer notepad: Sometimes links are added when references such as related source code are difficult to find (on search engines or otherwise).
  • Supporting evidence: Footnotes often provide additional references to support statements in the main documentation, particularly if factual statements are not obvious. This preempts possible future questions from the Whonix population and provides greater clarification at the outset.
  • Comments for auditors: In various sections footnotes are added to answer potential auditor questions around specific Whonix recommendations, chosen security configurations, why alternatives were not implemented, and so on.
  • Reducing duplication: To avoid duplicate tickets and discussions, footnotes often link to existing (usability) issues, as well as identical or related discussions to raise the reader's awareness.
  • Reducing confusion: Footnotes will sometimes link to additional information sources in an effort to reduce user confusion. For example, a common use case is when a major Whonix configuration has changed; legacy users might be confused why a change was implemented if this issue was not referenced. In general this reduces the likelihood of support requests.
  • Troubleshooting: Most software is expected to be fully functional with available instructions. However, in corner cases footnotes can provide possible troubleshooting tips and known workarounds.
  • Advanced users: To be more user-friendly, documentation is generally focused on the needs of "everyday" users who do not require specialist configurations or functionality. However, footnotes sometimes provide links or instructions for advanced users to undertake more complicated activities. Footnoting in this case reduces potential confusion for the larger Whonix population.
  • Other non-essential information: For simplicity, footnotes sometimes contain non-essential links, quotes, research articles and similar material for interested readers.

To remove all doubt, novice or intermediate users can generally ignore footnotes unless experiencing difficulties with the particular software, activity or configuration in question. Footnotes are more valuable for those exploring topics in further detail, undertaking advanced configurations, performing development, or seeking answers to specific questions.

Third Party Documentation[edit]

As a general issue in the Linux distributions ecosystem, meaning an issue unspecific to Whonix, for many users it will be difficult to take advantage of documentation for other Linux distributions. It might even be confusing. The documentation might be for a different Linux distribution or generic, meaning for not specific Linux distribution.

Some steps suggested in third party documentation might be unnecessary as these are pre-configured for the user already by Whonix or Debian, which Whonix is based on.

That is not to discourage the user from reading third party documentation as even suggestion chapter Based on Debian, Support and Self Support First Policy.

As far as security related questions are concerned, support request policy applies.

See also:

Recommended Reading[edit]

The documentation is lengthy, so newcomers to the Whonix platform or those with limited time should first read these sections:

If users have more time available, it is suggested to read the Documentation widely, particularly the Basic Security Guide, Advanced Security Guide, and Computer Security Education sections.

Final Warning[edit]

The Whonix design is intended to offer a technological means to stay anonymous on the Internet. However, it should be emphasized that staying anonymous is not simply a technological problem – there is no tool, including Whonix and Tor, that magically provides Internet anonymity. It is necessary to change a host of behaviors as well.

It is certainly helpful to have a deep, technical understanding of Internet architecture, cryptologyarchive.org, traffic analysisarchive.org techniques, and the applications that are in use; mainly by knowing what not to do. However, users with basic knowledge who proceed cautiously (using common sense) are likely to protect themselves adequately in most cases.


Whonix Introduction wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix Introduction wiki page Copyright (C) 2012 - 2021 ENCRYPTED SUPPORT LP <adrelanos@whonix.org>

This program comes with ABSOLUTELY NO WARRANTY; for details see the wiki source code. This is free software, and you are welcome to redistribute it under certain conditions; see the wiki source code for details.


  1. This aligns with the axiom that Kicksecure logo Security is a process, not a product. The Web Archive Onion Version

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