def try_endpoint(control_ep):
assert IStreamClientEndpoint.providedBy(control_ep)
proto = yield control_ep.connect(
TorProtocolFactory(password_function=password_function))
config = yield TorConfig.from_protocol(proto)
tor = Tor(reactor, proto, _tor_config=config)
returnValue(tor)
def build_tor_connection(connection,
build_state=True,
wait_for_proto=True,
password_function=lambda: None):
"""
This is used to build a valid TorState (which has .protocol for
the TorControlProtocol). For example::
from twisted.internet import reactor
from twisted.internet.endpoints import TCP4ClientEndpoint
import txtorcon
def example(state):
print "Fully bootstrapped state:",state
print " with bootstrapped protocol:",state.protocol
d = txtorcon.build_tor_connection(TCP4ClientEndpoint(reactor,
"localhost",
9051))
d.addCallback(example)
reactor.run()
:param password_function:
See :class:`txtorcon.TorControlProtocol`
:param build_state:
If True (the default) a TorState object will be
built as well. If False, just a TorControlProtocol will be
returned via the Deferred.
:return:
a Deferred that fires with a TorControlProtocol or, if you
specified build_state=True, a TorState. In both cases, the
object has finished bootstrapping
(i.e. TorControlProtocol.post_bootstrap or
TorState.post_bootstap has fired, as needed)
"""
if IStreamClientEndpoint.providedBy(connection):
endpoint = connection
elif isinstance(connection, tuple):
if len(connection) == 2:
reactor, socket = connection
if (os.path.exists(socket) and os.stat(socket).st_mode &
(stat.S_IRGRP | stat.S_IRUSR | stat.S_IROTH)):
endpoint = UNIXClientEndpoint(reactor, socket)
else:
raise ValueError('Can\'t use "%s" as a socket' % (socket, ))
elif len(connection) == 3:
endpoint = TCP4ClientEndpoint(*connection)
else:
raise TypeError('Expected either a (reactor, socket)- or a '
'(reactor, host, port)-tuple for argument '
'"connection", got %s' % (connection, ))
else:
raise TypeError('Expected a (reactor, socket)- or a (reactor, host, '
'port)-tuple or an object implementing IStreamClient'
'Endpoint for argument "connection", got %s' %
(connection, ))
d = endpoint.connect(
TorProtocolFactory(password_function=password_function))
if build_state:
d.addCallback(build_state if isinstance(build_state, collections.
Callable) else _build_state)
elif wait_for_proto:
d.addCallback(wait_for_proto if isinstance(
wait_for_proto, collections.Callable) else _wait_for_proto)
return d
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_tor(config,
reactor,
tor_binary=None,
progress_updates=None,
connection_creator=None,
timeout=None,
kill_on_stderr=True,
stdout=None,
stderr=None):
"""launches a new Tor process with the given config.
There may seem to be a ton of options, but don't panic: this
method should be easy to use and most options can be ignored
except for advanced use-cases. Calling with a completely empty
TorConfig should Just Work::
config = TorConfig()
d = launch_tor(config, reactor)
d.addCallback(...)
Note that the incoming TorConfig instance is examined and several
config options are acted upon appropriately:
``DataDirectory``: if supplied, a tempdir is not created, and the
one supplied is not deleted.
``ControlPort``: if 0 (zero), a control connection is NOT
established (and ``connection_creator`` is ignored). In this case
we can't wait for Tor to bootstrap, and **you must kill the tor**
yourself.
``User``: if this exists, we attempt to set ownership of the tempdir
to this user (but only if our effective UID is 0).
This method may set the following options on the supplied
TorConfig object: ``DataDirectory, ControlPort,
CookieAuthentication, __OwningControllerProcess`` and WILL call
:meth:`txtorcon.TorConfig.save`
:param config:
an instance of :class:`txtorcon.TorConfig` with any
configuration values you want. If ``ControlPort`` isn't set,
9052 is used; if ``DataDirectory`` isn't set, tempdir is used
to create one (in this case, it will be deleted upon exit).
:param reactor: a Twisted IReactorCore implementation (usually
twisted.internet.reactor)
:param tor_binary: path to the Tor binary to run. Tries to find the tor
binary if unset.
:param progress_updates: a callback which gets progress updates; gets as
args: percent, tag, summary (FIXME make an interface for this).
: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 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 "no_kill=True"
if you don't like the behavior.
: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 a TorProcessProtocol
connected to the fully-bootstrapped Tor; this has a
:class:`txtorcon.TorControlProtocol` instance as `.tor_protocol`. In
Tor, ``__OwningControllerProcess`` will be set and TAKEOWNERSHIP will
have been called, so if you close the TorControlProtocol the Tor should
exit also (see `control-spec
<https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_
3.23). Note that if ControlPort was 0, we don't connect at all
and therefore don't wait for Tor to be bootstrapped. In this case, it's
up to you to kill off the Tor you created.
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.
"""
## 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.
## the other option here is to simply write a torrc version of our
## config and get Tor to load that...which might be the best
## option anyway.
## actually, can't we pass them all as command-line arguments?
## could be pushing some limits for giant configs...
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
for arg in [stderr, stdout]:
if arg and not getattr(arg, "write", None):
raise RuntimeError(
'File-like object needed for stdout or stderr args.')
try:
data_directory = config.DataDirectory
user_set_data_directory = True
except KeyError:
user_set_data_directory = False
data_directory = tempfile.mkdtemp(prefix='tortmp')
config.DataDirectory = data_directory
# Set ownership on the temp-dir to the user tor will drop privileges to
# when executing as root.
try:
user = config.User
except KeyError:
pass
else:
if sys.platform in ('linux2', 'darwin') and os.geteuid() == 0:
os.chown(data_directory, pwd.getpwnam(user).pw_uid, -1)
try:
control_port = config.ControlPort
except KeyError:
control_port = 9052 # FIXME choose a random, unoccupied one?
config.ControlPort = control_port
if control_port != 0:
config.CookieAuthentication = 1
config.__OwningControllerProcess = os.getpid()
else:
connection_creator = None
config.save()
(fd, torrc) = tempfile.mkstemp(prefix='tortmp')
os.write(fd, config.create_torrc())
os.close(fd)
# txtorlog.msg('Running with config:\n', open(torrc, 'r').read())
if connection_creator is None and control_port > 0:
connection_creator = functools.partial(
TCP4ClientEndpoint(reactor, 'localhost', control_port).connect,
TorProtocolFactory())
process_protocol = TorProcessProtocol(connection_creator, progress_updates,
config, reactor, timeout,
kill_on_stderr, stdout, stderr)
# 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 user_set_data_directory:
process_protocol.to_delete = [torrc]
reactor.addSystemEventTrigger(
'before', 'shutdown', functools.partial(delete_file_or_tree,
torrc))
else:
process_protocol.to_delete = [torrc, data_directory]
reactor.addSystemEventTrigger(
'before', 'shutdown',
functools.partial(delete_file_or_tree, torrc, data_directory))
try:
log.msg('Spawning tor process with DataDirectory', data_directory)
transport = reactor.spawnProcess(process_protocol,
tor_binary,
args=(tor_binary, '-f', torrc),
env={'HOME': data_directory},
path=data_directory)
# FIXME? don't need rest of the args: uid, gid, usePTY, childFDs)
transport.closeStdin()
except RuntimeError, e:
return defer.fail(e)
def launch_tor(config, reactor,
tor_binary=None,
progress_updates=None,
connection_creator=None,
timeout=None):
"""
launches a new Tor process with the given config.
If Tor prints anything on stderr, we kill off the process, close
the TorControlProtocol and raise an exception.
:param config: an instance of :class:`txtorcon.TorConfig` with any
configuration values you want. :meth:`txtorcon.TorConfig.save`
should have been called already (anything unsaved won't make
it into the torrc produced). If ControlPort isn't set, 9052 is
used; if DataDirectory isn't set, tempdir is used to create
one.
:param reactor: a Twisted IReactorCore implementation (usually
twisted.internet.reactor)
:param tor_binary: path to the Tor binary to run. Tries to find the tor
binary if unset.
:param progress_updates: a callback which gets progress updates; gets as
args: percent, tag, summary (FIXME make an interface for this).
: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
:return: a Deferred which callbacks with a TorProcessProtocol
connected to the fully-bootstrapped Tor; this has a
:class:`txtorcon.TorControlProtocol` instance as .protocol. In Tor,
``__OwningControllerProcess`` will be set and TAKEOWNERSHIP will have
been called, so if you close the TorControlProtocol the Tor should
exit also (see `control-spec <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ 3.23).
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.
"""
## 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.
## the other option here is to simply write a torrc version of our
## config and get Tor to load that...which might be the best
## option anyway.
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')
if config.needs_save():
log.msg("Config was unsaved when launch_tor() called; calling save().")
config.save()
try:
data_directory = config.DataDirectory
user_set_data_directory = True
except KeyError:
user_set_data_directory = False
data_directory = tempfile.mkdtemp(prefix='tortmp')
config.DataDirectory = data_directory
# Set ownership on the temp-dir to the user tor will drop privileges to
# when executing as root.
try:
user = config.User
except KeyError:
pass
else:
if sys.platform in ('linux2', 'darwin') and os.geteuid() == 0:
os.chown(data_directory, pwd.getpwnam(user).pw_uid, -1)
try:
control_port = config.ControlPort
except KeyError:
control_port = 9052
config.ControlPort = control_port
config.CookieAuthentication = 1
config.__OwningControllerProcess = os.getpid()
config.save()
(fd, torrc) = tempfile.mkstemp(prefix='tortmp')
os.write(fd, config.create_torrc())
os.close(fd)
# txtorlog.msg('Running with config:\n', open(torrc, 'r').read())
if connection_creator is None:
connection_creator = functools.partial(TCP4ClientEndpoint(reactor, 'localhost', control_port).connect,
TorProtocolFactory())
process_protocol = TorProcessProtocol(connection_creator, progress_updates, config, reactor, timeout)
# 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
# we don't want to delete the user's directories, just our
# temporary ones
if user_set_data_directory:
process_protocol.to_delete = [torrc]
reactor.addSystemEventTrigger('before', 'shutdown',
functools.partial(delete_file_or_tree,
torrc))
else:
process_protocol.to_delete = [torrc, data_directory]
reactor.addSystemEventTrigger('before', 'shutdown',
functools.partial(delete_file_or_tree,
torrc,
data_directory))
try:
transport = reactor.spawnProcess(process_protocol, tor_binary,
args=(tor_binary, '-f', torrc),
env={'HOME': data_directory},
path=data_directory)
#FIXME? don't need rest of the args: uid, gid, usePTY, childFDs)
transport.closeStdin()
except RuntimeError, e:
process_protocol.connected_cb.errback(e)