Stem Docs

Tor Process

Tor Process

Helper functions for working with tor as a process.

NO_TORRC:when provided as a torrc_path tor is ran with a blank configuration
DEFAULT_INIT_TIMEOUT:
 number of seconds before we time out our attempt to start a tor instance

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