Tor Process¶

Helper functions for working with tor as a process.

Module Overview:

launch_tor             - starts up a tor process
launch_tor_with_config - starts a tor process with a custom torrc

stem.process.launch_tor(tor_cmd='tor', args=None, torrc_path=None, completion_percent=100, init_msg_handler=None, timeout=90, take_ownership=False, close_output=True, stdin=None)[source]¶

Initializes a tor process. This blocks until initialization completes or we error out.

If tor's data directory is missing or stale then bootstrapping will include making several requests to the directory authorities which can take a little while. Usually this is done in 50 seconds or so, but occasionally calls seem to get stuck, taking well over the default timeout.

To work to must log at NOTICE runlevel to stdout. It does this by default, but if you have a 'Log' entry in your torrc then you'll also need 'Log NOTICE stdout'.

Note: The timeout argument does not work on Windows or when outside the main thread, and relies on the global state of the signal module.

Changed in version 1.6.0: Allowing the timeout argument to be a float.

Changed in version 1.7.0: Added the close_output argument.

Parameters:	tor_cmd (str) -- command for starting tor args (list) -- additional arguments for tor torrc_path (str) -- location of the torrc for us to use completion_percent (int) -- percent of bootstrap completion at which this'll return init_msg_handler (functor) -- optional functor that will be provided with tor's initialization stdout as we get it timeout (int) -- time after which the attempt to start tor is aborted, no timeouts are applied if None take_ownership (bool) -- asserts ownership over the tor process so it aborts if this python process terminates or a Controller we establish to it disconnects close_output (bool) -- closes tor's stdout and stderr streams when bootstrapping is complete if true stdin (str) -- content to provide on stdin
Returns:	subprocess.Popen instance for the tor subprocess
Raises :	OSError if we either fail to create the tor process or reached a timeout without success

stem.process.launch_tor_with_config(config, tor_cmd='tor', completion_percent=100, init_msg_handler=None, timeout=90, take_ownership=False, close_output=True)[source]¶

Initializes a tor process, like launch_tor(), but with a customized configuration. This writes a temporary torrc to disk, launches tor, then deletes the torrc.

For example...

tor_process = stem.process.launch_tor_with_config(
  config = {
    'ControlPort': '2778',
    'Log': [
      'NOTICE stdout',
      'ERR file /tmp/tor_error_log',
    ],
  },
)

Changed in version 1.7.0: Added the close_output argument.

Parameters:	config (dict) -- configuration options, such as "{'ControlPort': '9051'}", values can either be a str or list of str if for multiple values tor_cmd (str) -- command for starting tor completion_percent (int) -- percent of bootstrap completion at which this'll return init_msg_handler (functor) -- optional functor that will be provided with tor's initialization stdout as we get it timeout (int) -- time after which the attempt to start tor is aborted, no timeouts are applied if None take_ownership (bool) -- asserts ownership over the tor process so it aborts if this python process terminates or a Controller we establish to it disconnects close_output (bool) -- closes tor's stdout and stderr streams when bootstrapping is complete if true
Returns:	subprocess.Popen instance for the tor subprocess
Raises :	OSError if we either fail to create the tor process or reached a timeout without success