Class: TorController

Constructor

new TorController(socket, optionsopt)

Parameters:

Name Type Attributes Description

socket

Socket

net.Socket connected to Tor's control port

options

object

Properties

Name	Type	Attributes	Default	Description
`authOnConnect`	boolean	<optional>	true	Automatically authenticate

Source: lib/controller.js, line 16

Methods

(static) createChallengeResponse(cookie, clientNonce, serverNonce) → {string}

Creates the challenge response from a SAFECOOKIE challenge

Parameters:

Name	Type	Description
`cookie`	string	The secret cookie string
`clientNonce`	string	Client nonce sent with auth challenge
`serverNonce`	string	Server nonce reply from auth challenge

Source: lib/controller.js, line 29

Returns:

Type:: string

(static) createReplySplitter()

Creates a message splitter from incoming socket data

Source: lib/controller.js, line 43

addEventListeners(events, callback)

Instructs Tor to send asynchronous events for the given types - these events will be emitted from the controller. Calling this method resets previously set event listeners

Parameters:

Name	Type	Description
`events`	Array.<string>	List of event types to listen for
`callback`	TorController~addEventListenersCallback

Source: lib/controller.js, line 807
See: https://gitweb.torproject.org/torspec.git/tree/control-spec.txt#n1708

attachStream(streamId, circuitIdopt, hopNumberopt, callback)

Attaches the specified stream to the given circuit

Parameters:

Name	Type	Attributes	Default	Description
`streamId`	string			ID for the stream to attach
`circuitId`	string	<optional>	0	Circuit to attach stream
`hopNumber`	number	<optional>		Which hop to exit circuit
`callback`	TorController~attachStreamCallback

Source: lib/controller.js, line 565

authenticate(token, callback)

Authenticates with the control port given the supplied param

Parameters:

Name	Type	Description
`token`	string
`callback`	TorController~authenticateCallback

Source: lib/controller.js, line 269

cleanCircuits(callback)

Clears DNS cache and establishes new clean circuits

Parameters:

Name	Type	Description
`callback`	TorController~cleanCircuitsCallback

Source: lib/controller.js, line 463

clearDnsCache(callback)

Forget client side hostname->ip cache

Parameters:

Name	Type	Description
`callback`	TorController~clearDnsCacheCallback

Source: lib/controller.js, line 451

closeCicuit(circuitId, optionsopt, callback)

Closes the given circuit

Parameters:

Name Type Attributes Description

circuitId

string

ID for the circuit to close

options

object

Properties

Name	Type	Attributes	Default	Description
`ifUnused`	boolean	<optional>	false	Only close if not in use

callback TorController~closeCircuitCallback

Source: lib/controller.js, line 650

closeStream(streamId, reasonopt, callback)

Closes the exit for the given stream

Parameters:

Name	Type	Attributes	Default	Description
`streamId`	string			ID for the stream to close
`reason`	number	<optional>	1	Reason code for closing stream
`callback`	TorController~closeStreamCallback

Source: lib/controller.js, line 629
See: https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt#n1404

createAddressMapping(target, replacement, callback)

Instruct Tor to route requests to the target to the replacement

Parameters:

Name	Type	Description
`target`	string	Original address to map
`replacement`	string	New address to route request to target
`callback`	TorController~createAddressMappingCallback

Source: lib/controller.js, line 502

createCircuit(purposeopt, callback)

Creates a new circuit, returning the newly created circuit ID

Parameters:

Name	Type	Attributes	Default	Description
`purpose`	string	<optional>	"general"	The circuit purpose, either general\|controller
`callback`	TorController~createCircuitCallback

Source: lib/controller.js, line 515

createHiddenService(ports, optionsopt, callback)

Establishes a hidden service on the given target

Parameters:

Name	Type	Attributes	Description
`ports`	array		Array containing optional virtualPort (defaults to 80) and target ip:port string
`options`	object	<optional>	module:commands#ADD_ONION
`callback`	TorController~createHiddenServiceCallback

Source: lib/controller.js, line 306

destroyHiddenService(serviceId, callback)

Takes down a running hidden service owned by this controller

Parameters:

Name	Type	Description
`serviceId`	string	Tor hidden service ID
`callback`	TorController~destroyHiddenServiceCallback

Source: lib/controller.js, line 326

dropGuards(callback)

Tells the server to drop all guard nodes. Do not invoke this command lightly; it can increase vulnerability to tracking attacks over time.

Parameters:

Name	Type	Description
`callback`	TorController~dropGuardsCallback

Source: lib/controller.js, line 735

dumpHeartbeat(callback)

Dumps a heartbeat message to the logs

Parameters:

Name	Type	Description
`callback`	TorController~dumpHeartbeatCallback

Source: lib/controller.js, line 475

dumpStats(callback)

Dump stats to tor log file

Parameters:

Name	Type	Description
`callback`	TorController~dumpStatsCallback

Source: lib/controller.js, line 415

enableDebug(callback)

Set open logs to debug level

Parameters:

Name	Type	Description
`callback`	TorController~enableDebugCallback

Source: lib/controller.js, line 427

extendCircuit(circuitId, callback)

Extends the existing circuit

Parameters:

Name	Type	Description
`circuitId`	string	The circuit ID to extend
`callback`	TorController~extendCircuitCallback

Source: lib/controller.js, line 535

fetchHiddenServiceDescriptor(serviceId, serverLongNameopt, callback)

Fetches descriptors for the given hidden service

Parameters:

Name	Type	Attributes	Description
`serviceId`	string		ID for the hidden service
`serverLongName`	string	<optional>	Long name for specific server to use
`callback`	TorController~fetchHiddenServiceDescriptorCallback

Source: lib/controller.js, line 749

getAuthChallenge(nonce, callback)

Requests an authentication challenge from tor

Parameters:

Name	Type	Description
`nonce`	string	Client nonce for authenticating
`callback`	TorController~getAuthChallengeCallback

Source: lib/controller.js, line 278

getConfig(keyword, callback)

Return the values for the given configuration key

Parameters:

Name	Type	Description
`keyword`	string	Configuration key
`callback`	TorController~getConfigCallback

Source: lib/controller.js, line 366

getInfo(keyword, callback)

Get information from Tor not stored in configuration

Parameters:

Name	Type	Description
`keyword`	string	Keyword for info to fetch
`callback`	TorController~getInfoCallback

Source: lib/controller.js, line 790
See: https://gitweb.torproject.org/torspec.git/tree/control-spec.txt#n500

getProtocolInfo(callback)

Ask tor for general information

Parameters:

Name	Type	Description
`callback`	TorController~getProtocolInfoCallback

Source: lib/controller.js, line 291

halt(callback)

Shutdown tor immediately

Parameters:

Name	Type	Description
`callback`	TorController~haltCallback

Source: lib/controller.js, line 439

loadConfig(configText, callback)

Instruct Tor to load the configuration file from the given text

Parameters:

Name	Type	Description
`configText`	string	Complete torrc config text to load
`callback`	TorController~loadConfigCallback

Source: lib/controller.js, line 702

postDescriptor(descriptor, optionsopt, callback)

Inform the server about a new descriptor

Parameters:

Name Type Attributes Description

descriptor

object

Key-value pairs for server descriptor

options

object

Properties

Name	Type	Attributes	Default	Description
`purpose`	string	<optional>	"general"	general\|controller\|bridge
`cache`	boolean	<optional>	true	Flag for caching descriptor

callback TorController~postDescriptorCallback

Source: lib/controller.js, line 587

postHiddenServiceDescriptor(descriptor, serverLongNameopt, callback)

Launch a hidden service descriptor upload

Parameters:

Name	Type	Attributes	Description
`descriptor`	string
`serverLongName`	string	<optional>	Long name for specific server to use
`callback`	TorController~postHiddenServiceDescriptorCallback

Source: lib/controller.js, line 770
See: https://gitweb.torproject.org/torspec.git/tree/rend-spec.txt#n193

quit(callback)

Tells Tor to hang up on the controller

Parameters:

Name	Type	Description
`callback`	TorController~quitCallback

Source: lib/controller.js, line 668

redirectStream(streamId, address, portopt, callback)

Change the exit address on a given stream

Parameters:

Name	Type	Attributes	Description
`streamId`	string		ID for stream to redirect
`address`	string		Exit address for the given stream
`port`	number	<optional>	Exit port for the given stream
`callback`	TorController~redirectStreamCallback

Source: lib/controller.js, line 608

reloadConfig(callback)

Reloads the config values set

Parameters:

Name	Type	Description
`callback`	TorController~reloadConfigCallback

Source: lib/controller.js, line 391

removeEventListeners(callback)

Instructs Tor to stop listening for events

Parameters:

Name	Type	Description
`callback`	TorController~removeEventListenersCallback

Source: lib/controller.js, line 819

resetConfig(keyword, callback)

Change the value for a configuration variable to it's default

Parameters:

Name	Type	Description
`keyword`	string	Configuration key
`callback`	TorController~resetConfigCallback

Source: lib/controller.js, line 353

resolve(address, optionsopt, callback)

Launch remote hostname lookup - answer returnd as async ADDRMAP event

Parameters:

Name Type Attributes Description

address

string

Address to lookup

options

object

Properties

Name	Type	Attributes	Default	Description
`reverse`	boolean	<optional>	false	Perform reverse lookup

callback TorController~resolveCallback

Source: lib/controller.js, line 683

saveConfig(callback)

Tell Tor to write out it's config value to it's torrc

Parameters:

Name	Type	Description
`callback`	TorController~saveConfigCallback

Source: lib/controller.js, line 379

setCircuitPurpose(circuitId, purpose, callback)

Sets the purpose of the given circuit

Parameters:

Name	Type	Description
`circuitId`	string	The identifier for the circuit
`purpose`	string	One of general\|controller
`callback`	TorController~setCircuitPurposeCallback

Source: lib/controller.js, line 550

setConfig(keyword, value, callback)

Change the value for a configuration variable

Parameters:

Name	Type	Description
`keyword`	string	Configuration key
`value`	string	New value to set
`callback`	TorController~setConfigCallback

Source: lib/controller.js, line 340

shutdown(callback)

Controlled shutdown signal

Parameters:

Name	Type	Description
`callback`	TorController~shutdownCallback

Source: lib/controller.js, line 403

signal(signal, callback)

Sends a signal to the control port

Parameters:

Name	Type	Description
`signal`	string
`callback`	TorController~signalCallback

Source: lib/controller.js, line 488

takeOwnership(callback)

Take ownership of the tor process - will close tor when the connection closes

Parameters:

Name	Type	Description
`callback`	TorController~takeOwnershipCallback

Source: lib/controller.js, line 715

Type Definitions

addEventListenersCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 810

attachStreamCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 574

cleanCircuitsCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 466

clearDnsCacheCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 454

closeCircuitCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 659

closeStreamCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 638

createAddressMappingCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 505

createCircuitCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	Array.<string>

Source: lib/controller.js, line 524

createHiddenServiceCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	AddOnionResult

Source: lib/controller.js, line 315

destroyHiddenServiceCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 329

dropGuardsCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 738

dumpHeartbeatCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 478

dumpStatsCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 418

enableDebugCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 430

extendCircuitCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	Array.<string>

Source: lib/controller.js, line 538

fetchHiddenServiceDescriptorCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 758

getAuthChallengeCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	AuthChallengeResult

Source: lib/controller.js, line 281

getConfigCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	GetConfigResult

Source: lib/controller.js, line 369

getInfoCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	string

Source: lib/controller.js, line 793

getProtocolInfoCallback(error, result)

Parameters:

Name	Type	Description
`error`	object \| null
`result`	ProtocolInfoResult

Source: lib/controller.js, line 294

haltCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 442

loadConfigCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 705

postDescriptorCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 596

postHiddenServiceDescriptorCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 779

quitCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 671

redirectStreamCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 617

reloadConfigCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 394

resetConfigCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 356

resolveCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 692

saveConfigCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 382

setCircuitPurposeCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 553

setConfigCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 343

shutdownCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 406

signalCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 491

takeOwnershipCallback(error)

Parameters:

Name	Type	Description
`error`	object \| null

Source: lib/controller.js, line 725

Events

close

Fires when the underlying socket closes

Source: lib/controller.js, line 75

error

Fired when the underlying socket encounters an error

Type:

error

Source: lib/controller.js, line 64

ready

Fires when the controller is authenticated and ready to send commands

Source: lib/controller.js, line 70