tlaloc
v0.3.1
Published
Tor proxy management cluster server
Downloads
3
Maintainers
Readme
Tlaloc
Tlaloc is a decentralized Tor cluster server. It helps you create multiple tor processes across servers, and manage them at scale using a central Redis pub/sub interface.
It exposes a redis pub/sub communication channel for exposing available tor hidden service running in the cluster. It also lets you lock into a particular proxy, ensuring you are the only owner of that IP.
Requirements
A Tor client. Tor is available for a multitude of systems.
On OSX you can install with homebrew
brew install tor
tor # This should start the tor process
On Windows download the tor expert bundle (not the browser), unzip it and run tor.exe.
./Tor/tor.exe # This should start the tor process
See TorProject.org for linux bundles and detailed installation guides for all platforms. Make sure not to install the browser, but the tor standalone command.
Setup
Install Tor. Make sure "Tor" is in your $PATH
, try running "tor" in the terminal to confirm it.
Then install Tlaloc
npm install -g tlaloc
Usage
Cluster server
$ tlaloc --help
Usage: tlaloc [options]
Options:
-h, --help output usage information
-V, --version output the version number
-i, --instances <instances> number of tor processes to run. Default: 4
-d, --data-dir <dataDir> data dir to use for the tor processes. Default: "currentDir + /tordata"
-hn, --host <host> IP address or hostname of this server. Default: "127.0.0.1"
-p, --port <portRangeStart> starting port to start binding tor on. Default: 10770
-rp, --redis-port <redisPort> redis port. Default: 6379
-rh, --redis-host <redisHost> redis host. Default: "127.0.0.1"
Examples:
Start Tlaloc using a specified data dir:
$ tlaloc --data-dir ~/tordata
Use a redis pub/sub located in a remote host:
$ tlaloc -rp 6779 -rh myredis.somedomain.com
Starts with 30 Tor processes, providing 30 different random IPs:
$ tlaloc -i 30
Starts with 30 Tor processes, exposes this server hostname to clients
$ tlaloc -i 30 --host cluster1.mydomain.com
The default options are:
{
dataDir: '/var/tmp' or '/tmp' or `${process.cwd()}/data`,
torInstances: 4,
host: '127.0.0.1',
port: 10700
redis: {
port: 6379,
host: '127.0.0.1'
}
}
You can also configure tlaloc with environmental variables:
TLALOC_TOR_INSTANCES="20" # Sets the number of tor processes
TLALOC_DATADIR="/var/tmp" # Sets the data directory
TLALOC_HOST="cluster1.mydomain.com" # Sets the cluster hostname
TLALOC_PORT="10900" # Sets the starting port range
TLALOC_REDIS_HOST="127.0.0.1" # Sets the redis host
TLALOC_REDIS_PORT="6379" # Sets the redis host
# Then, you can just run "tlaloc" and these options will be used
# Scaling horizontally is better done through environmental variables
Tlaloc will start a cluster of tor processes, write a dedicated torrc files in the data directory, create a connection to the central redis pub/sub interface, and start listening for proxy requests.
It will serve tor proxy endpoints on request via the redis publish/subscribe flow. You can use the client in 'tlaloc/client' to easily request a proxy from the tor pool in the redis pub/sub, as described below.
Client library
Install tlaloc locally in your project
npm install --save tlaloc
Use it in your code
import Client from 'tlaloc/client';
const client = new Client();
// these are the defaults
const redisConfig = {
host: '127.0.0.1',
port: 6379
}
client.connect(redisConfig)
.then(() => client.getProxy())
.then((proxy) => {
console.log(proxy.host); // the host of the tor cluster
console.log(proxy.port); // the port bound to the remote tor instance
console.log(proxy.active); // The tor host is still alive
// Now use this host and port to make requests through a socks5 proxy
// eg. using the 'socks5-https-client' module
const shttp = require('socks5-https-client');
shttp.get({
hostname: 'api.ipify.org',
socksHost: proxy.host,
socksPort: proxy.port,
path: '/',
rejectUnauthorized: false
}, (res) => {
res.setEncoding('utf8');
res.on('readable', () => {
console.log(`My tor IP is ${res.read()}`);
}
});
});
Scaling
Tlaloc is designed to allow for easy horizontal scaling. There's no central server managing the clusters, so in order to increase the available tor proxies in the pool, you just need to start more Tlaloc clusters in different servers, and configure them to use the same redis pub/sub interface.
You have to make sure to expose each server's IP addresses correctly through TLALOC_HOST (or the command-line option). Failing to do so will make the clusters expose themselves without their IP address, and clients won't be able to reach the proxies.
Tests
mocha
Cheers.