Page MenuHomePhabricator

Tunnel, VPN, proxy, SSH documentation needs to be restructured
Closed, ResolvedPublic

Description

Short Task Description:

See https://www.whonix.org/wiki/Features#VPN_.2F_Tunnel_support then use your brain and restructure it in a usable way. ;)


Details:

These pages are historically grown. When we started documenting this, we didn't know everything we know now. Knowing what we know now, we should restructure that knowledge so it can be easier understood by the user.

For example, https://www.whonix.org/wiki/Tunnel_Tor_through_proxy_or_VPN_or_SSH has an "introduction" chapter, that is supposed to be read by all, proxy, VPN and SSH tunnel users.

And https://www.whonix.org/wiki/Tunnel_Proxy_or_SSH_or_VPN_through_Tor has a "required knowledge" chapter that applies to all of these.

Also for VPN related stuff, these two pages are theoretical and for the practical part, we tell users to see the https://www.whonix.org/wiki/TestVPN page.

We also tell them for VPN related stuff "Fail Closed Mechanism", but instead of explaining how to do this to them, we link to other pages.

For better usability, these 3 pages (tunnel Tor through X + tunnel X through Tor + TestVPN) should be split into 6. Like this:

  • Tunnel Tor through proxy (user -> proxy -> Tor)
  • Tunnel Tor through SSH (user -> SSH -> Tor)
  • Tunnel Tor through VPN (user -> VPN -> Tor)
  • Tunnel proxy/proxychains through Tor (user -> Tor -> proxy)
  • Tunnel SSH through Tor (user -> Tor -> SSH)
  • Tunnel VPN through Tor (user -> Tor -> VPN)

Knowledge that applies to multiple tunnel scenarios should be moved to wiki templates and these templates should then be used where required.

Event Timeline

Patrick created this task.Feb 1 2015, 5:14 AM
Patrick raised the priority of this task from to Normal.
Patrick updated the task description. (Show Details)
Patrick added a project: user documentation.
Patrick added subscribers: Patrick, HulaHoop, JasonJAyalaP.

I'd like one page that briefly introduces two types of connections (tunnel before; tunnel after), with links to 6 pages for each configuration/setup.

Here's my rough draft of the intro page. Tell me if any technical details are wrong or unclear:


It is possible to combine Tor with tunnels and proxies such as VPN, Socks and SSH. Your traffic can be sent through both Tor and the second tunnel, in either order. However, this is an advanced topic and appropriate only for special cases. Adding a second connection does not automatically add security, but will add significant complexity. In fact, improper combination of Tor and another service may decrease your security and anonymity. For almost all users of Whonix, using Tor alone – without a VPN or proxy – is the right choice.

Connecting to a VPN or encrypted proxy before Tor

By first connecting to a VPN (or proxy) then connecting to Tor, your internet traffic will (1) pass through your ISP as encrypted VPN or proxy traffic; (2) exit your VPN server as encrypted Tor traffic; (3) enter to the Tor network; (4) exit the Tor network at a Tor exit node as normal internet traffic (encrypted or unencrypted).

Possible uses:

  • You must connect to your VPN or proxy to access the internet.
  • Your ISP blocks Tor and Tor bridges but doesn’t block VPNs or proxies. Your ISP doesn’t inspect VPN or proxy traffic for possible Tor connections.
  • Fear of de-anonymizing attacks against the Tor network; belief that your VPN is able to hide your identity in such case.

Warnings:

  • A VPN or proxy that knows your identity and/or location may be more willing and able to compromise your privacy than your ISP.
  • If your software configuration doesn’t block all traffic when your connection to your VPN or proxy suddenly disconnects, your Tor traffic will go through your ISP without warning.
  • HTTP, HTTPS, and Socks proxies are much less likely to hide your Tor traffic than VPNs.
  • If the use of Tor is dangerous in your area, VPNs and proxies may not provide enough protection.

Configuring a VPN before Tor
Configuring a Proxy before Tor
Configuring SSH before Tor

Connecting to a VPN or encrypted proxy after Tor

By first connecting to Tor, then to a VPN or proxy, your internet traffic will (1) pass through your ISP as encrypted Tor traffic; (2) exit the Tor network at a Tor exit node as encrypted VPN or proxy traffic; (3) exit your VPN or proxy as normal internet traffic (encrypted or unencrypted).

Possible uses:

  • As one component of using a VPN or proxy anonymously for some specific reason.
  • You must use Tor, but need to connect to an internet server who bans Tor exit nodes.

Warnings:

  • Even though Tor will hide your IP address from your VPN or proxy, you can still be located with your payment method, usages logs, or other identifying information the service knows about you.
  • You will not be able to access Tor hidden services.

Configuring a VPN after Tor
Configuring a Proxy after Tor
Configuring SSH after Tor

Looks good overall. A general overview page sounds very good. Feel free to create [temporary] wiki pages. After you're done we can simply move them where they really belong. [Just want to spare you from once writing the text using phabricator and one mediawiki markup.]

Since these introduction pages are often skipped by users, since they find the links elsewhere, these general info and warnings should be actually hosted in wiki templates. So these can be reused at the specific pages.

How to use wiki templates? Template:somepage. Add the text. Then import that template from a normal wiki page using {{tempalte-name}}. A random example:

Some minor technical points.

improper combination of Tor and another service may decrease your security and anonymity

I am certain, the "may" will generate inquiries. The 'may' should be a link. Or a footnote linking to https://trac.torproject.org/projects/tor/wiki/doc/TorPlusVPN should be added after that sentence.

encrypted proxy

That combination of words is problematic. Please have a look here:
https://www.whonix.org/wiki/Comparison_Of_Tor_with_CGI_Proxies,_Proxy_Chains,_and_VPN_Services

If your software configuration doesn’t block all traffic when your connection to your VPN or proxy suddenly disconnects, your Tor traffic will go through your ISP without warning.

Perhaps a footnote or something, that makes clear, that Whonix does not introduce this issue, the we're only documenting this mess that we did not create. Would be pointless if users therefore concluded "I not use Whonix then".

Configuring a Proxy before Tor

"before" is ambiguous because traffic flows in two directions. So many got this wrong.

By first connecting to Tor, then to a VPN or proxy

We should keep the current wordings in this style.

  • Connecting to a tunnel-link (proxy/VPN/SSH) before Tor
  • Connecting to a proxy before Tor

And also keep the connection schemes.

  • (User -> proxy/VPN/SSH -> Tor -> Internet)

To make sure no one can misunderstand. This has always been a source for major confusion.

While we're at it, we could also consider a page hierarchy. Such as:

https://www.whonix.org/wiki/Configure_VPN_before_Tor

A made the "VPN before Tor" page. The last part (configure whonix-gateway) was copy and pasted from the original page. I'll revisit those instructions once all the pages are in place.

I like the page heirarchy idea. Is that how you want it? Maybe "Tunnels" instead?

Tunnels/Introduction
Tunnels/VPN_Before_Tor
Tunnels/SSH_After_Tor

or

Tunnel/VPN/Before_Tor
Tunnel/SSH/After_Tor

?

The before and after is ambiguous.

It all comes down to one's perspective. i.e. am I talking about the
tunnel-link being "behind" Tor and therefore before it reaches my
internet destination (User -> x -> Tor -> Internet)? Or, am I talking
about the tunnel-link being "behind" Tor before the data reaches me?
(User -> Tor -> X -> Internet)

That's why it was changed to.

  • Connecting to a tunnel-link (proxy/VPN/SSH) before Tor
  • Connecting to a VPN before Tor
  • Connecting to Tor before a tunnel-link
  • Connecting to Tor before a VPN

When "before" is coupled with "connecting", it makes it rather obvious
that one is speaking from the mindset of the [User] connecting to [X]
before [i.e. connecting to X first, and then connecting to] Y.

Hierarchy proposal:

  • Tunnels/Connecting_to_a_VPN_before_Tor
  • Tunnels/Connecting to_Tor_before_a_VPN

JasonJAyalaP (Jason J. Ayala P.):

https://www.whonix.org/wiki/Tunnels/Connecting_to_Tor_before_a_VPN/Examples

Should just be https://www.whonix.org/wiki/Tunnels/Examples for now,
since these examples aren't tied to Connecting_to_Tor_before_a_VPN.

(mediawiki has a page move function. At the top menu. action -> move)

JasonJAyalaP added a comment.EditedDec 9 2015, 1:10 AM

EDIT: Oh wait, I see. The riseup example is about connecting to a VPN, before or after.

Original:
The rise-up example on VPN/Examples is about Tor_before_a_VPN, and it's longer than most of the individual tunnel pages. When we have one or multiple proxy_before_Tor example(s), you'd rather have them on the same long page as the rise-up Tor_before_a_VPN example than on "proxy_before_Tor/Examples" ?

https://www.whonix.org/wiki/Tunnels/Introduction
https://www.whonix.org/wiki/Tunnels/Connecting_to_a_VPN_before_Tor
https://www.whonix.org/wiki/Tunnels/Connecting_to_a_proxy_before_Tor
https://www.whonix.org/wiki/Tunnels/Connecting_to_SSH_before_Tor
https://www.whonix.org/wiki/Tunnels/Connecting_to_Tor_before_a_VPN
https://www.whonix.org/wiki/Tunnels/Connecting_to_Tor_before_a_proxy
https://www.whonix.org/wiki/Tunnels/Connecting_to_Tor_before_SSH
https://www.whonix.org/wiki/Tunnels/Examples

It still needs review for obvious stuff like in-page anchor links that were broken by page separation. I made a few editorial judgements, but nothing too drastic. The task of separation seems to be done. Can we close this topic? However, these pages could still need some minor formatting improvements (What's the markup to change the page title display?). And, of course, there is room for improvement generally speaking.

Patrick added a comment.EditedDec 9 2015, 3:08 AM

JasonJAyalaP (Jason J. Ayala P.):

(What's the markup to change
the page title display?).

One method would be to add

__NOTITLE__

at the very top. That magic word is hidden in the final html output and
will suppress the title.

If we want a title replacement, we should perhaps do that using html.
Just now created a template:
https://www.whonix.org/wiki/Template:Title

usage:

{{Title|
title=Connecting to a VPN before Tor
}}

Usage example:
https://www.whonix.org/wiki/Tunnels/Connecting_to_a_VPN_before_Tor

Do you have a rough list of editorial changes?

Comparison Table should be included in the introduction.

We also need SEO descriptions for all pages. (Most Whonix pages have them. See for comparison.)

{{#seo:
|description=Whonix Documentation. Crash Course in Anonymity and Security on the Internet.
}}

Shouldn't we somehow optically separate <references /> as done by other pages? (On other pages they have their own chapter.) It doesn't have to be its own chapter, but just writing them at the page end without and optical separation seems wrong.

Looks good overall.

Once that is sorted out, and [anchor] links and https://www.whonix.org/wiki/Features#VPN_.2F_Tunnel_support is working... We move https://www.whonix.org/wiki/Using_Tunnels_with_Whonix to https://www.whonix.org/wiki/Deprecated/Using_Tunnels_with_Whonix. Then this ticket can be closed.

We still wouldn't have actionable, usable pages one can read and apply from top to bottom, but still a huge improvement over the previous mess.

JasonJAyalaP added a comment.EditedDec 12 2015, 3:37 AM

I added {{Title| and #seo to each page. (But some pages are showing the NOTITLE effect, some aren't.)

I copy-pasted the comparison table to the intro page.

I don't have a list of editorial judgements. Most were very minor. I think biggest was splitting out the details of 'https://www.whonix.org/wiki/Using_Tunnels_with_Whonix#Things_to_keep_in_mind_when_connecting_to_Tor_before_a_tunnel-link' to different pages (one point went to the introduction warnings, one point went to proxy pages... I think. Stuff like that).

optically separate <references /> ? I don't understand.

I linked "https://www.whonix.org/wiki/Features#VPN_.2F_Tunnel_support" to the new pages

I did a visual scan for anchor links in all 6 sub-pages, but only needed to correct one link.

This link is very odd though
https://www.whonix.org/wiki/Tunnels/Connecting_to_Tor_before_a_proxy#Generally

What exactly is "read first" ? And is the #introduction link susposed to be the info about fixing tor browser (and does it still have the bug?).

Which part of wiki/Documentation? The " Tunnel Support / Chaining Support " is using a template that I changed.

References is just a matter of putting

Footnotes

<references />

at the end of each page?

Fixed wiki/Documentation.

Yes.

The double title sux, but I haven't found out how to get rid of it yet. Perhaps some CSS trick ( https://www.whonix.org/wiki/Dev/CSS !!!) could get rid of the ugly titles on all wiki pages.

Patrick closed this task as Resolved.Dec 12 2015, 11:02 PM