Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Connecting to Tor
There are several options for how OnionShare might connect to Tor that are available in the Settings:
- Use Tor that is bundled with OnionShare
- Attempt automatic configuration with Tor Browser
- Connect using control port
- Connect using socket file
Use Tor that is bundled with OnionShare
This is the default way that OnionShare connects to Tor, and it's also the simplest and most reliable way. For this reason, it's recommended for most users.
When you open OnionShare, it will launch a Tor process in the background that's configured specifically for OnionShare to use. This Tor process won't interfere with other Tor processes on your computer, so you're free to run Tor Browser or use a system Tor in the background.
Attempt automatic configuration with Tor Browser
You can configure OnionShare to connect to the Tor that comes with Tor Browser. First, download Tor Browser here if you don't already have it. With this setting selected, you need to keep Tor Browser open in the background while you're using OnionShare.
Connect using control port or socket file
If you'd like, you can install Tor system-wide and configure OnionShare to connect to that. Or you can even connect to Tor that's running on a different operating system, for example if you'd like to run OnionShare in a Whonix workstation, where the Tor process itself runs in a Whonix gateway.
(Note that if your version of Tor is older than
0.2.7.1 it won't support ephemeral onion services, and if it's older than
0.2.9.8 it won't support stealth onion services. You always run the latest stable version of Tor, as opposed to old versions that might be in your operating system's package repository.)
Here are instructions for different operating systems:
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.
Download the Tor Expert Bundle for Windows. You can get the latest version from here (expand Microsoft Windows, and the Expert Bundle is right below Tor Browser). Extract the zip file, and copy the extracted folder to
C:\Program Files (x86)\, and rename the folder to
tor-win32, so that inside that folder is the
Make up a control port password. I'm going to use
comprised stumble rummage work avenging construct volatile as my password. Now open a command prompt as an administrator, and use
tor.exe --hash-password to generate a hash of your password. For example:
cd "C:\Program Files (x86)\tor-win32\Tor" tor.exe --hash-password "comprised stumble rummage work avenging construct volatile"
The hashed password output is displayed after some warnings (which you can ignore). In my case, it was
Now create a new text file at
C:\Program Files (x86)\tor-win32\torrc and put this in it, replacing the
HashedControlPassword with the one you just generated:
ControlPort 9051 HashedControlPassword 16:00322E903D96DE986058BB9ABDA91E010D7A863768635AC38E213FDBEF
In your administrator command prompt, install tor as a service using the appropriate
torrc file you just created (see here for more information on doing this). Like this:
tor.exe --service install -options -f "C:\Program Files (x86)\tor-win32\torrc"
You're now running a system Tor in Windows!
Open OnionShare. Click the Settings icon. Under "How should OnionShare connect to Tor?" choose "Connect using control port", and set the control port host to
127.0.0.1 and the port to
9051. Under "Tor authentication options" choose "Password" and set the password to your password, in my case
comprised stumble rummage work avenging construct volatile. Click the "Test Settings" button. If all goes well, you should see successfully connected to tor.
Using a system Tor in Mac OS X
First, install Homebrew if you don't already have it. Then, install Tor:
brew install tor
Now configure Tor to allow connections from OnionShare:
mkdir -p /usr/local/var/run/tor chmod 700 /usr/local/var/run/tor echo 'SOCKSPort 9050' >> /usr/local/etc/tor/torrc echo 'ControlPort unix:"/usr/local/var/run/tor/control.socket"' >> /usr/local/etc/tor/torrc
And start the system Tor service:
brew services start tor
Open OnionShare. Click the Settings icon. 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 options" choose "No authentication, or cookie authentication". Click the "Test Settings" button. If all goes well, you should see successfully connected to tor.
Using a system Tor in Linux
First, install the tor package. If you're using Debian, Ubuntu, or a similar Linux distro, I recommend you use Tor Project's official repository. For example, in Ubuntu 16.04:
sudo su -c "echo 'deb http://deb.torproject.org/torproject.org xenial main' > /etc/apt/sources.list.d/torproject.list" gpg --keyserver keys.gnupg.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add - sudo apt-get update sudo apt-get install -y tor deb.torproject.org-keyring
Next, add your user to the group that runs the Tor process (in the case of Debian and Ubuntu,
debian-tor) and configure OnionShare to connect to your system Tor's control socket file.
Add your user to the
debian-tor group by running this command (replace
username with your actual username):
sudo usermod -a -G debian-tor username
Reboot your computer. After it boots up again, open OnionShare. Click the Settings icon. Under "How should OnionShare connect to Tor?" choose "Connect using socket file", and set the socket file to be
/var/run/tor/control. Under "Tor authentication options" choose "No authentication, or cookie authentication". Click the "Test Settings" button. If all goes well, you should see successfully connect to Tor.
If you need to use Bridges to connect to Tor, please see this section