how to programmatically refresh the Tor session?

[aguyinmontreal]

I see in the README:

You need to enable the Tor ControlPort if you want to programmatically refresh the Tor session (i.e., get a new proxy IP address) without restarting your Tor client

But after enabling the Tor ControlPort, how exactly do you refresh the Tor session without restarting the Tor client?

Could you please give me a starting point (something to read)? Thanks!

[talmobi]

The API lists a few helper functions for you: https://github.com/talmobi/tor-request#api

module.exports = {

  // <snip>

  /**
   * Helper object to communicate with the tor ControlPort. Requires an enabled ControlPort on tor.
   */
  TorControlPort: {
    password: "", // default ControlPort password
    host: "localhost", // default address
    port: 9051, // default ControlPort
    
    /**
     * @param {Array.string} commands - signals that are sent to the ControlPort
     */
    send: function (commands, done(err, data))
  }
  
  /**
   * A set of predefined TorControlPort commands to request and verify tor for a new session (get a new ip to use).
   *
   * @param {function} done - the callback function to tell you when the process is done
   * @param {object} err - null if tor session renewed successfully
   */
  newTorSession: function ( done(err) ) // clears and renews the Tor session (i.e., you get a new IP)
  
}

Basically, when you enable the control port in the tor config file -- tor will also run a sub process/service/server on port 9051 (tor runs on port 9050 by default). So to communicate with it you simply connect to it through TCP ( in nodejs: require('net').connect( /* snip */) ) and then, using tors own custom text based signalling protocol ( [2] basically just text separated by newlines \n if I recall correctly) you can tell it do do various things.

The helper function api.newTorSession...<snip> basically just opens a TCP socket to 9051 and sends a few lines[1] of text in order to do this and then listens for a response from the socket to determine if it was successful or if it failed/errored.

[1]

  var commands = [
    'authenticate "' + password + '"', // authenticate the connection
    'signal newnym', // send the signal (renew Tor session)
    'quit' // close the connection
  ];

See: https://github.com/talmobi/tor-request/blob/master/index.js#L127-L157
and https://github.com/talmobi/tor-request/blob/master/index.js#L101-L124

[2] ( https://gitweb.torproject.org/torspec.git/tree/control-spec.txt )

1. Protocol outline

  TC is a bidirectional message-based protocol.  It assumes an underlying
  stream for communication between a controlling process (the "client"
  or "controller") and a Tor process (or "server").  The stream may be
  implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
  but it must provide reliable in-order delivery.  For security, the
  stream should not be accessible by untrusted parties.

  In TC, the client and server send typed messages to each other over the
  underlying stream.  The client sends "commands" and the server sends
  "replies".

  By default, all messages from the server are in response to messages from
  the client.  Some client requests, however, will cause the server to send
  messages to the client indefinitely far into the future.  Such
  "asynchronous" replies are marked as such.

  Servers respond to messages in the order messages are received.

[talmobi]

For more details about the protocol see: https://gitweb.torproject.org/torspec.git/tree/control-spec.txt

( CTRL-F search for "NEWNYM" pertains to our case )

[aguyinmontreal]

Thanks a lot!