2018-08-10 17:06:40 +00:00
# RPC Functions
2018-05-10 04:56:00 +00:00
The following functions are available via the RPC
2018-08-10 17:06:40 +00:00
## queryInstances()
2018-05-10 04:56:00 +00:00
Returns an array containing information on the instances currently running under the router.
2018-09-11 06:48:56 +00:00
## queryInstanceByName(instance_name: String)
2018-05-10 04:56:00 +00:00
2018-08-10 17:06:40 +00:00
Returns information on an instance identified by name
2018-09-11 06:48:56 +00:00
## queryInstancesByGroup(instance_name: String)
2018-08-10 17:06:40 +00:00
2018-09-11 06:48:56 +00:00
Returns an array containing information on the instances within a group.
2018-08-10 17:06:40 +00:00
2018-09-11 06:48:56 +00:00
## 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)
2018-08-10 17:06:40 +00:00
2018-09-10 04:53:06 +00:00
If passed an Integer, creates that many Tor instances. An array can also be passed describing the names, weights and configurations of prospective instances. :
2018-05-10 04:56:00 +00:00
```
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
2018-09-11 06:48:56 +00:00
## addInstances(instances: Array)
2018-05-10 04:56:00 +00:00
Serves the same purpose as "createInstances" but only takes an Array
2018-09-11 06:48:56 +00:00
## removeInstances(instances: Integer)
2018-05-10 04:56:00 +00:00
Removes a number of instances
2018-09-11 06:48:56 +00:00
## removeInstanceAt(instance_index: Integer)
2018-05-10 04:56:00 +00:00
2018-05-11 05:56:55 +00:00
Remove a specific instance from the pool by its index
2018-05-10 04:56:00 +00:00
2018-09-11 06:48:56 +00:00
## removeInstanceByName(instance_name: String)
2018-05-10 04:56:00 +00:00
2018-05-11 05:56:55 +00:00
Remove a specific instance from the pool by its name
2018-05-10 04:56:00 +00:00
2018-08-10 17:06:40 +00:00
## newIdentites()
2018-05-10 04:56:00 +00:00
2018-05-11 05:08:38 +00:00
Get new identites for all instances
2018-09-11 06:48:56 +00:00
## newIdentityAt(instance_index: Integer)
2018-05-11 05:08:38 +00:00
2018-05-11 05:56:55 +00:00
Get a new identity for a specific instance by its index
2018-05-11 05:08:38 +00:00
2018-09-11 06:48:56 +00:00
## newIdentityByName(instance_name: String)
2018-05-11 05:08:38 +00:00
2018-05-11 05:56:55 +00:00
Get a new identity for a specific instance by its name
2018-05-10 04:56:00 +00:00
2018-09-11 06:48:56 +00:00
## newIdentitiesByGroup(group: String)
Get new identities for all instances in a group
2018-08-10 17:06:40 +00:00
## nextInstance()
2018-05-10 04:56:00 +00:00
Cycle to the next instance using the load balancing method
2018-08-10 17:06:40 +00:00
## closeInstances()
2018-05-10 04:56:00 +00:00
Shutdown all Tor instances
2018-09-11 06:48:56 +00:00
## setTorConfig(config: Object)
Apples the provided configuration to all instances using the control protocol. Changes will be applied immediately.
## setTorConfigByGroup(group: String, config: Object)
2018-05-10 04:56:00 +00:00
2018-09-11 06:48:56 +00:00
Apples the provided configuration to all instances in a group using the control protocol. Changes will be applied immediately.
2018-05-10 04:56:00 +00:00
2018-08-10 17:06:40 +00:00
## getDefaultTorConfig()
2018-08-10 04:44:07 +00:00
Retrieve the default Tor Config for all future instances
2018-09-11 06:48:56 +00:00
## setDefaultTorConfig(config: Object)
2018-05-10 04:56:00 +00:00
2018-08-10 04:44:07 +00:00
Set the default Tor Config for all future instances
2018-05-10 04:56:00 +00:00
2018-08-10 17:06:40 +00:00
## getLoadBalanceMethod()
2018-05-10 04:56:00 +00:00
Get the current load balance method
2018-09-11 06:48:56 +00:00
## setLoadBalanceMethod(load_balance_method: String)
2018-05-10 04:56:00 +00:00
2018-05-11 05:56:55 +00:00
Set the current load balance method
2018-09-11 06:48:56 +00:00
## getInstanceConfigAt(instance_index: Integer, keyword: String)
2018-05-11 05:56:55 +00:00
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
};
```
2018-09-11 06:48:56 +00:00
## getInstanceConfigByName(name: String, keyword: String)
2018-05-11 05:56:55 +00:00
Works the same way as `getInstanceConfigAt` except takes an instance name instead of an index
2018-09-11 06:48:56 +00:00
## setInstanceConfigAt(index: Integer, keyword: String, value: String)
2018-05-11 05:56:55 +00:00
Sets the value in the configuration of an instance using the control protocol. Changes will be applied immediately.
2018-09-11 06:48:56 +00:00
## setInstanceConfigByName(index: Integer, keyword: String, value: String)
2018-05-11 05:56:55 +00:00
Works the same way as `setInstanceConfigAt` except takes an instance name instead of an index
2018-09-11 06:48:56 +00:00
## signalAllInstances(signal: String)
2018-05-11 05:56:55 +00:00
Sends a signal using the control protocol to all instances
2018-05-11 15:56:11 +00:00
A list of all signals can be [found here ](https://gitweb.torproject.org/torspec.git/tree/control-spec.txt )
2018-09-11 06:48:56 +00:00
## signalInstancesByGroup(group: String, signal: String)
Sends a signal using the control protocol to all instances in a group
## signalInstanceAt(index: Integer, signal: String)
2018-05-11 05:56:55 +00:00
Sends a signal using the control protocol to an instance identified by its index
2018-09-11 06:48:56 +00:00
## signalInstanceByName(name: String, signal: String)
2018-05-11 05:56:55 +00:00
Sends a signal using the control protocol to an instance identified by its name