Bug Report Recommendations[edit]

Non-critical Bugs[edit]

Users who find bugs are encouraged to report them to the Whonix ™ forums ^[archive]. To assist developers, please refer to the Reporting Guidelines further below when describing the problem.

Once notified issues are reproduced and confirmed, developers discuss the problem in order to find a suitable solution or workaround. All Whonix ™ source code fixes and related matters are implemented as quickly as possible and the finding is posted for the public benefit.

Security Vulnerabilities[edit]

Responsible disclosure ^[archive]: Users are kindly asked to privately report security bugs and describe the problem in detail - see the recommended Reporting Guidelines below for guidance. Lead Whonix ™ developer Patrick Schleizer should be contacted via OpenPGP encrypted mail before the information is published in public forums; see Contacting Whonix ™ developers. In this way, vulnerabilities can be patched without endangering the Whonix ™ population and the notifier can be credited with the finding(s) after the change reaches the stable repository (or next Whonix ™ release).

Reporting Guidelines[edit]

Before developers take time to answer concerns, the reporter should make a reasonable attempt to demonstrate it is an actual issue.

1. Make sure it is an actual bug report and not a support request.
2. Please use Search Engines and see Documentation First
3. Read Support.
4. Learn about Free Support Principle.
5. How to Ask Smart Questions ^[archive]
6. How to Report Bugs Effectively ^[archive]
7. XyProblem ^[archive]

Whonix ™, Qubes OS and most other software projects expect thorough reports to include: ^[1]

1. Whonix ™ version and platform.
2. Affected component(s) or functionality.
3. Steps to reproduce the behavior.
4. Expected behavior.
5. Actual behavior - including detailed console output.
6. Context - How has this issue affected you? What are you trying to accomplish? Providing context helps us come up with a solution that is most useful in the real world.
7. Relevant Documentation that was consulted.
8. Any related, non-duplicate issues (bugs) ^[archive].

The following example report would be considered wholly insufficient by Whonix ™ developers:

• Platform: Non-Qubes-Whonix 16.
• Affected functionality: Updating/upgrading the system.
• Steps to reproduce: Update the system in a terminal.
• Expected behavior: No error messages appear.
• Actual behavior: The message "70 signatures not checked due to missing keys" appears.
• Context: Curiosity.

Instead, further indicators are necessary in order to meet the threshold of a bug report.

Sample Bug Report[edit]

In many cases only developers, developers-alike and very technical users will be able to report an actual issue based upon console output. A sample, thorough bug report is given below. ^[2]

Table: Example Whonix ™ Bug Report

Indicator	Description
Whonix ™ version	All Whonix ™ 16 variants (Non-Qubes-Whonix ™ and Qubes-Whonix ™).
Affected component(s) or functionality	Whonix-Gateway ™ (sys-whonix) firewall.
Steps to reproduce the behavior	Enable the fail closed firewall mechanism in Whonix-Gateway ™ (sys-whonix). [3] Later on when a Template:Project name lowercase-firewall package upgrade becomes available, networking is no longer functional after installation.
Expected behavior	An upgrade of the Template:Project name lowercase-firewall package should not break networking.
Actual behavior	An upgrade of the Template:Project name lowercase-firewall package breaks networking.
Context	Running standard ("everyday") upgrade instructions.
Relevant Documentation that was consulted	See below.
Any related, non-duplicate issues (bugs) [archive]	None, but these resources are directly relevant: https://github.com/Whonix/ [archive]Template:Project name lowercase-firewall https://github.com/Whonix/ [archive]Template:Project name lowercase-firewall/blob/master/lib/systemd/system/networking.service.d/30_whonix-gw-firewall-fail-closed.conf

A detailed answer to a reported issue is more likely if:

1. Reporters exert more effort, provide detailed analysis, perform multiple web searches, and read the source code beforehand; or
2. The reporter is a Whonix ™ contributor or developer.

Generic Bug Reproduction[edit]

The following concepts and principles are related:

• Please use Search Engines and see Documentation First
• Unspecific
• Support
• Free Support Principle
• The User Co-developer Concept
• Mental Model

Issues unspecific to Whonix ™, in short, due to the organizational structure of Freedom Software, in most cases the only realistic way to resolve questions and issues is to reduce the complexity to as few components and to research upstream (origin) resources (documentation, forums, mailing lists) and to contact upstream if applicable. For that, it is highly useful to remove the complexity of Whonix ™. Rephrasing the question, removing the Whonix ™ specific part of it, utilizing other resources might yield more information or better help. Therefore all topics which are unspecific to Whonix ™ are redirected to upstream resources as per Free Support Principle.

For issues specific to Whonix ™ it is still highly useful to attempt to utilize the same concepts and principles as much as possible. To more colorfully explain this, an example will be used. A good example is issues with VirtualBox showing VERR_INVALID_HANDLE ^[archive]. Whonix ™ does not develop VirtualBox. Whonix ™ source code does not contain textual string VERR_INVALID_HANDLE. (search Whonix ™ source code) The error message is generated by the VirtualBox source code and is not by the Whonix ™ source code. The VirtualBox community and developers have more expertise in this area.

Even if the issue is only occurring inside Whonix ™, perhaps caused by Whonix ™ integration source code, i.e. Whonix ™ specific, useful things to research are:

• How is this implemented in Whonix ™?
• How to reproduce this independently of Whonix ™?
• How to reproduce this in Debian bullseye?

Posting a link to this wiki chapter does not imply the issue should not be discussed. On the contrary, it is an invitation according to the The User Co-developer Concept to utilize upstream resources. If questions where asked, bug reports posted, helpful information or (partial) solution have been found, please consider editing the Whonix ™ Documentation and/or providing a complete answer in the Whonix ™ User Forums as a contribution to Whonix ™.

Software Development Cycle[edit]

Community Feedback[edit]

The Whonix ™ project is highly receptive to genuine feedback and suggested improvements from users. Software projects flourish from community input and every suggestion is noted and considered.

The Whonix ™ community is asked to remain patient. The development cycle involves a number of competing priorities and challenges which must be overcome to achieve ambitious roadmap goals. Further, there is also an existing backlog 1 ^[archive] / backlog 2 ^[archive] of unresolved bugs and feature requests to address. See also Policy Rationale.

If Whonix ™ resources grow over time, development activity and responsiveness to user input might increase. See also Linus doesn't scale and Whonix ™ social organization structure doesn't scale yet either ^[archive].

Often, proposed improvements or fixes to the Whonix ™ platform are awaiting implementation due to differing developer priorities, limited human resources and/or the inordinate amount of time required to develop a particular feature or solution. In a minority of cases, the Whonix ™ team is unsure how to resolve a bug or implement a specific change / feature. ^[4]

It is generally unhelpful to debate the priorities laid out in the future Whonix ™ roadmap, as this diverts energy from core development. Some major suggestions might become available in the long-term or might never eventuate. See also Linux User Experience versus Commercial Operating Systems to learn about organizational and funding issues in the Open Source ecosystem.

For some requests it might be possible to:

• get the it solved if you contribute and/or become a contributor.
• have the same benefit by applying Free Support Principle.
• pay for it. See Professional Support.

Contributions[edit]

Volunteer contributions to Whonix ™ are most welcome. All proposed patches are carefully reviewed and merged if appropriate. Volunteers with the requisite coding ability should refer to the current backlog 1 ^[archive] / backlog 2 ^[archive] and consult with developers before undertaking any significant body of work. See also Focus on low-effort maintainability ^[archive].

Old Stable Support Policy[edit]

It is not uncommon for Linux Distributions to support multiple release versions. ^[5] The popular Debian Linux distribution on which Whonix ™ is based not only provides the stable, testing and unstable versions, but also maintains support for the old-stable version. The main reason is because it can take a long time for some organizations to plan, test and upgrade all computers when a new stable version is released. ^[6]

Supporting the old-stable version with continued security updates for a period of time provides flexibility when migrating to the stable version. However, even for distributions like Debian that have a large number of developers, it can be very difficult to support both the stable and old-stable versions. This is evident by the limited time that the old-stable version is supported after the new stable is released - currently around one year on average. ^[7]

Providing extended support for previous stable versions is preferred for both large and small projects alike, but this is infeasible for Whonix ™ due to limited human resources. The reason is the vast majority of developer time must be focused on core components of the stable release version, otherwise providing support for both stable and old-stable would unduly stall its development. Therefore, without a significant increase in funding or manpower, the maintenance of two stable release versions is unlikely in the near or distant future.

Package Upgrade Policy[edit]

Tickets that have status resolved or implemented on the backlog 1 ^[archive] / backlog 2 ^[archive] are not automatically pushed to the stable (or even developer) APT repository of Whonix ™. Also referenced git commits are not intended to imply that.

• Standard Package Migration (link):
  • Stable package upgrades take time in order to provide a Whonix ™ Stable Version User Experience.
  • Packages are uploaded to the developers repository first. After developer testing, these are migrated to the testers repository for general testing. After that, these are migrated to the stable-proposed-updates repository. Eventually, packages are migrated to the stable repository
  • Standard Package Migration: package upload → developers → testers → stable-proposed-updates → stable
• Instant Package Migration (link):
  • If critical security security vulnerabilities are discovered.
  • Packages with very low probability of introducing system instability.
    • Tor Browser Downloader by Whonix ™ (tb-updater ^[archive])
    • monero-gui ^[archive].
    • binaries-freedom ^[archive] (electrum appimage).
  • Special purpose packages such as debug-misc ^[archive] which are not installed by default.
  • Instant Package Migration: package upload → developers → all repositories (testers, stable-proposed-updates, stable)

Advanced users who do not wish to wait for package updates can of course manually apply fixes to the relevant package(s) before that time. ^[8] Often all that is required is opening the files which were changed in a git commit(s) with root rights and emulating what the git commit would have changed. Do not copy any + or - signs that only illustrate which lines where added / removed and are not part of the actual file change. Another option is to update the package from source code.

(Package Upgrade Policy Forum Discussion ^[archive])

Issue Labels[edit]

Forum Issue Tracker Labels[edit]

Table: Forum Issue Tracker Labels

Label Descriptor	Description
open	The issue is still in the backlog.
confirmed	Developers or other community members were able to reproduce the issue.
diagnosed / undiagnosed	Developers or other community members were able/unable to identify the cause of the issue.
won't fix	This is an ambiguous label that will hopefully be avoided in future. This applies to any issue that could be theoretically fixed, but it was rejected because there was no obvious solution, it was deemed too expensive to fix (in time or resources), the fix would add too much complexity, or for other reasons. See this entry [archive] for a rationale.
can't fix	Similar to the entry above.
closed	The issue was fixed, but the solution may not have been deployed yet.
implemented	The issue was fixed, but the solution may not necessarily have been deployed. This is distinct from the closed label because code has been devised, but it may not have yet filtered through to the Whonix ™ repositories (stable, stable-proposed-updates, testers or developers APT repositories).
patches welcome	See source code contributions for further information.
unsupported	The proposed use case is unsupported and no contributor is available or volunteering to provide Free Support for implementation. Contributions are welcome. Professional Support might also be available.
declined	The feature request was declined. No contributions will be accepted and Professional Support is also unavailable.

Phabricator Issue Tracker Labels[edit]

Phabricator issue tracker labels can be interpreted as follows:

• Reviewed: "Completed in the latest source code version of Whonix" (but not released). Further testing is required in the next Whonix ™ developers-only or testers-only release.
• Resolved: "Completed in the development version of Whonix".
• There is no specific label to indicate status in the stable Whonix ™ release.

Support Request Policy[edit]

Due to constraints,

• many support requests unspecific to Whonix ™ have to be redirected elsewhere as per the Free Support Principle,
• many features are presently either undocumented, untested, unsupported or community support only, and
• sometimes there are Declined Feature Requests.
• Whonix ™ developers will normally only respond if they are convinced an actual technical, privacy or security-related problem has been identified. Many issues are unfortunately Out of Scope Issues.

In the past, Whonix ™ developers provided answers to a wide range of reported oddities, such as console output messages that were difficult for users to understand. Unfortunately this level of attention is no longer possible, for reasons outlined in this chapter. Effective December 1, 2018, the policy concerning responses to support requests and concerns had changed.

Out of Scope Issues[edit]

For example, if a user reported that the following console message appeared during an update, Whonix ™ developers would be unlikely to respond.

70 signatures not checked due to missing keys

The reason is because developers are aware this is not symptomatic of a technical problem, but rather a minor usability issue. In case of this example, if the user reporting the problem conducted simple Internet research, they would quickly realize the cause of the error is not Whonix ™-specific. ^[9]

As a reminder, most anomalies are generally harmless rather than an indication of a compromise:

If trivial changes are noticed on your system -- such as a duplicate desktop icon -- this is not evidence of a hack or leak. Similarly, if warning or error messages appear that are difficult to understand, in most cases there is no need for panic. If something unexpected occurs such as the appearance of a "htaccess file in home directory", or graphical glitches emerge in Nyx, then it is more likely a harmless bug and/or usability issue rather than a compromise.

Policy Rationale[edit]

There are several reasons for this policy:

• Developer Time:
  • Providing answers for each and every (duplicate) reported (non-)issue costs time, which could be otherwise dedicated to core development and the backlog 1 ^[archive] / backlog 2 ^[archive] of existing bugs.
  • To get an insight of the existing developer workload, see selection of Whonix ™ project activities and maintenance tasks and Whonix ™ News ^[archive].
  • Consider the following analogy. A popular speaker at a conference is approached by 500 people before their speech. Each individual requests a private discussion of only five minutes. The speaker made a rough calculation; ~500 people multiplied by five minutes equals 2,500 minutes or ~ 41 hours (nearly two days). Clearly it is infeasible for one speaker to accommodate everyone's request for a short discussion.
  • By comparison, generally the architects of complex structures like buildings or hardware (and a myriad of other professions) do not explain any technical details for free to the general public.
• Personal Initiative: Whonix ™ is Freedom Software (Why?), which means every aspect of the source code is available for review. This level of transparency allows those who spend enough time or monetary resources to analyze everything in detail. In the spirit of Freedom Software, Whonix ™ is purposefully opposed to artificial boundaries which make analysis unnecessarily more difficult.
• Feature Richness: Since Whonix ™ is based on Debian there are thousands of software packages available for use, and not all oddities can be discussed or explained due to time constraints.
• Usability Issues: In the main, most usability issues will remain out of scope for developer attention. The reason is two-fold: either they are outside the control of the Whonix ™ project and/or it is not economically viable due to the very structure of Freedom Software development; see Linux User Experience versus Comparable Operating Systems for further information.
• Legal Liability: Due to legal liability and time restraints few communications can flow through Whonix ™ Website and Whonix ™ Chat.
• Free Support Principle Rationale

There are several reasons for this wiki entry. First, a link can be posted whenever necessary, thereby saving developers significant time and effort in addressing issues that are out of scope or non-issues. This demonstrates acknowledgement of the report, but also signals it is not cannot be processed at this time. Secondly, answering with a link is better than a non-answer. A nil response makes it unclear if the report has been seen or whether project development is even active.

Users are welcome to report whatever they like, but it is strongly recommended to first search the forums ^[archive] and Internet as per The Free Support Principle to see if it was already reported - this is often the case.

It is also absolutely crucial to subscribe to and read the latest Whonix ™ news category 'important-news' to stay in touch with ongoing developments. This way users benefit from notifications concerning important security vulnerabilities, potential upgrade issues, common issues and improved releases which address identified issues, like those affecting the updater or other core elements. See Stay Tuned. Often issues which users are about the report are already mentioned there for example in the changelogs of release announcements.

Issue Tracker[edit]

Transition to Discourse Forums[edit]

In the recent past, all issues were posted to the legacy tracker application: Whonix ™ phabricator ^[archive]. However, the decision has been made to migrate issue tracking to the Whonix ™ discourse forums ^[archive]. ^{[10] [11]}

The links to the existing backlog of open issues (backlog 1) and the new discourse forums backlog location (backlog 2) are below.

backlog 1 ^[archive] / backlog 2 ^[archive]

Forum Tags[edit]

The goal of forum tags is to maximize the usefulness of the Whonix ™ forums as a roadmap and issue tracker for project developers.

Previously there were no guidelines or rules on how to use discourse forum tags; anyone could create, add or change them. ^[12] Discourse forums tags can now only be changed by Whonix ™ discourse moderators ^[archive].

Search query examples:

• all status_open_issue_todo issues ^[archive]
• all status_closed_issue_implemented issues ^[archive]
• status_open_issue_todo component_security related enhancement requests (TODO) ^[archive]
• status_closed_issue_implemented component_security related enhancement requests (done) ^[archive]
• status_open_issue_todo component_research tasks ^[archive]
• list of all forum tags ^[archive]

You can create a comment in a separate post such as:

• Please open.

• Please close.

• Please re-open.

• Please add tag testers-wanted.

• Please remove tag component_security.

If appropriate, the tag will be changed by a forum moderator. ^[13] Note that issue-related comments might be deleted if inappropriate, duplicated or for the sake of brevity in the discussion (like when the status update was not changed due to a mistake). Also, tags should not be appended to every discussion or question about the related subject. ^[14]

If a forum thread is not tagged with the current stable release of Whonix ™ or the next Whonix ™ release (whonix-15 and whonix-16 at the time of writing), then it is not on the roadmap. In this case the likelihood the issue will be resolved is lower, whether it is a feature implementation, research/task completion, or bug fix. Please refrain from debating issue priorities or the timeframe for implementation; see Community Feedback.

Appendix[edit]

Linux User Experience versus Commercial Operating Systems[edit]

Introduction[edit]

When newcomers interact with a Linux operating system like Whonix ™, they come with certain expectations in regards to their overall experience. For the majority, expectations are based on their familiarity with Windows or macOS, since they dominate the desktop and laptop markets. ^[15] These commercial platforms pre-install a wide variety of popular and fully-featured applications, while the graphical user interface (GUI) is easy to use and intuitive. As a consequence, the seamless integration of new system software packages is the rule rather than the exception.

Windows and macOS users are now accustomed to an integrated experience where "everything just works". Attempts to provide a comparable experience in Linux have proven to be very difficult and the problem seems insurmountable. Many find the Linux GUI difficult to use and counterintuitive. There are software applications that are similar in design to those found in Windows or macOS, but they often lack many of the same features ^[16] or do not fully integrate with other packages. For Linux beginners, it might be difficult to understand how applications with similar design goals can have vastly different cross-platform functionality. Only by comparing the structural differences between a typical corporate hierarchy and a Linux distribution's collaborative effort can the discrepancies be explained.

Linux Distributions vs. Commercial Operating Systems[edit]

Overview[edit]

The following table provides a simplified comparison of the major organizational structural differences. Quoted figures are accurate for the year 2020.

Table: Linux Distribution vs. Commercial Operating System

	Linux Distributions	Commercial Operating Systems
Software	Based on packages from many independent projects which develop software according to their own design goals	Centralized (in-house) development with unified design goals
Funding Sources	Donations, volunteer payments, grants, corporate sponsorship, professional services	Revenue from software licensing [17] [18]
Funding Amount	Unprofitable, most are underfunded and depend on volunteers	Profitable, billion dollar profits are the norm
Authority to Issue Directives	None, can only ask third party projects nicely	CEO issues directives
Human Resources	Community-based volunteers (limited time and human resources)	In Windows' case, over 163,000 employees [19]
Popularity	~ 1.85 per cent of the desktop operating system market [20]	Windows: ~ 78 per cent of the desktop operating system market [20] macOS: ~ 17 per cent of the desktop operating market [21]
User Experience	Fragmented	Unified

Software Comparison[edit]

As shown in the table above, Linux distributions are based on many third party projects which develop software according to their own design goals. For instance, an application might be initially developed by a volunteer for Windows and optimized for that platform. Later on, another volunteer joins the project, forks the application and ports it to the Linux platform. When these projects develop software, they do not necessarily prioritize the design goals to suit compatibility with Linux distributions.

Linux distributions can only pick software packages that are already available, meaning the selected packages might fall short of the design goals. Moreover, unlike a traditional company, distributions are not structured with a large number of paid employees. Neither do they have the authority to issue directives to third party projects to make desirable software changes. If a distribution needs package changes from an independent project, there are a few options but they all require time and patience: ^[22]

• Try to understand the perspective of the third party project.
• Politely ask the project if they would be willing to make the changes.
• Submit code that makes sense from their point of view.
• Patch and/or fork their software.
• Use an alternative package from a different project.

In contrast, commercial operating systems are based on software expressly designed to provide a fully-unified user experience. While Linux distributions rely on third party packages, commercial platforms are developed in large companies with a strict corporate hierarchy. In these companies, the CEO can issue a directive to developers to make any change needed to improve the integrated experience. Any developer who lacks the necessary skills or refuses to make changes is likely to be terminated for non-compliance. The human resources department (representing the CEO) will not tolerate delays in software development, as it might threaten profits.

Funding Comparison[edit]

Linux distributions are based on Freedom Software which can be used freely by anyone. Without a software licensing fee, options to generate a reliable funding stream for development are severely limited. Unless funding is available to hire a large contingent of full-time employees, it is nearly impossible to provide a unified experience. Instead, distributions rely primarily on the goodwill of developers who volunteer their time to integrate and maintain software packages. Without a salary, the time developers can devote to the task is necessarily reduced. Although this problem is attributable to the restricted funding sources available, it has less impact for sizeable or popular distributions due to:

• Donations or volunteer payment-based funding.
• Professional services provided on a commercial basis such as technical support, training and consulting.
• Developmental grants.
• Corporate sponsorship.

On the other hand, proprietary operating systems like Windows are funded through the sale of software licenses and few barriers exist to funding growth. Licensing generates billions of dollars in revenue which is used to employ a large number of full-time developers. This in turn allows these employees to focus on developing the software packages from the ground up, while remaining focused on the primary design goal: maintaining and improving the "Windows user experience" that the community has come to expect.

Conclusion[edit]

Based on the preceding information, it is unrealistic to expect any Linux distribution to provide a unified user experience identical to Windows or macOS. Linux has gradually improved the quality and consistency of the user experience on various devices, particularly for larger and more popular distributions like Debian, Fedora and Ubuntu. However, it is impossible for most (if not all) distributions to replicate the quality found on commercial platforms. In the case of smaller distributions like Whonix ™, very limited human resources mean it is out of the question. Instead, developers must spend a large portion of their time on core functionality development.

One obvious impact is that Whonix ™ developers have limited time to answer support requests. Therefore, it is recommended to follow the advice outlined in the Free Support Principle chapter before asking for specific help. In addition, please document any steps that were used to solve problems in the forums and/or wiki, thereby supporting the co-developer concept which has been adopted by the Whonix ™ project. ^[23]

On the upside Linux distributions have unique advantages. Less bloatware and other anti-features are imposed on the user. Privacy is generally better protected. When Windows breaks, the recommendation is usually to "reinstall Windows" which is a non-solution. The underlying cause of the problem in many cases has not been identified, understood or reported, hence it is likely to reoccur due to a lack of progress. The common experience of Windows users is the platform becomes slower over time.

When the support channels of commercial operating systems are utilized to report an issue, the support staff often provide inadequate responses. Issues may be ignored or reinterpreted as the fault of the end user. Issues are frequently not forwarded to developers and therefore never fixed. While it is difficult or near impossible to approach the developers of commercial operating systems, Freedom Software developers are generally accessible. In contrast to the open development principles adopted by Linux, the proprietary, closed source nature of commercial operating systems hinder community efforts to resolve problems or make enhancements -- it is very difficult or impossible to perform the necessary analysis of internals and source code.

Footnotes[edit]

---

---

	100px
Fosshost	About Advertisements

---

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

---

Follow:

Support:

Donate:

Priority Support | Investors | Professional Support

Whonix ™ | © ENCRYPTED SUPPORT LP | Freedom Software / Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.