tor-router/docs/rpc-methods.md

RPC Functions

The following functions are available via the RPC

queryInstances()

Returns an array containing information on the instances currently running under the router.

queryInstanceByName(instance_name: String)

Returns information on an instance identified by name

queryInstancesByGroup(instance_name: String)

Returns an array containing information on the instances within a group.

queryInstanceAt(instance_index: Integer)

Returns information on an instance identified by index.

queryInstanceNames()

Returns a list of all instance names.

queryGroupNames()

Returns a list of all instance groups.

addInstanceToGroupByName(group: String, instance_name: String)

Adds an instance, identified by name, to a group

addInstanceToGroupAt(group: String, instance_index: Integer)

Adds an instance, identified by index, to a group

removeInstanceFromGroupByName(group: String, instance_name: String)

Removes an instance, identified by name, from a group

removeInstanceFromGroupAt(group: String, instance_index: Integer)

Removes an instance, identified by index, from a group

createInstances(instances: Array or Integer)

If passed an Integer, creates that many Tor instances. An array can also be passed describing the names, weights and configurations of prospective instances. :

var rpcRequest = {
	"method": "createInstances",
	"params": [
		{
			"Config": {

			},
			"Name": "instance-1",
			"Weight": 10
		},
		...
	], 
	"jsonrpc":"2.0", 
	"id": 1
};

Will wait until the Tor Instance has fully connected to the network before returning

addInstances(instances: Array)

Serves the same purpose as "createInstances" but only takes an Array

removeInstances(instances: Integer)

Removes a number of instances

removeInstanceAt(instance_index: Integer)

Remove a specific instance from the pool by its index

removeInstanceByName(instance_name: String)

Remove a specific instance from the pool by its name

newIdentites()

Get new identites for all instances

newIdentityAt(instance_index: Integer)

Get a new identity for a specific instance by its index

newIdentityByName(instance_name: String)

Get a new identity for a specific instance by its name

newIdentitiesByGroup(group: String)

Get new identities for all instances in a group

nextInstance()

Cycle to the next instance using the load balancing method

closeInstances()

Shutdown all Tor instances

setTorConfig(config: Object)

Apples the provided configuration to all instances using the control protocol. Changes will be applied immediately.

setTorConfigByGroup(group: String, config: Object)

Apples the provided configuration to all instances in a group using the control protocol. Changes will be applied immediately.

getConfig(key: String)

Retrieve a value from application configuration.

setConfig(key: String, value: Any)

Sets a value in application configuration.

saveConfig()

If the application was started using a config file will save the current configuration.

loadConfig()

If the application was started using a config file will load the configuration from the config file.

getLoadBalanceMethod()

Get the current load balance method

setLoadBalanceMethod(load_balance_method: String)

Set the current load balance method

getInstanceConfigAt(instance_index: Integer, keyword: String)

Retrieves the current value of an option set in the configuration by the index of the instance using the control protocol.

Example:

The following would retrieve the path to the data directory of the instance

var rpcRequest = {
	"method": "getInstanceConfigAt",
	"params": [0, "DataDirectory"], 
	"jsonrpc":"2.0", 
	"id": 1
};

getInstanceConfigByName(name: String, keyword: String)

Works the same way as getInstanceConfigAt except takes an instance name instead of an index

setInstanceConfigAt(index: Integer, keyword: String, value: String)

Sets the value in the configuration of an instance using the control protocol. Changes will be applied immediately.

setInstanceConfigByName(index: Integer, keyword: String, value: String)

Works the same way as setInstanceConfigAt except takes an instance name instead of an index

signalAllInstances(signal: String)

Sends a signal using the control protocol to all instances

A list of all signals can be found here

signalInstancesByGroup(group: String, signal: String)

Sends a signal using the control protocol to all instances in a group

signalInstanceAt(index: Integer, signal: String)

Sends a signal using the control protocol to an instance identified by its index

signalInstanceByName(name: String, signal: String)

Sends a signal using the control protocol to an instance identified by its name