introduction for "user friendly" documentor

lwatts · December 15, 2016, 7:32pm

Greetings, all,

I’m new here and thought I should introduce myself. I saw, and am responding to, the request on sourceforge’s helpwanted/documenters page, asking for someone to write some “user friendly” (or “for dummies”) documentation for whonix.

I am a native of, and live in, Atlanta, Georgia, USA, and a native English speaker (and writer). I’m interested in whonix, and I believe that I’m capable of writing what you need. I’m a software engineer with ~38 years of programming experience, including close to 2 decades of unix/linux experience. I’ve also acted as system / network administrator and as technical writer when the need presented itself.

Let me know if you have ideas for me to work on, and I’ll let you know what I’m thinking and working on.

Thanks! --lw

entr0py · December 15, 2016, 8:57pm

Welcome! I think we can find things for you to do.

Sheesh, with your background, your talents may go wasted on writing documentation if you could contribute code instead. Ways to Contribute. @Patrick can tell you which tasks need to be prioritized if you’re interested in that path.

I’m not sure if you’ve had a chance to browse the Whonix wiki yet: Whonix ™ Documentation. It’s a massive collection of comprehensive articles which have become quite disorganized over time. Some pages need to be merged, recategorized and updated.

I am Lead Procrastinator for a rather urgent Quick-Start guide that would help new users get started with Whonix. Details here: Whonix Short Documentation - Suggested FINAL - #11 by entr0py. I’ve been bouncing things around in my head for a while so I’ve got an idea of what needs to be done. My plan is to produce a first draft this weekend. Perhaps you would be willing to provide feedback?

lwatts · December 15, 2016, 10:32pm

Hi entr0py,

Thanks for your reply. I’m not at all opposed to contributing code, but I feel like I need to really learn the project first, and I learned a long time ago that one of the best ways to learn anything is to teach it to someone else.

I have looked over (not yet really in depth, but I’ll get there) the existing whonix documentation and was impressed with the breadth and depth, but I did notice some need for organization and cohesion.

I’ll be happy to look over a first draft of the short doc whenever it becomes available, and of course, provide feedback. Thanks for the welcome, and I look forward to working with you.

Thanks! --lw

Ego · December 15, 2016, 11:17pm

Good day,

First of all, thank you for being willing to support Whonix in such a way. That’s great to hear. Now, like @entr0py said, @torjunkie already somewhat outlined how the short documentation should look so that is likely a good place to start: Whonix Short Documentation - Suggested FINAL

Now, @torjunkie actually made another great contribution in creating a more simplified documentation already here: Whonix Quick-Start Guide v0.1

It can be of tremendous value to those wanting to get a deeper understanding of Whonix. However, for complete newcomers it can seem frightening due to its massive length. The current goal thus would be to simplify and strip down this documentation further for use as somewhat of an “Quick Start Guide”.

If already create a base for such a guide on our new homepage with the goal of making editing as simple and convinient as possible.

Due to the way I’ve designed this each main chapter will be housed in it’s own markdown file with the suheadings being included in there. These would have to be pushed into the respective folders found here: Whonix-Website/content at Preparation-for-Translation · EgoBits1/Whonix-Website · GitHub with every of the respective sites having their own “English” section. This design has been adopted both, to make the documentation easier to manage, as well as to make the “whole thing” translatable while not stressing the server to much with scripting and negating the need for client side scripts, like JavaScript, as those are often deactivated by Tor Browser Bundle Users.

Each folder is named so it reflects the respective chapter. So:

An Introduction to Whonix = /intro
Installation and Updating = /install
First Steps in Whonix = /first
Common Tasks = /common
Where to go from here = /more

You may push anything you’ve written to this repository. I will then make the necessary adjustments to get everything in an easily readable state adding things like section based URLs manually, to make navigating the documentation as easy as possible.

It’s actually us who should thank you for your support.

Have a nice day,

Ego

lwatts · December 16, 2016, 7:39pm

Hi Ego,

Thanks for your welcome as well, and this information is just what I needed to get started. I’ll see what @entr0py and I can do over the weekend, and go from there.

Thanks! --lw

torjunkie · January 5, 2017, 11:05am

@lwatts @entr0py

Hi

How is this progressing? Can I help or do you have things started already?

I only want to finish up Firejail, grsec, and miscellaneous ‘other’ entries under security guide that came out of the forums (shouldn’t be too difficult), and then should hopefully have some time to commit to this over the coming weeks.

I think lwatt’s coding experience is better put towards unfinished phabricator items in the high and medium categories, since documentation can be done by anybody, but his skills are quite rare.

There are 4 unfinished items in the ‘high’ category and well over 100+ under the ‘normal’ category here for Whonix:

https://phabricator.whonix.org/maniphest/query/all/

If you don’t need help with the Quick-start Guide, then I’ll probably request @Patrick’s permission to rework the security/advanced security guides.

Re: security guides, frankly they are a mess in terms of structure, even though the information is valuable.

Major overlaps exist in these sections:

Plus, ideally things would be separated into strictly non-Qubes-Whonix only items, Qubes-Whonix items, and both category items.

Also, security things should really be separated into ‘easy’, ‘medium’ and ‘difficult’ sections, focus on steps only to get them done, and reference all the security information (e.g. quotes, security theory etc. taking up half a page at a time) in perhaps the ‘Computer Security Section’. The latter section would be full of a hundred plus footnotes.

lwatts · January 11, 2017, 6:41pm

Hi @torjunkie,

Thanks for your message and offer to help. I have started, but it’s been a very slow start. Nevertheless, I am working on it and I have a reasonable idea of what I want to write and how I want it to look. And BTW, I would love to work on the code, but I chose to work on documentation first so I can learn the overall product before I jump in and start screwing up the code. B^)

My idea for the Quick-Start Guide (QSG) is to strip it down to just the bare essentials that someone would need to install and run Whonix on a Windows host with VirtualBox. After that, maybe add to that document or write a separate but similar document for a Linux host with VirtualBox. And then maybe the same thing for a Mac. The main thing I’m trying to focus on is to limit the scope and give the instructions without all the explanation.

I’m imagining that my target audience is the journalist, for example, who knows how to use his Windows laptop to research and write. His biggest problem is that the only thing he knows about security, privacy and anonymity is that he desperately needs it to protect himself and/or his sources. And he needs it now, not after days, weeks, or more devoted to learning about security.

I just looked (briefly) at the Tor Project’s Quick Start Guide. I’ll check it out further and try to use it as a guide for detail level, etc. And I’ll try to do better progress reporting as well.

Thanks! -lw

torjunkie · January 14, 2017, 1:15pm

That’s great!

I won’t get in the way of you and entr0py; he/she is also skilled at writing documentation for non-technical users.

It’s great to see the Whonix community coming together to support the hard work of the small Whonix team, who work their asses off on the project. Your help and expertise is very welcome I’m sure.

Cheers

lwatts · January 21, 2017, 12:09am

Hi @Patrick, @entr0py, @torjunkie, and @Ego, et al,

So far, I’ve pretty much ignored all of your wonderful suggestions and
just plowed ahead, listening only to the voices in my head.
Nevertheless, I now have a very rough first draft with no formatting,
of what I thought might be “the bare essentials that someone would need
to install and run Whonix on a Windows host”. Interestingly, half-way
through this draft, I ran across Whonix ™ for Windows, macOS, Linux inside VirtualBox,
which is almost exactly what I had originally envisioned, but after
getting started I decided it should have more. However, that didn’t
keep me from plagiarizing it mercilessly, along with several other
documents I found on the website/wiki. In this draft, I’ve used a kind
of footnote notation that I might replace (for most of these) with the
document reference / link notation that I’ve seen in the edit feature
of the wiki (“[[document_name#section_name|display_text]]”).

I also want to go back and at least look into all of your suggestions,
and see if it makes sense to incorporate into this document in some
way. And I want to “follow” the document, step by step, to
download,verify,install,configure, etc., so I can see where I’m
steering people wrong. Then, I’ll look into formatting, especially
with the wiki software, etc. And I’ll look around for a document or
instructions / suggestions for posting for review, etc.

So here’s what I have so far. Feel free to point out all my misteaks,
and/or tell me that’s not at all what you wanted (but please try to
clarify what you did want). Thanks! - lw

lwatts · January 21, 2017, 12:10am

Whonix Quick-Start Guide v lw0.1

Introduction (Why are we here?)

Whonix is a free desktop operating system (OS) that is specifically designed for advanced security, privacy and anonymity. It is Free Software, based on Tor, Debian GNU/Linux, and the principal of security by isolation. As such, many of its security benefits come from running within virtual machines on a host operating system.

This Quick-Start Guide describes how to use Whonix on a Windows host system, however, it is important to understand that using Windows as the host OS negates most (if not all) of whonix’ security / privacy benefits. [1] Nevertheless, Whonix can be run on a Windows host and people have their reasons for doing this. Whether you simply don’t believe the warnings about Windows security issues, or you have no choice but to use a Windows sytem and need to secure it as much as possible, this guide is here to help you do just that.

Before getting started, if you are new to Whonix and have not already, read the About [2], Warning [3] and Do Not [4] pages to make sure that Whonix is the right tool for you and you understand well its limitations.

Prep host hardware and OS

First, in keeping with the principle of security by isolation, if at all possible, you should use a system that you won’t be using for any other purpose. This is so that you won’t be loading and running any other software (each with their own possible security issues), and also to minimize the exposure to malware and accidentally giving away your identity. Also, using a completely separate machine for Whonix makes it easier to implement security measures over the whole machine and reduces the risk of overlooking some small piece of vital data.

Along the same lines, remember that if you purchased the hardware with a check or credit/debit card, and/or if you got a “rebate” on the purchase, the serial number of the machine linked to your payment information was recorded and might have been sold, stolen, or otherwise distributed. The same may be true if you ever took it in for repair, upgrade or virus removal, etc.

Before you install Whonix on your Windows system, you should clean up your Windows installation as much as possible. First, you should back up any and all data that is important to you. [5] If you’ve had your system for a long time, you might want to completely wipe out your primary partition and reload windows from scratch, preferrably with Full Disk Encryption [6]. If you do this, you will probably want to go in after the reload and configure Windows to be as secure as possible, especially with regard to Windows updates, etc.

If you do not opt to reload Windows, at least do everything possible to ensure that you have a malware-free system. [7] Uninstall every piece of software that is not absolutely required. Run a file system (hard drive) cleaner to remove (and securely wipe) any temporary and non-essential files. Then run the same “cleaner” software to securely wipe your hard drive free space. (Of course, as mentioned earlier, back up any data that you can’t afford to lose.) Run a registry cleaner. After all of this, run a full scan of anti-rootkit software, anti-malware software, and anti-virus software.

Be very careful in the initial setup/activation of Windows, that you do not enter your name, email address, or any other personal information. [8] (And don’t think you’re safe because you used a hotmail or gmail or other address where you signed up with a pseudonym.)

And finally, do any Whonix specific pre-install configuration, such as configure and run Windows firewall or install and configure a third-party firewall. [9] Also disable TCP Timestamps. [10] Disable or secure your microphone and webcam as well. [11][12] Replace any wireless input devices (keyboard, mouse, etc.) with hard-wired equivalents as well. [13] And make sure that you have at least 8GB of free disk space.

Download, verify and install Whonix

a) Download the installer. (Whonix-Installer for Windows)
https://download.whonix.org/windows/Whonix-Installer.exe

b) Verify the installer.

It is important to always check the integrity of software files
downloaded from the internet, to ensure that the files are exactly as
the developer intended and were not corrupted in any way.  If the
verification fails, Do Not Continue with this/these file(s).  Delete
the file(s) immediately, then re-download and verify the newly
downloaded file(s).

The Whonix-Installer has been cryptographically signed using OpenPGP
[14] by the creator of the Whonix-Installer, Ego. [15]

If you know how to use an OpenPGP key, download the signing key [16]
and the Signature [17] straight away.  Otherwise, follow these
instructions: (Verify the Installer).
    https://www.whonix.org/wiki/Installer/Verify_the_Installer_using_the_command_line

c) Install Whonix.

Execute the verified Whonix-Installer.exe and follow its instructions.
Please be careful to read the instructions in their entirety and make
sure you understand everything.  [18]

Please note: Due to the size of Whonix and the accompanying files,
this may take up to half an hour.

d) Start using Whonix

You may now enjoy Whonix and all its features, either via Whonix.exe
or Whonix for Windows, which you should find on your desktop or
VirtualBox.

Install additional software

Whonix is made up of 3 main components, and when we’re talking of installing additional software, it’s important to make the distinction clear:

The host Operating System (OS) (The only host Operating System discussed in this document is MS Windows.) is the OS that hosts the virtual machines that make up the Whonix system. The host OS is not part of Whonix, and any additional software that runs on the host operating system will get no security, privacy, or anonymity benefit from Whonix running on the same machine at the same time.

The Whonix-Gateway runs in a virtual machine and only runs Tor, directing all internet traffic through Tor. Once Whonix is installed and configured, there should be no reason to modify anything on the gateway virtual machine.

The Whonix-Workstation virtual machine is where you reap all of the privacy/anonymity benefits of Whonix. Whonix comes with applications for various tasks, pre-installed by default. (See the Software [19] page for a list of these applications, software recommendation, safety advice, and installation instructions.) If you need to install additional software, the Whonix-Workstation virtual machine is where it must be installed. Also, note that the operating system of the Whonix-Workstation is Debian GNU/Linux, so the only software that can be installed in the Whonix-Workstation must be able to run on the Debian GNU/Linux OS.

Having said that, the pieces start to fall into place and Windows users with no experience with GNU/Linux begin to realize that they can’t use their Windows-only software on a Whonix system. (i.e. The security / privacy / anonymity benefits that Whonix provides cannot be applied to software that only runs on Windows.) About the best you can do with Windows-only software is to run Tor directly on your Windows system and try as much as possible to keep it clean and free of malware. Also, be hyper-vigilant to avoid letting any personal (or personally identifiable) information get onto that machine, and understand that it is simply not possible to completely secure the machine.

Security tips (Post install advice)

In the Whonix-Gateway and Whonix-Workstation virtual machines:

Change passwords for the “user” and “root” username accounts. [20]
Regularly check for security updates and apply them. [21]

Network Time Syncing: When you use the pause/suspend/save/resume feature of your virtualizer or the hibernate feature of your host operating system while Whonix-Workstation is running, you should manually run TimeSync (in the Whonix-Workstation virtual machine) afterwards! [22][23]

We recommend against using pause/suspend/save/hibernate on the Whonix-Gateway virtual machine because of the difficulty of restoring the clock after resume.

And on the Windows host, check often to make sure the battery is not empty, and configure Windows to get its time from the internet. Avoid using Microsoft’s time servers, instead check out: http://www.pool.ntp.org/

You can further improve security by reading and applying the Security Guide.
[24]

torjunkie · January 22, 2017, 4:21pm

Hi lwatts,

That looks like a good start! Short, sweet, covering off the basic things to get Whonix up and running on Windows fast etc.

I’ll wait to see if the other guys already tasked to Short-Guide comment first though, before providing any substantial feedback. I have a few things in mind.

Cheers

Ego · January 22, 2017, 6:22pm

Good day,

First of all, thank you for making this kind of a write-up, it is very much appreciated.

Secondly, I feel like there is a certain focus on Windows based installations, which, while being good from a users perspective, also might create a few issues. Take the “Prep host hardware and OS section” as an example:

Focusing on Windows hosts is only a good idea for a quick start guide if we acknowledge the fact that by design, Windows isn’t a secure host. Recommending to do a fresh install of Windows is not advantageous in this scenario as it both, creates an image of unnecessary security theater, as well as the feeling, that using Windows as a host, once freshly installed, is a secure way of using Whonix.

That’s the reason why I’d shorten or maybe even remove this section. As long as Windows is used as a host, their are very few configurations (Windows-10-LTSB which is said to be trackingless, though also extremely expensive, not withstanding) which will give a user a significant improvement in security and anonymity.

Whonix for Windows really has been designed as a simple introduction which enable people to experiment with Whonix in a familar environment without the necessity of complex imports or OS switches.

Adding to that, certain post-install advice is, at least in Whonix for Windows thanks to Whonix-UI not necessary anymore. Whonix-UI has been designed in a way to shut-down the machines in the most safe manner possible. Simply recommending against using any other way of controling the machines should be shorter, simpler and easier to digest for users.

Also, the Windows time recommendation is, at least in my eyes, redundant, seeing how A) Windows will never be secure enough for “dissident-level journalism” and B) the host OS’s time shouldn’t have any influence on things done inside the Workstation. If there should be a way for it to influence a virtual machine, then the security Whonix relies on has been broken long ago already.

Other than that, it is a very nicely made draft.

Have a nice day,

Ego

lwatts · January 23, 2017, 6:08pm

Greetings all,

Thanks @torjunkie for the quick response and @ego for the detailed feedback. All very valid points, including some that I hadn’t researched well enough to know before. I feel like I need to keep the “Prep host hardware and OS” section for 2 primary reasons: (1) Even if the host OS isn’t secure and breaks the security of the entire system, I want to get people used to the idea that regardless of OS, these steps are important to prepare the host, and (2) Many of these steps are helpful in removing adware and other malware that slow down the system so much even before installing whonix.

I also have friends that revere Bill Gates as the one person who has done more for the computer industry than anyone else in the world, and they are blind to any faults in MS products. They see any criticism as BG or MS “bashing” and would never deign to use a non-MS OS. I think that if I can “get a foot in the door” with Whonix for Windows, I can get them to focus on real security and start to open their minds to the truth.

So with that in mind, I’ll see what I can do with a second draft, and post it here when I’m done.

Thanks! - lw

Ego · January 24, 2017, 1:31am

Good day,

I see what you mean regarding those two reasons and they are very much valide reasons, though I’m still personally unsure as to whether it is a beneficial idea in regards to reading flow, to have such a massive elaboration in what essentially should enable to set the user up and point at enhanced documentation at the end. Perhaps shortening it slightly might be a good idea, seeing how we’ll likely link to the “enhanced” documentation anyways at every point in the quick start guide.

Very interesting and indeed clever stance. I obviously have no issue with people using Windows, nor any other Microsoft product, as it is their personal choice. Owning a Surface for taking notes in lectures, that would be quite hypocritical. Though the question remains whether the type of person who’ll stick to Windows as a host would even consider doing a full wipe to use “yet another anonymity tool”. That’s why maybe putting it front-and-center in this magnitude might be suboptimal. It could create a rather paranoid apperance of people using this kind of Software which may deter people from using it at all, even if the reasons for it are very well founded and perfectly reasonable.

Finding a balance is what we have to do here.

One more thing: Gates the person who’s done the most for computers? What about Charles Babbage, Charles Xavier Thomas or Alan Turing. Bill Gates was certainly incredibly important and seems to be a great philanthropist, though in regards to importance for computers as a whole, I certainly don’t see him in the top ten.

Again, thank you very much.

Have a nice day,

Ego

Patrick · January 24, 2017, 10:04am

The writeup to reinstall Windows and keep it malware free is awesome to have in the wiki but rather as enhanced documentation indeed. For the quick start it’s much too long. Thank you a lot for working on this!

lwatts · January 24, 2017, 12:48pm

No problem. Stay tuned…

Thanks! - lw

lwatts · January 26, 2017, 12:14am

Greetings, all,

I’ve attempted to address most of the feedback from my first draft in this second draft. I’ve changed the name to make it clear that it’s just for Windows, and I plan to do the same for the Debian version (that’s next on my list). (I don’t expect to write a Qubes version of the Quick Start Guide because I would expect anyone ready and willing to install “Whonix for Qubes” would not need a “Quick Start Guide”.)

Also, I applaud the author of the Whonix “Windows” page. (Whonix ™ for Windows, macOS, Linux inside VirtualBox) I understand that to be an excellent “Quick Start Guide”, and may not have written my version if I’d seen it before I committed. After we reach concensus on major mods to my version, we can decide whether to keep these (2) distinct documents separate or merge them into one.

As always, let me know what y’all want and I’ll try my best to accomodate. Thanks! - lw

lwatts · January 26, 2017, 12:24am

(Apologies for the numbering below; this editor doesn’t like the way I did it and I don’t have time to wrestle with it at the moment.)

Whonix for Windows Quick-Start Guide v0.2

Introduction (Why are we here?)

Whonix is a free desktop operating system (OS) that is specifically designed for advanced security, privacy and anonymity. It is Free Software, based on Tor, Debian GNU/Linux, and the principal of security by isolation. As such, many of its security benefits come from running within virtual machines on a host operating system.

This Quick-Start Guide describes how to use Whonix on a Windows host system, however, it is important to understand that by design, Windows is not a secure host. [1] Whonix for Windows was designed to be a simple introduction, to enable people to experiment with Whonix in a familiar environment without the necessity of complex imports or OS switches.

As you learn how to use Whonix, do not forget that Windows cannot provide a secure foundation for Whonix.

Before getting started, read the Whonix System Requirements [2] and make sure your host system meets the requirements.

Download, verify and install Whonix

a) Download the installer. (Whonix-Installer for Windows)
https://download.whonix.org/windows/Whonix-Installer.exe

b) Verify the installer.

It is important to always check the integrity of software files downloaded from the internet, to ensure that the files are exactly as the developer intended and were not corrupted in any way. If the verification fails, Do Not Continue with this/these file(s). Delete the file(s) immediately, then re-download and verify the newly downloaded file(s).

The Whonix-Installer has been cryptographically signed using OpenPGP [3] by the creator of the Whonix-Installer, Ego. [4]

If you know how to use an OpenPGP key, download the signing key [5] and the Signature [6] straight away. Otherwise, follow these instructions: (Verify the Installer). https://www.whonix.org/wiki/Installer/Verify_the_Installer_using_the_command_line

c) Install Whonix.

( run as admin? )
Execute the verified Whonix-Installer.exe and follow its instructions. Please be careful to read the instructions in their entirety and make sure you understand everything. [7]

Please note: Due to the size of Whonix and the accompanying files, this may take up to half an hour.

d) Start using Whonix

You may now enjoy Whonix and all its features, either via Whonix.exe or Whonix for Windows, which you should find on your desktop or VirtualBox.

Install additional software

Whonix is made up of 3 main components, and when we’re talking of installing additional software, it’s important to make the distinction clear:

The host Operating System (OS) (The only host OS discussed in this document is MS Windows.) is the OS that hosts the virtual machines that make up the Whonix system. The host OS is not part of Whonix, and any additional software that runs on the host operating system will get no security, privacy, or anonymity benefit from Whonix running on the same machine.

The Whonix-Gateway runs in a virtual machine and only runs Tor, directing all internet traffic through Tor. Once Whonix is installed and configured, there should be no reason to modify anything on the gateway virtual machine.

The Whonix-Workstation virtual machine is where you reap all of the privacy/anonymity benefits of Whonix. Whonix comes with applications for various tasks, pre-installed by default. (See the Software [8] page for a list of these applications, software recommendations, safety advice, and installation instructions.) If you need to install additional software, the Whonix-Workstation virtual machine is where it must be installed. Also, note that the operating system of the Whonix-Workstation is Debian GNU/Linux, so any software to be run in the Whonix-Workstation must be able to run on the Debian GNU/Linux OS.

Security tips (Post install advice)

In the Whonix-Gateway and Whonix-Workstation virtual machines:

Change passwords for the “user” and “root” username accounts. [9]
Regularly check for security updates and apply them. [10]

Just as it’s important in Windows to “shut down” the system before turning off
or removing power from the machine, the Whonix-UI should always be used to
shut-down the Whonix system (virtual machines) in the most safe manner
possible.

Read the About [11], Warning [12] and Do Not [13] pages to make sure that Whonix is the right tool for you and you understand well its limitations.

[1] Computer Security Education - Whonix
[2] System Requirements - Whonix
[3] http://openpgp.org/
[4] Whonix Forum
[5] https://download.whonix.org/windows/ego.asc
[6] https://download.whonix.org/windows/Whonix-Installer.exe.asc
[7] Tips on Remaining Anonymous.
[8] Software - Kicksecure
[9] Post-installation Security Advice
[10] Security Guide - Whonix
[11] Whonix ™ - Anonymous Operating System
[12] Whonix ™ and Tor Limitations
[13] Tips on Remaining Anonymous

HulaHoop · January 26, 2017, 2:01am

Thanks for your effort @lwatts. However I think its still too long for a quickstart guide. The information must be extremely condensed and cover the most basic topics so beginners with low attention spans can focus and know just enough to get Whonix install off the ground.

torjunkie · January 26, 2017, 5:25am

Great job!

They are hard task masters around here, so I think HulaHoop is just referring to paring back any text to the absolute minimum, because I think you’ve covered all the necessary bases e.g. passwords, updates, verification with PGP etc.