def __init__(self, reactor):
super(TwistedRunLoop, self).__init__()
if not IReactorCore.providedBy(reactor):
raise TypeError('reactor must implement IReactorCore')
if not IReactorTime.providedBy(reactor):
raise TypeError('reactor must implement IReactorTime')
self.__reactor = reactor
# TODO(strager): Make thread-safe.
self.__delayed_calls = []
def test_reactor(self):
"""
Importing L{twisted.internet.reactor} installs the default reactor if
none is installed.
"""
installed = []
def installer():
installed.append(True)
return install()
self.patch(default, "install", installer)
with NoReactor():
from twisted.internet import reactor
self.assertTrue(IReactorCore.providedBy(reactor))
self.assertEqual(installed, [True])
def launch(
reactor,
progress_updates=None,
control_port=None,
data_directory=None,
socks_port=None,
stdout=None,
stderr=None,
timeout=None,
tor_binary=None,
user=None, # XXX like the config['User'] special-casing from before
# 'users' probably never need these:
connection_creator=None,
kill_on_stderr=True,
_tor_config=None, # a TorConfig instance, mostly for tests
):
"""
launches a new Tor process, and returns a Deferred that fires with
a new :class:`txtorcon.Tor` instance. From this instance, you can
create or get any "interesting" instances you need: the
:class:`txtorcon.TorConfig` instance, create endpoints, create
:class:`txtorcon.TorState` instance(s), etc.
Note that there is NO way to pass in a config; we only expost a
couple of basic Tor options. If you need anything beyond these,
you can access the ``TorConfig`` instance (via ``.config``)
and make any changes there, reflecting them in tor with
``.config.save()``.
You can igore all the options and safe defaults will be
provided. However, **it is recommended to pass data_directory**
especially if you will be starting up Tor frequently, as it saves
a bunch of time (and bandwidth for the directory
authorities). "Safe defaults" means:
- a tempdir for a ``DataDirectory`` is used (respecting ``TMP``)
and is deleted when this tor is shut down (you therefore
*probably* want to supply the ``data_directory=`` kwarg);
- a random, currently-unused local TCP port is used as the
``SocksPort`` (specify ``socks_port=`` if you want your
own). If you want no SOCKS listener at all, pass
``socks_port=0``
- we set ``__OwningControllerProcess`` and call
``TAKEOWNERSHIP`` so that if our control connection goes away,
tor shuts down (see `control-spec
<https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
3.23).
- the launched Tor will use ``COOKIE`` authentication.
:param reactor: a Twisted IReactorCore implementation (usually
twisted.internet.reactor)
:param progress_updates: a callback which gets progress updates; gets 3
args: percent, tag, summary (FIXME make an interface for this).
:param data_directory: set as the ``DataDirectory`` option to Tor,
this is where tor keeps its state information (cached relays,
etc); starting with an already-populated state directory is a lot
faster. If ``None`` (the default), we create a tempdir for this
**and delete it on exit**. It is recommended you pass something here.
:param stdout: a file-like object to which we write anything that
Tor prints on stdout (just needs to support write()).
:param stderr: a file-like object to which we write anything that
Tor prints on stderr (just needs .write()). Note that we kill
Tor off by default if anything appears on stderr; pass
"kill_on_stderr=False" if you don't want this behavior.
:param tor_binary: path to the Tor binary to run. If None (the
default), we try to find the tor binary.
:param kill_on_stderr:
When True (the default), if Tor prints anything on stderr we
kill off the process, close the TorControlProtocol and raise
an exception.
:param connection_creator: is mostly available to ease testing, so
you probably don't want to supply this. If supplied, it is a
callable that should return a Deferred that delivers an
:api:`twisted.internet.interfaces.IProtocol <IProtocol>` or
ConnectError.
See :api:`twisted.internet.interfaces.IStreamClientEndpoint`.connect
Note that this parameter is ignored if config.ControlPort == 0
:return: a Deferred which callbacks with :class:`txtorcon.Tor`
instance, from which you can retrieve the TorControlProtocol
instance via the ``.protocol`` property.
HACKS:
1. It's hard to know when Tor has both (completely!) written its
authentication cookie file AND is listening on the control
port. It seems that waiting for the first 'bootstrap' message on
stdout is sufficient. Seems fragile...and doesn't work 100% of
the time, so FIXME look at Tor source.
XXX this "User" thing was, IIRC, a feature for root-using scripts
(!!) that were going to launch tor, but where tor would drop to a
different user. Do we still want to support this? Probably
relevant to Docker (where everything is root! yay!)
``User``: if this exists, we attempt to set ownership of the tempdir
to this user (but only if our effective UID is 0).
"""
# We have a slight problem with the approach: we need to pass a
# few minimum values to a torrc file so that Tor will start up
# enough that we may connect to it. Ideally, we'd be able to
# start a Tor up which doesn't really do anything except provide
# "AUTHENTICATE" and "GETINFO config/names" so we can do our
# config validation.
if not IReactorCore.providedBy(reactor):
raise ValueError("'reactor' argument must provide IReactorCore"
" (got '{}': {})".format(
type(reactor).__class__.__name__, repr(reactor)))
if tor_binary is None:
tor_binary = find_tor_binary()
if tor_binary is None:
# We fail right here instead of waiting for the reactor to start
raise TorNotFound('Tor binary could not be found')
# make sure we got things that have write() for stderr, stdout
# kwargs (XXX is there a "better" way to check for file-like object?)
for arg in [stderr, stdout]:
if arg and not getattr(arg, "write", None):
raise RuntimeError(
'File-like object needed for stdout or stderr args.')
config = _tor_config or TorConfig()
if data_directory is not None:
user_set_data_directory = True
config.DataDirectory = data_directory
try:
os.mkdir(data_directory, 0o0700)
except OSError:
pass
else:
user_set_data_directory = False
data_directory = tempfile.mkdtemp(prefix='tortmp')
config.DataDirectory = data_directory
# note: we also set up the ProcessProtocol to delete this when
# Tor exits, this is "just in case" fallback:
reactor.addSystemEventTrigger(
'before', 'shutdown',
functools.partial(delete_file_or_tree, data_directory))
# things that used launch_tor() had to set ControlPort and/or
# SocksPort on the config to pass them, so we honour that here.
if control_port is None and _tor_config is not None:
try:
control_port = config.ControlPort
except KeyError:
control_port = None
if socks_port is None and _tor_config is not None:
try:
socks_port = config.SocksPort
except KeyError:
socks_port = None
if socks_port is None:
socks_port = yield available_tcp_port(reactor)
config.SOCKSPort = socks_port
try:
our_user = user or config.User
except KeyError:
pass
else:
if sys.platform in ('linux', 'linux2', 'darwin') and os.geteuid() == 0:
os.chown(data_directory, pwd.getpwnam(our_user).pw_uid, -1)
# user can pass in a control port, or we set one up here
if control_port is None:
# on posix-y systems, we can use a unix-socket
if sys.platform in ('linux', 'linux2', 'darwin'):
# note: tor will not accept a relative path for ControlPort
control_port = 'unix:{}'.format(
os.path.join(os.path.realpath(data_directory),
'control.socket'))
else:
control_port = yield available_tcp_port(reactor)
else:
if str(control_port).startswith('unix:'):
control_path = control_port.lstrip('unix:')
containing_dir = dirname(control_path)
if not exists(containing_dir):
raise ValueError(
"The directory containing '{}' must exist".format(
containing_dir))
# Tor will be sad if the directory isn't 0700
mode = (0o0777 & os.stat(containing_dir).st_mode)
if mode & ~(0o0700):
raise ValueError(
"The directory containing a unix control-socket ('{}') "
"must only be readable by the user".format(containing_dir))
config.ControlPort = control_port
config.CookieAuthentication = 1
config.__OwningControllerProcess = os.getpid()
if connection_creator is None:
if str(control_port).startswith('unix:'):
connection_creator = functools.partial(
UNIXClientEndpoint(reactor, control_port[5:]).connect,
TorProtocolFactory())
else:
connection_creator = functools.partial(
TCP4ClientEndpoint(reactor, 'localhost', control_port).connect,
TorProtocolFactory())
# not an "else" on purpose; if we passed in "control_port=0" *and*
# a custom connection creator, we should still set this to None so
# it's never called (since we can't connect with ControlPort=0)
if control_port == 0:
connection_creator = None
# NOTE well, that if we don't pass "-f" then Tor will merrily load
# its default torrc, and apply our options over top... :/ should
# file a bug probably? --no-defaults or something maybe? (does
# --defaults-torrc - or something work?)
config_args = [
'-f', '/dev/null/non-existant-on-purpose', '--ignore-missing-torrc'
]
# ...now add all our config options on the command-line. This
# avoids writing a temporary torrc.
for (k, v) in config.config_args():
config_args.append(k)
config_args.append(v)
process_protocol = TorProcessProtocol(
connection_creator,
progress_updates,
config,
reactor,
timeout,
kill_on_stderr,
stdout,
stderr,
)
if control_port == 0:
connected_cb = succeed(None)
else:
connected_cb = process_protocol.when_connected()
# we set both to_delete and the shutdown events because this
# process might be shut down way before the reactor, but if the
# reactor bombs out without the subprocess getting closed cleanly,
# we'll want the system shutdown events triggered so the temporary
# files get cleaned up either way
# we don't want to delete the user's directories, just temporary
# ones this method created.
if not user_set_data_directory:
process_protocol.to_delete = [data_directory]
reactor.addSystemEventTrigger(
'before', 'shutdown',
functools.partial(delete_file_or_tree, data_directory))
log.msg('Spawning tor process with DataDirectory', data_directory)
args = [tor_binary] + config_args
# XXX note to self; we create data_directory above, so when this
# is master we can close
# https://github.com/meejah/txtorcon/issues/178
transport = reactor.spawnProcess(
process_protocol,
tor_binary,
args=args,
env={'HOME': data_directory},
path=data_directory if os.path.exists(data_directory) else
None, # XXX error if it doesn't exist?
)
# FIXME? don't need rest of the args: uid, gid, usePTY, childFDs)
transport.closeStdin()
proto = yield connected_cb
# note "proto" here is a TorProcessProtocol
# we might need to attach this protocol to the TorConfig
if config.protocol is None and proto is not None and proto.tor_protocol is not None:
# proto is None in the ControlPort=0 case
yield config.attach_protocol(proto.tor_protocol)
# note that attach_protocol waits for the protocol to be
# boostrapped if necessary
returnValue(
Tor(
reactor,
config.protocol,
_tor_config=config,
_process_proto=process_protocol,
))
def launch(reactor,
progress_updates=None,
control_port=None,
data_directory=None,
socks_port=None,
stdout=None,
stderr=None,
timeout=None,
tor_binary=None,
user=None, # XXX like the config['User'] special-casing from before
# 'users' probably never need these:
connection_creator=None,
kill_on_stderr=True,
_tor_config=None, # a TorConfig instance, mostly for tests
):
"""
launches a new Tor process, and returns a Deferred that fires with
a new :class:`txtorcon.Tor` instance. From this instance, you can
create or get any "interesting" instances you need: the
:class:`txtorcon.TorConfig` instance, create endpoints, create
:class:`txtorcon.TorState` instance(s), etc.
Note that there is NO way to pass in a config; we only expost a
couple of basic Tor options. If you need anything beyond these,
you can access the ``TorConfig`` instance (via ``.config``)
and make any changes there, reflecting them in tor with
``.config.save()``.
You can igore all the options and safe defaults will be
provided. However, **it is recommended to pass data_directory**
especially if you will be starting up Tor frequently, as it saves
a bunch of time (and bandwidth for the directory
authorities). "Safe defaults" means:
- a tempdir for a ``DataDirectory`` is used (respecting ``TMP``)
and is deleted when this tor is shut down (you therefore
*probably* want to supply the ``data_directory=`` kwarg);
- a random, currently-unused local TCP port is used as the
``SocksPort`` (specify ``socks_port=`` if you want your
own). If you want no SOCKS listener at all, pass
``socks_port=0``
- we set ``__OwningControllerProcess`` and call
``TAKEOWNERSHIP`` so that if our control connection goes away,
tor shuts down (see `control-spec
<https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
3.23).
- the launched Tor will use ``COOKIE`` authentication.
:param reactor: a Twisted IReactorCore implementation (usually
twisted.internet.reactor)
:param progress_updates: a callback which gets progress updates; gets 3
args: percent, tag, summary (FIXME make an interface for this).
:param data_directory: set as the ``DataDirectory`` option to Tor,
this is where tor keeps its state information (cached relays,
etc); starting with an already-populated state directory is a lot
faster. If ``None`` (the default), we create a tempdir for this
**and delete it on exit**. It is recommended you pass something here.
:param stdout: a file-like object to which we write anything that
Tor prints on stdout (just needs to support write()).
:param stderr: a file-like object to which we write anything that
Tor prints on stderr (just needs .write()). Note that we kill
Tor off by default if anything appears on stderr; pass
"kill_on_stderr=False" if you don't want this behavior.
:param tor_binary: path to the Tor binary to run. If None (the
default), we try to find the tor binary.
:param kill_on_stderr:
When True (the default), if Tor prints anything on stderr we
kill off the process, close the TorControlProtocol and raise
an exception.
:param connection_creator: is mostly available to ease testing, so
you probably don't want to supply this. If supplied, it is a
callable that should return a Deferred that delivers an
:api:`twisted.internet.interfaces.IProtocol <IProtocol>` or
ConnectError.
See :api:`twisted.internet.interfaces.IStreamClientEndpoint`.connect
Note that this parameter is ignored if config.ControlPort == 0
:return: a Deferred which callbacks with :class:`txtorcon.Tor`
instance, from which you can retrieve the TorControlProtocol
instance via the ``.protocol`` property.
HACKS:
1. It's hard to know when Tor has both (completely!) written its
authentication cookie file AND is listening on the control
port. It seems that waiting for the first 'bootstrap' message on
stdout is sufficient. Seems fragile...and doesn't work 100% of
the time, so FIXME look at Tor source.
XXX this "User" thing was, IIRC, a feature for root-using scripts
(!!) that were going to launch tor, but where tor would drop to a
different user. Do we still want to support this? Probably
relevant to Docker (where everything is root! yay!)
``User``: if this exists, we attempt to set ownership of the tempdir
to this user (but only if our effective UID is 0).
"""
# We have a slight problem with the approach: we need to pass a
# few minimum values to a torrc file so that Tor will start up
# enough that we may connect to it. Ideally, we'd be able to
# start a Tor up which doesn't really do anything except provide
# "AUTHENTICATE" and "GETINFO config/names" so we can do our
# config validation.
if not IReactorCore.providedBy(reactor):
raise ValueError(
"'reactor' argument must provide IReactorCore"
" (got '{}': {})".format(
type(reactor).__class__.__name__,
repr(reactor)
)
)
if tor_binary is None:
tor_binary = find_tor_binary()
if tor_binary is None:
# We fail right here instead of waiting for the reactor to start
raise TorNotFound('Tor binary could not be found')
# make sure we got things that have write() for stderr, stdout
# kwargs (XXX is there a "better" way to check for file-like object?)
for arg in [stderr, stdout]:
if arg and not getattr(arg, "write", None):
raise RuntimeError(
'File-like object needed for stdout or stderr args.'
)
config = _tor_config or TorConfig()
if data_directory is not None:
user_set_data_directory = True
config.DataDirectory = data_directory
try:
os.mkdir(data_directory, 0o0700)
except OSError:
pass
else:
user_set_data_directory = False
data_directory = tempfile.mkdtemp(prefix='tortmp')
config.DataDirectory = data_directory
# note: we also set up the ProcessProtocol to delete this when
# Tor exits, this is "just in case" fallback:
reactor.addSystemEventTrigger(
'before', 'shutdown',
functools.partial(delete_file_or_tree, data_directory)
)
# things that used launch_tor() had to set ControlPort and/or
# SocksPort on the config to pass them, so we honour that here.
if control_port is None and _tor_config is not None:
try:
control_port = config.ControlPort
except KeyError:
control_port = None
if socks_port is None and _tor_config is not None:
try:
socks_port = config.SocksPort
except KeyError:
socks_port = None
if socks_port is None:
socks_port = yield available_tcp_port(reactor)
config.SOCKSPort = socks_port
try:
our_user = user or config.User
except KeyError:
pass
else:
if sys.platform in ('linux', 'linux2', 'darwin') and os.geteuid() == 0:
os.chown(data_directory, pwd.getpwnam(our_user).pw_uid, -1)
# user can pass in a control port, or we set one up here
if control_port is None:
# on posix-y systems, we can use a unix-socket
if sys.platform in ('linux', 'linux2', 'darwin'):
# note: tor will not accept a relative path for ControlPort
control_port = 'unix:{}'.format(
os.path.join(os.path.realpath(data_directory), 'control.socket')
)
else:
control_port = yield available_tcp_port(reactor)
else:
if str(control_port).startswith('unix:'):
control_path = control_port.lstrip('unix:')
containing_dir = dirname(control_path)
if not exists(containing_dir):
raise ValueError(
"The directory containing '{}' must exist".format(
containing_dir
)
)
# Tor will be sad if the directory isn't 0700
mode = (0o0777 & os.stat(containing_dir).st_mode)
if mode & ~(0o0700):
raise ValueError(
"The directory containing a unix control-socket ('{}') "
"must only be readable by the user".format(containing_dir)
)
config.ControlPort = control_port
config.CookieAuthentication = 1
config.__OwningControllerProcess = os.getpid()
if connection_creator is None:
if str(control_port).startswith('unix:'):
connection_creator = functools.partial(
UNIXClientEndpoint(reactor, control_port[5:]).connect,
TorProtocolFactory()
)
else:
connection_creator = functools.partial(
TCP4ClientEndpoint(reactor, 'localhost', control_port).connect,
TorProtocolFactory()
)
# not an "else" on purpose; if we passed in "control_port=0" *and*
# a custom connection creator, we should still set this to None so
# it's never called (since we can't connect with ControlPort=0)
if control_port == 0:
connection_creator = None
# NOTE well, that if we don't pass "-f" then Tor will merrily load
# its default torrc, and apply our options over top... :/ should
# file a bug probably? --no-defaults or something maybe? (does
# --defaults-torrc - or something work?)
config_args = ['-f', '/dev/null/non-existant-on-purpose', '--ignore-missing-torrc']
# ...now add all our config options on the command-line. This
# avoids writing a temporary torrc.
for (k, v) in config.config_args():
config_args.append(k)
config_args.append(v)
process_protocol = TorProcessProtocol(
connection_creator,
progress_updates,
config, reactor,
timeout,
kill_on_stderr,
stdout,
stderr,
)
if control_port == 0:
connected_cb = succeed(None)
else:
connected_cb = process_protocol.when_connected()
# we set both to_delete and the shutdown events because this
# process might be shut down way before the reactor, but if the
# reactor bombs out without the subprocess getting closed cleanly,
# we'll want the system shutdown events triggered so the temporary
# files get cleaned up either way
# we don't want to delete the user's directories, just temporary
# ones this method created.
if not user_set_data_directory:
process_protocol.to_delete = [data_directory]
reactor.addSystemEventTrigger(
'before', 'shutdown',
functools.partial(delete_file_or_tree, data_directory)
)
log.msg('Spawning tor process with DataDirectory', data_directory)
args = [tor_binary] + config_args
# XXX note to self; we create data_directory above, so when this
# is master we can close
# https://github.com/meejah/txtorcon/issues/178
transport = reactor.spawnProcess(
process_protocol,
tor_binary,
args=args,
env={'HOME': data_directory},
path=data_directory if os.path.exists(data_directory) else None, # XXX error if it doesn't exist?
)
# FIXME? don't need rest of the args: uid, gid, usePTY, childFDs)
transport.closeStdin()
proto = yield connected_cb
# note "proto" here is a TorProcessProtocol
# we might need to attach this protocol to the TorConfig
if config.protocol is None and proto is not None and proto.tor_protocol is not None:
# proto is None in the ControlPort=0 case
yield config.attach_protocol(proto.tor_protocol)
# note that attach_protocol waits for the protocol to be
# boostrapped if necessary
returnValue(
Tor(
reactor,
config.protocol,
_tor_config=config,
_process_proto=process_protocol,
)
)