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 disconnectsclose_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 disconnectsclose_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