mirror of
https://github.com/onionshare/onionshare.git
synced 2025-01-24 18:22:58 -03:00
Merge the automatic censorship circumvention docs with the tor settings docs
This commit is contained in:
Micah Lee
parent
a8b8414482
commit
96024de4b8
7 changed files with 70 additions and 87 deletions
BIN
docs/source/_static/screenshots/autoconnect-select-country.png
Normal file
BIN
docs/source/_static/screenshots/autoconnect-select-country.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 95 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 79 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 103 KiB After Width: | Height: | Size: 112 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 44 KiB After Width: | Height: | Size: 64 KiB |
|
|
@ -1,69 +0,0 @@
|
|||
Getting connected to Tor
|
||||
========================
|
||||
|
||||
When OnionShare starts, it will show you a screen asking you to connect to the Tor network.
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-welcome-screen.png
|
||||
|
||||
You can click "Connect to Tor" to begin the connection process. If there are no problems with your network, including any attempts to block your access to the Tor network, this should hopefully work the first time.
|
||||
|
||||
Or, if you want to manually configure Bridges or other Tor settings before you connect, you can click "Network Settings".
|
||||
|
||||
Automatic censorship circumvention
|
||||
----------------------------------
|
||||
|
||||
When OnionShare fails to connect to Tor, it might be because Tor is censored in your country or on your local network.
|
||||
|
||||
If this occurs, you will have these choices:
|
||||
|
||||
- Try again without a bridge
|
||||
- Automatically determine my country from my IP address for bridge settings
|
||||
- Manually select my country for bridge settings
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-failed-to-connect.png
|
||||
|
||||
Here's what each option does.
|
||||
|
||||
Try again without a bridge
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This will retry the normal OnionShare connection attempt to Tor without attempting to bypass censorship.
|
||||
|
||||
Automatically determine my country from my IP address for bridge settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This will attempt to automatically bypass censorship. It works by using Tor bridges.
|
||||
If your network provider is blocking access to the Tor network, you can hopefully still connect to a Tor bridge, which will then connect you to the Tor network.
|
||||
|
||||
This option uses the Tor Project's Censorship Circumvention API to determine your country and, based on that, provide you with bridge settings that should work for you.
|
||||
OnionShare will temporarily use the `Meek <https://gitlab.torproject.org/legacy/trac/-/wikis/doc/meek/>`_ domain-fronting proxy to make a non-Tor connection from your computer to Tor's Censorship Circumvention API. The Meek proxy hides the fact that you are trying to find a way to connect to Tor.
|
||||
The Censorship Circumvention API will consider your IP address (yes, your real IP address) to determine what country you might reside in.
|
||||
Based on the country information, the API will try to automatically find bridges that suit your location.
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-trying-to-resolve-connectivity-issues.png
|
||||
|
||||
(add another screenshot of it connecting more successfully)
|
||||
|
||||
Manually select my country for bridge settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Just live the previous option, this will attempt to bypass censorship using Tor Project's Censorship API. But rather than the API determining your country from your IP address, it will fetch bridges for the country that you specified.
|
||||
|
||||
If it finds any such bridges, OnionShare will try to reconnect to Tor using those bridges.
|
||||
|
||||
If the API does not find any bridges for your location, OnionShare will ask the API for "fallback" options. At the time of writing, this is likely to be the obfs4 built-in bridges.
|
||||
|
||||
OnionShare will also attempt to use the obfs4 built-in bridges if for some reason it could not connect to the API itself, or the API returned an error.
|
||||
|
||||
It's important to note that the requests to the Censorship Circumvention API do not go over the Tor Network (because if you could connect to Tor already, you wouldn't need to connect to the API).
|
||||
|
||||
Even though it is hard for an adversary to discover where the Meek request is going, this may still be risky for some users. Therefore, it is an opt-in feature. The use of Meek and non-torified network requests are limited only to making one or two requests to the Censorship Circumvention API. Then Meek is stopped, and all further network requests happen over the Tor network.
|
||||
|
||||
If you are uncomfortable with making a request that doesn't go over the Tor network, you can click the Network Settings (or the Settings icon in the bottom right corner, followed by the Tor Settings tab in the screen that appears), and manually configure bridges. After you save any bridge settings, OnionShare will try to reconnect using those bridges.
|
||||
|
||||
Connect to Tor automatically
|
||||
----------------------------
|
||||
|
||||
You can toggle on the switch "Connect to Tor automatically" before clicking "Connect to Tor". This means that next time OnionShare starts, it will automatically connect with its Tor connection settings from the last session, instead of presenting you with the connection options.
|
||||
|
||||
If the connection fails, you can still try bridges or reconfigure Tor via the "Network Settings" button.
|
||||
|
|
@ -9,10 +9,9 @@ OnionShare is an open source tool that lets you securely and anonymously share f
|
|||
:maxdepth: 2
|
||||
|
||||
install
|
||||
connecting
|
||||
tor
|
||||
features
|
||||
advanced
|
||||
tor
|
||||
help
|
||||
security
|
||||
develop
|
||||
|
|
|
|||
|
|
@ -1,14 +1,71 @@
|
|||
Connecting to Tor
|
||||
=================
|
||||
|
||||
.. _tor:
|
||||
When OnionShare starts, it will show you a screen asking you to connect to the Tor network.
|
||||
|
||||
Pick a way to connect OnionShare to Tor by clicking the Settings icon in the bottom right corner of the application, and then the Tor Settings tab in the screen that appears.
|
||||
.. image:: _static/screenshots/autoconnect-welcome-screen.png
|
||||
|
||||
You can toggle on the switch "Connect to Tor automatically" before clicking "Connect to Tor". This means that next time OnionShare starts, it will automatically connect with its Tor connection settings from the last session, instead of presenting you with the connection options.
|
||||
If the connection fails, you can still try bridges or reconfigure Tor via the "Network Settings" button.
|
||||
|
||||
You can click "Connect to Tor" to begin the connection process. If there are no problems with your network, including any attempts to block your access to the Tor network, this should hopefully work the first time.
|
||||
|
||||
Or, if you want to manually configure Bridges or other Tor settings before you connect, you can click "Network Settings".
|
||||
|
||||
Automatic censorship circumvention
|
||||
----------------------------------
|
||||
|
||||
When you click "Connect to Tor", if OnionShare fails to connect, it might be because Tor is censored in your country or on your local network.
|
||||
|
||||
If this occurs, you will have these choices:
|
||||
|
||||
- Try again without a bridge
|
||||
- Automatically determine my country from my IP address for bridge settings
|
||||
- Manually select my country for bridge settings
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-failed-to-connect.png
|
||||
|
||||
If you choose the "Try again without a bridge" option, OnionShare will retry connecting to Tor like normal, without attempting to bypass censorship.
|
||||
|
||||
The other two options will attempt to automatically bypass censorship using Tor bridges.
|
||||
If your network provider is blocking access to the Tor network, you can hopefully still connect to a Tor bridge, which will then connect you to the Tor network, circumventing the censorship.
|
||||
Both of these options use the Tor Project's Censorship Circumvention API to provide you with bridge settings that should work for you.
|
||||
OnionShare will temporarily use the `Meek <https://gitlab.torproject.org/legacy/trac/-/wikis/doc/meek/>`_ domain-fronting proxy to make a non-Tor connection from your computer to Tor's Censorship Circumvention API.
|
||||
The Meek proxy hides the fact that you are trying to find a way to connect to Tor.
|
||||
|
||||
If you choose "Automatically determine my country from my IP address for bridge settings", the Censorship Circumvention API will consider your IP address (yes, your real IP address) to determine what country you might reside in.
|
||||
Based on the country information, the API will try to automatically find bridges that suit your location.
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-trying-to-resolve-connectivity-issues.png
|
||||
|
||||
If you choose "Manually select my country for bridge settings", the Censorship API will find the bridges that suit the country that you specified.
|
||||
|
||||
.. image:: _static/screenshots/autoconnect-select-country.png
|
||||
|
||||
How automatic censorship circumvention works
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If the Censorship Circumvention API finds bridges that it believes will suit you, OnionShare will try to reconnect to Tor using those bridges. If the API does not find any bridges for your location, OnionShare will ask the API for "fallback" options, and then try to reconnect using those.
|
||||
|
||||
If for some reason OnionShare fails to connect to the Censorship API itself, or if the API returns an error message, OnionShare will attempt to use the obfs4 built-in bridges.
|
||||
|
||||
It's important to note that the requests to the Censorship Circumvention API do not go over the Tor network (because if you could connect to Tor already, you wouldn't need to connect to the API).
|
||||
|
||||
Even though it's hard for an adversary to discover where the Meek request is going, this may still be risky for some users. Therefore, it is an opt-in feature. The use of Meek and non-torified network requests are limited only to making one or two requests to the Censorship Circumvention API. Then Meek is stopped, and all further network requests happen over the Tor network.
|
||||
|
||||
If you are uncomfortable with making a request that doesn't go over the Tor network, you can click "Network Settings" (or the Settings icon in the bottom right corner, followed by the Tor Settings tab in the screen that appears), and manually configure bridges. After you save any bridge settings, OnionShare will try to reconnect using those bridges.
|
||||
|
||||
Manually configure Tor settings
|
||||
-------------------------------
|
||||
|
||||
You can get to the Tor settings by clicking "Network Settings" on the welcome screen, or by clicking the "⚙" icon in the bottom-right corner of the application, and then switch to the Tor Settings tab in the screen that appears.
|
||||
|
||||
.. image:: _static/screenshots/tor-settings.png
|
||||
|
||||
Here are the different ways you can configure OnionShare to connect to Tor:
|
||||
|
||||
Use the Tor version built into OnionShare
|
||||
-----------------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This is the default, simplest and most reliable way that OnionShare connects to Tor.
|
||||
For this reason, it's recommended for most users.
|
||||
|
|
@ -16,13 +73,9 @@ For this reason, it's recommended for most users.
|
|||
When you open OnionShare, it launches an already configured ``tor`` process in the background for OnionShare to use.
|
||||
It doesn't interfere with other ``tor`` processes on your computer, so you can use the Tor Browser or the system ``tor`` on their own.
|
||||
|
||||
Getting Around Censorship
|
||||
-------------------------
|
||||
**Using bridges**
|
||||
|
||||
If your access to the internet is censored, you can configure OnionShare to connect to the Tor network using `Tor bridges <https://tb-manual.torproject.org/bridges/>`_. If OnionShare connects to Tor without one, you don't need to use a bridge.
|
||||
|
||||
To use a bridge, open the Tor Settings tab.
|
||||
You must select "Use the Tor version built into OnionShare" and check the "Use a bridge" checkbox.
|
||||
To use a bridge, you must select "Use the Tor version built into OnionShare" and check the "Use a bridge" checkbox.
|
||||
|
||||
Try using a built-in bridge first. Using `obfs4` or `snowflake` bridges is recommended over using `meek-azure`.
|
||||
|
||||
|
|
@ -35,13 +88,13 @@ If using a built-in bridge doesn't work, you can request a bridge from torprojec
|
|||
You also have the option of using a bridge that you learned about from a trusted source.
|
||||
|
||||
Attempt auto-configuration with Tor Browser
|
||||
-------------------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you have `downloaded the Tor Browser <https://www.torproject.org>`_ and don't want two ``tor`` processes running, you can use the ``tor`` process from the Tor Browser.
|
||||
Keep in mind you need to keep Tor Browser open in the background while you're using OnionShare for this to work.
|
||||
|
||||
Using a system ``tor`` in Windows
|
||||
---------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This is fairly advanced. You'll need to know how edit plaintext files and do stuff as an administrator.
|
||||
|
||||
|
|
@ -69,7 +122,7 @@ In your administrator command prompt, install ``tor`` as a service using the app
|
|||
|
||||
You are now running a system ``tor`` process in Windows!
|
||||
|
||||
Open OnionShare and click the "⚙" icon in it.
|
||||
Open OnionShare, click the "⚙" icon in it, and switch to the Tor Settings tab.
|
||||
Under "How should OnionShare connect to Tor?" choose "Connect using control port", and set
|
||||
"Control port" to ``127.0.0.1`` and
|
||||
"Port" to ``9051``.
|
||||
|
|
@ -78,7 +131,7 @@ Click the "Test Connection to Tor" button.
|
|||
If all goes well, you should see "Connected to the Tor controller".
|
||||
|
||||
Using a system ``tor`` in macOS
|
||||
-------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First, install `Homebrew <https://brew.sh/>`_ if you don't already have it, and then install Tor::
|
||||
|
||||
|
|
@ -95,7 +148,7 @@ And start the system Tor service::
|
|||
|
||||
brew services start tor
|
||||
|
||||
Open OnionShare and click the "⚙" icon in it.
|
||||
Open OnionShare, click the "⚙" icon in it, and switch to the Tor Settings tab.
|
||||
Under "How should OnionShare connect to Tor?" choose "Connect using socket file", and
|
||||
set the socket file to be ``/usr/local/var/run/tor/control.socket``.
|
||||
Under "Tor authentication settings" choose "No authentication, or cookie authentication".
|
||||
|
|
@ -104,7 +157,7 @@ Click the "Test Connection to Tor" button.
|
|||
If all goes well, you should see "Connected to the Tor controller".
|
||||
|
||||
Using a system ``tor`` in Linux
|
||||
-------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First, install the ``tor`` package. If you're using Debian, Ubuntu, or a similar Linux distro, It is recommended to use the Tor Project's `official repository <https://support.torproject.org/apt/tor-deb-repo/>`_.
|
||||
|
||||
|
|
@ -115,7 +168,7 @@ Add your user to the ``debian-tor`` group by running this command (replace ``use
|
|||
sudo usermod -a -G debian-tor username
|
||||
|
||||
Reboot your computer.
|
||||
After it boots up again, open OnionShare and click the "⚙" icon in it.
|
||||
After it boots up again, open OnionShare, click the "⚙" icon in it, and switch to the Tor Settings tab.
|
||||
Under "How should OnionShare connect to Tor?" choose "Connect using socket file".
|
||||
Set the socket file to be ``/var/run/tor/control``.
|
||||
Under "Tor authentication settings" choose "No authentication, or cookie authentication".
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue