(reactor,
           progress_updates=None,
           control_port=None,
           data_directory=None,
           socks_port=None,
           non_anonymous_mode=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 non_anonymous_mode: sets the Tor options
        `HiddenServiceSingleHopMode` and
        `HiddenServiceNonAnonymousMode` to 1 and un-sets any
        `SOCKSPort` config, thus putting this Tor client into
        "non-anonymous mode" which allows starting so-called Single
        Onion services -- which use single-hop circuits to rendezvous
        points. See WARNINGs in Tor manual! Also you need Tor
        `0.3.4.1` or later (e.g. any `0.3.5.*` or newer) for this to
        work properly.

    :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).
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.
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 .
def launch(reactor,
           progress_updates=None,
           control_port=None,
           data_directory=None,
           socks_port=None,
           non_anonymous_mode=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 non_anonymous_mode: sets the Tor options
        `HiddenServiceSingleHopMode` and
        `HiddenServiceNonAnonymousMode` to 1 and un-sets any
        `SOCKSPort` config, thus putting this Tor client into
        "non-anonymous mode" which allows starting so-called Single
        Onion services -- which use single-hop circuits to rendezvous
        points. See WARNINGs in Tor manual! Also you need Tor
        `0.3.4.1` or later (e.g. any `0.3.5.*` or newer) for this to
        work properly.

    :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? do we use anything besides 'write()'?)
    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 non_anonymous_mode:
        if socks_port is not None:
            raise ValueError(
                "Cannot use SOCKS options with non_anonymous_mode=True"
            )
        config.HiddenServiceNonAnonymousMode = 1
        config.HiddenServiceSingleHopMode = 1
        config.SOCKSPort = 0
    else:
        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 we're root, make sure the directory is owned by the User
        # that Tor is configured to drop to
        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
    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?
    )
    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,
            _non_anonymous=True if non_anonymous_mode else False,
        )
    )
def launch ( reactor , progress_updates = None , control_port = None , data_directory = None , socks_port = None , non_anonymous_mode = 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 ) : # 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? do we use anything besides 'write()'?) 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 non_anonymous_mode : if socks_port is not None : raise ValueError ( "Cannot use SOCKS options with non_anonymous_mode=True" ) config . HiddenServiceNonAnonymousMode = 1 config . HiddenServiceSingleHopMode = 1 config . SOCKSPort = 0 else : 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 we're root, make sure the directory is owned by the User # that Tor is configured to drop to 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 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? ) 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 , _non_anonymous = True if non_anonymous_mode else False , ) )