Getting Started

When Granax is installed on Mac OSX or Windows platforms, it will automatically download a copy of the Tor Browser Bundle locally and use it - no configuration required! On GNU+Linux systems, Granax expects the tor package to be installed.

Granax will start Tor with a custom torrc file that can be found in lib/torrc.js, however if you prefer to use a custom torrc or a different Tor executable, follow this guide. This guide assumes you are running Debian or a derivitive, however it should translate easily to any other operating system.

Step 0: Install Tor

Use your system's package manager to install the latest Tor release:

sudo apt install tor

See https://www.torproject.org/docs/installguide.html.en

Step 1: Give User Access

On Debian systems, Tor is compartmentalized for security. You'll need to be able to read Tor's authentication cookie file. There are a couple ways to do this without running Granax as root.

Run your program as the debian-tor user:

sudo -u debian-tor /path/to/nodejs granax/examples/hidden-service.js

Add your user to the debian-tor group:

sudo adduser $USER debian-tor

Then log out and back in and Granax will be able to access Tor's control interface.

Step 2: Enable Tor's Control Interface

By default, Tor does not enable the control port, so you must enable it in your torrc file.

sudo vim /etc/tor/torrc

Don't know where your torrc is? See https://www.torproject.org/docs/faq#torrc

Find the section that contains the text below.

## The port on which Tor will listen for local connections from Tor
## controller applications, as documented in control-spec.txt.
#ControlPort 9051
## If you enable the controlport, be sure to enable one of these
## authentication methods, to prevent attackers from accessing it.
#HashedControlPassword 16:872860B76453A77D60CA2BB8C1A7042072093276A3D701AD684053EC4C
#CookieAuthentication 1

And uncomment ControlPort 9051 and CookieAuthentication 1.

## The port on which Tor will listen for local connections from Tor
## controller applications, as documented in control-spec.txt.
ControlPort 9051
## If you enable the controlport, be sure to enable one of these
## authentication methods, to prevent attackers from accessing it.
#HashedControlPassword 16:872860B76453A77D60CA2BB8C1A7042072093276A3D701AD684053EC4C
CookieAuthentication 1

Write the changes and restart Tor.

sudo /etc/init.d/tor restart

Step 3: Hack The Planet

Now that you have a running Tor, configured to allow your user to access it's control port, you can integrate Tor into your own packages using Granax!

const { connect } = require('net');
const { TorController } = require('granax');
const tor = new TorController(connect(9051));

tor.on('ready', function() {
  // Tor controller is ready!
});

Happy hacking!