Exemplo n.º 1
0
    def __init__(self, control=None):
        if control is None:
            self.protocol = None
            self.__dict__['_slutty_'] = None
        else:
            self.protocol = ITorControlProtocol(control)

        self.config = {}
        '''Current configuration, by keys.'''

        self.unsaved = {}
        '''Configuration that has been changed since last save().'''

        self.parsers = {}
        '''Instances of the parser classes, subclasses of TorConfigType'''

        self.post_bootstrap = defer.Deferred()
        if self.protocol:
            if self.protocol.post_bootstrap:
                self.protocol.post_bootstrap.addCallback(self.bootstrap).addErrback(log.err)
            else:
                self.bootstrap()

        else:
            self.post_bootstrap.callback(self)

        self.__dict__['_setup_'] = None
Exemplo n.º 2
0
    def __init__(self, routercontainer, protocol):
        """
        :param routercontainer: should implement
        :class:`txtorcon.interface.IRouterContainer`.

        :param protocol: should implement
        :class:`txtorcon.interface.ITorControlProtocol`
        """
        self.listeners = []
        self.router_container = IRouterContainer(routercontainer)
        self.protocol = ITorControlProtocol(protocol)
        self.path = []
        self.streams = []
        self.purpose = None
        self.id = None
        self.state = 'UNKNOWN'
        self.build_flags = []

        ## this is used to hold a Deferred that will callback() when
        ## this circuit is being CLOSED or FAILED.
        self._closing_deferred = None
Exemplo n.º 3
0
class TorConfig(object):
    """
    This class abstracts out Tor's config so that you don't have to
    realize things like: in order to successfully set multiple listen
    addresses, you must put them all (and the or-ports) in one SETCONF
    call. (FIXME: this isn't true yet)

    Also, it gives easy access to all the configuration options
    present. This is done with lazy caching: the first time you access
    a value, it asks the underlying Tor (via TorControlProtocol) and
    thereafter caches the value; if you change it, a SETCONF is
    issued.

    When setting configuration values, they are cached locally and DO
    NOT AFFECT the running Tor until you call save(). When getting
    config items they will reflect the current state of Tor
    (i.e. *not* what's been set since the last save())

    FIXME: It also listens on the CONF_CHANGED event to update the
    cached data in the event other controllers (etc) changed it. (Only
    exists in Git versions?)

    FIXME: when is CONF_CHANGED introduced in Tor? Can we do anything
    like it for prior versions?

    FIXME:

        - HiddenServiceOptions is special: GETCONF on it returns
        several (well, two) values. Besides adding the two keys 'by
        hand' do we need to do anything special? Can't we just depend
        on users doing 'conf.hiddenservicedir = foo' AND
        'conf.hiddenserviceport = bar' before a save() ?

        - once I determine a value is default, is there any way to
          actually get what this value is?
    """

    def __init__(self, control=None):
        if control is None:
            self.protocol = None
            self.__dict__['_slutty_'] = None
        else:
            self.protocol = ITorControlProtocol(control)

        self.config = {}
        '''Current configuration, by keys.'''

        self.unsaved = {}
        '''Configuration that has been changed since last save().'''

        self.parsers = {}
        '''Instances of the parser classes, subclasses of TorConfigType'''

        self.post_bootstrap = defer.Deferred()
        if self.protocol:
            if self.protocol.post_bootstrap:
                self.protocol.post_bootstrap.addCallback(self.bootstrap).addErrback(log.err)
            else:
                self.bootstrap()

        else:
            self.post_bootstrap.callback(self)

        self.__dict__['_setup_'] = None

    def __setattr__(self, name, value):
        """
        we override this so that we can provide direct attribute
        access to our config items, and move them into self.unsaved
        when they've been changed. hiddenservices have to be special
        unfortunately. the _setup_ thing is so that we can set up the
        attributes we need in the constructor without uusing __dict__
        all over the place.
        """

        if self.__dict__.has_key('_setup_'):
            name = self._find_real_name(name)
            if not self.__dict__.has_key('_slutty_') and name.lower() != 'hiddenservices':
                value = self.parsers[name].validate(value, self, name)
            if isinstance(value, types.ListType):
                value = _ListWrapper(value, functools.partial(self.mark_unsaved, name))

            name = self._find_real_name(name)
            self.unsaved[name] = value

        else:
            super(TorConfig, self).__setattr__(name, value)


    def __getattr__(self, name):
        """
        on purpose, we don't return self.saved if the key is in there
        because I want the config to represent the running Tor not
        ``things which might get into the running Tor if save() were
        to be called''
        """

        return self.config[self._find_real_name(name)]

    def get_type(self, name):
        """
        return the type of a config key.

        :param: name the key

        FIXME can we do something more-clever than this for client
        code to determine what sort of thing a key is?
        """

        if name.lower() == 'hiddenservices':
            return HiddenService
        return type(self.parsers[name])

    def bootstrap(self, *args):
##        self.protocol.add_event_listener('CONF_CHANGED', self._conf_changed)
        return self.protocol.get_info_raw("config/names").addCallbacks(self._do_setup, log.err).addCallback(self.do_post_bootstrap).addErrback(log.err)

    def do_post_bootstrap(self, *args):
        self.post_bootstrap.callback(self)
        self.__dict__['post_bootstrap'] = None

    def needs_save(self):
        return len(self.unsaved) > 0

    def mark_unsaved(self, name):
        name = self._find_real_name(name)
        if self.config.has_key(name) and not self.unsaved.has_key(name):
            self.unsaved[name] = self.config[self._find_real_name(name)]

    def save(self):
        """
        Save any outstanding items. This returns a Deferred which will
        errback if Tor was unhappy with anything, or callback with
        this TorConfig object on success.
        """

        if not self.needs_save():
            return defer.succeed(self)

        args = []
        for (key, value) in self.unsaved.items():
            if key == 'HiddenServices':
                self.config['HiddenServices'] = value
                for hs in value:
                    args.append('HiddenServiceDir')
                    args.append(hs.dir)
                    for p in hs.ports:
                        args.append('HiddenServicePort')
                        args.append(str(p))
                    if hs.version:
                        args.append('HiddenServiceVersion')
                        args.append(str(hs.version))
                    if hs.authorize_client:
                        args.append('HiddenServiceAuthorizeClient')
                        args.append(hs.authorize_client)
                continue

            if isinstance(value, types.ListType):
                for x in value:
                    args.append(key)
                    args.append(str(x))

            else:
                args.append(key)
                args.append(value)

            # FIXME in future we should wait for CONF_CHANGED and
            # update then, right?
            self.config[self._find_real_name(key)] = value

        ## FIXME might want to re-think this, but currently there's no
        ## way to put things into a config and get them out again
        ## nicely...unless you just don't assign a protocol
        if self.protocol:
            d = self.protocol.set_conf(*args)
            d.addCallback(self._save_completed)
            d.addErrback(log.err)
            return d

        else:
            return defer.succeed(self)

    def _save_completed(self, foo):
        self.__dict__['unsaved'] = {}
        return self

    def _find_real_name(self, name):
        for x in self.__dict__['config'].keys():
            if x.lower() == name:
                return x
        return name

    @defer.inlineCallbacks
    def _do_setup(self, data):
        for line in data.split('\n'):
            if line == "config/names=" or line == "OK":
                continue

            (name, value) = line.split()
            if name == 'HiddenServiceOptions':
                ## set up the "special-case" hidden service stuff
                servicelines = yield self.protocol.get_conf_raw('HiddenServiceOptions')
                self._setup_hidden_services(servicelines)
                continue

            if value == 'Dependant':
                continue

            inst = None
            # FIXME: put parser classes in dict instead?
            for cls in config_types:
                if cls.__name__ == value:
                    inst = cls()
            if not inst:
                raise RuntimeError("Don't have a parser for: " + value)
            v = yield self.protocol.get_conf(name)
            v = v[name]

            self.parsers[name] = inst

            if value == 'LineList':
                ## FIXME should move to the parse() method, but it
                ## doesn't have access to conf object etc.
                self.config[self._find_real_name(name)] = _ListWrapper(self.parsers[name].parse(v), functools.partial(self.mark_unsaved, name))

            else:
                self.config[self._find_real_name(name)] = self.parsers[name].parse(v)

        # can't just return in @inlineCallbacks-decorated methods
        defer.returnValue(self)

    def _setup_hidden_services(self, servicelines):
        hs = []
        directory = None
        ports = []
        ver = None
        auth = None
        for line in servicelines.split('\n'):
            if not len(line.strip()):
                continue

            if line == 'HiddenServiceOptions':
                continue
            k, v = line.split('=')
            if k == 'HiddenServiceDir':
                if directory != None:
                    hs.append(HiddenService(self, directory, ports, auth, ver))
                directory = v
                ports = []
                ver = None
                auth = None

            elif k == 'HiddenServicePort':
                ports.append(v)

            elif k == 'HiddenServiceVersion':
                ver = int(v)

            elif k == 'HiddenServiceAuthorizeClient':
                auth = v

            else:
                raise RuntimeError("Can't parse HiddenServiceOptions: " + k)

        if directory is not None:
            hs.append(HiddenService(self, directory, ports, auth, ver))

        name = 'HiddenServices'
        self.config[name] = _ListWrapper(hs, functools.partial(self.mark_unsaved, name))

    def create_torrc(self):
        rtn = StringIO()

        for (k, v) in self.config.items() + self.unsaved.items():
            if type(v) is _ListWrapper:
                if k.lower() == 'hiddenservices':
                    for x in v:
                        for (kk, vv) in x.config_attributes():
                            rtn.write('%s %s\n' % (kk, vv))

                else:
                    for x in v:
                        rtn.write('%s %s\n' % (k, x))

            else:
                rtn.write('%s %s\n' % (k, v))

        return rtn.getvalue()
Exemplo n.º 4
0
class Circuit(object):
    """
    Used by :class:`txtorcon.TorState` to represent one of Tor's circuits.

    This is kept up-to-date by the :class`txtorcon.TorState` that owns it, and
    individual circuits can be listened to for updates (or listen to
    every one using :meth:`txtorcon.TorState.add_circuit_listener`)

    :ivar path:
        contains a list of :class:`txtorcon.Router` objects
        representing the path this Circuit takes. Mostly this will be
        3 or 4 routers long. Note that internally Tor uses single-hop
        paths for some things. See also the *purpose*
        instance-variable.

    :ivar streams:
        contains a list of Stream objects representing all streams
        currently attached to this circuit.

    :ivar state:
        contains a string from Tor describing the current state of the
        stream. From control-spec.txt section 4.1.2, these are:

            - NEW: New request to connect
            - NEWRESOLVE: New request to resolve an address
            - REMAP: Address re-mapped to another
            - SENTCONNECT: Sent a connect cell along a circuit
            - SENTRESOLVE: Sent a resolve cell along a circuit
            - SUCCEEDED: Received a reply; stream established
            - FAILED: Stream failed and not retriable
            - CLOSED: Stream closed
            - DETACHED: Detached from circuit; still retriable

    :ivar purpose:
        The reason this circuit was built. Values can currently be one
        of (but see control-spec.txt 4.1.1):

          - GENERAL
          - HS_CLIENT_INTRO
          - HS_CLIENT_REND
          - HS_SERVICE_INTRO
          - HS_SERVICE_REND
          - TESTING
          - CONTROLLER

        For most purposes, you'll want to look at GENERAL circuits only.

    :ivar id:
        The ID of this circuit, a number (or None if unset).
    """

    def __init__(self, routercontainer, protocol):
        """
        :param routercontainer: should implement
        :class:`txtorcon.interface.IRouterContainer`.

        :param protocol: should implement
        :class:`txtorcon.interface.ITorControlProtocol`
        """
        self.listeners = []
        self.router_container = IRouterContainer(routercontainer)
        self.protocol = ITorControlProtocol(protocol)
        self.path = []
        self.streams = []
        self.purpose = None
        self.id = None
        self.state = 'UNKNOWN'
        self.build_flags = []

        ## this is used to hold a Deferred that will callback() when
        ## this circuit is being CLOSED or FAILED.
        self._closing_deferred = None

    def listen(self, listener):
        if listener not in self.listeners:
            self.listeners.append(listener)

    def unlisten(self, listener):
        self.listeners.remove(listener)

    def close(self):
        """
        This asks Tor to close the underlying circuit object. See
        :method:`txtorcon.interface.ITorControlProtocol.close_circuit`
        for details.

        NOTE that the callback delivered from this method only
        callbacks after the underlying circuit is really destroyed
        (not just when the CLOSECIRCUIT command has successfully
        completed).
        """

        self._closing_deferred = defer.Deferred()
        def close_command_is_queued(*args):
            return self._closing_deferred
        d = self.protocol.close_circuit(self)
        d.addCallback(close_command_is_queued)
        return self._closing_deferred

    def _create_flags(self, kw):
        "this clones the kw dict, adding a lower-case version of every key (duplicated in stream.py; put in util?)"

        flags = {}
        for k in kw.keys():
            flags[k] = kw[k]
            flags[k.lower()] = kw[k]
        return flags

    def update(self, args):
        ##print "Circuit.update:",args
        if self.id is None:
            self.id = int(args[0])
            [x.circuit_new(self) for x in self.listeners]

        else:
            if int(args[0]) != self.id:
                raise RuntimeError("Update for wrong circuit.")
        self.state = args[1]

        kw = find_keywords(args)
        if 'PURPOSE' in kw:
            self.purpose = kw['PURPOSE']
        if 'BUILD_FLAGS' in kw:
            self.build_flags = kw['BUILD_FLAGS'].split(',')

        if self.state == 'LAUNCHED':
            self.path = []
            [x.circuit_launched(self) for x in self.listeners]
        else:
            if self.state != 'FAILED' and self.state != 'CLOSED' and len(args) > 2:
                self.update_path(args[2].split(','))

        if self.state == 'BUILT':
            [x.circuit_built(self) for x in self.listeners]

        elif self.state == 'CLOSED':
            if len(self.streams) > 0:
                log.err(RuntimeError("Circuit is %s but still has %d streams" %
                                     (self.state, len(self.streams))))
            flags = self._create_flags(kw)
            self.maybe_call_closing_deferred()
            [x.circuit_closed(self, **flags) for x in self.listeners]

        elif self.state == 'FAILED':
            if len(self.streams) > 0:
                log.err(RuntimeError("Circuit is %s but still has %d streams" %
                                     (self.state, len(self.streams))))
            flags = self._create_flags(kw)
            self.maybe_call_closing_deferred()
            [x.circuit_failed(self, **flags) for x in self.listeners]

    def maybe_call_closing_deferred(self):
        """
        Used internally to callback on the _closing_deferred if it
        exists.
        """

        if self._closing_deferred:
            self._closing_deferred.callback(self)
            self._closing_deferred = None

    def update_path(self, path):
        """
        There are EXTENDED messages which don't include any routers at
        all, and any of the EXTENDED messages may have some arbitrary
        flags in them. So far, they're all upper-case and none start
        with $ luckily. The routers in the path should all be
        LongName-style router names (this depends on them starting
        with $).

        For further complication, it's possible to extend a circuit to
        a router which isn't in the consensus. nickm via #tor thought
        this might happen in the case of hidden services choosing a
        rendevouz point not in the current consensus.
        """

        oldpath = self.path
        self.path = []
        for router in path:
            p = router[:41]
            if p[0] != '$':
                break

            ## this will create a Router if we give it a router
            ## LongName that doesn't yet exist
            router = self.router_container.router_from_id(p)

            self.path.append(router)
            if len(self.path) > len(oldpath):
                [x.circuit_extend(self, router) for x in self.listeners]
                oldpath = self.path

    def __str__(self):
        return "<Circuit %d %s [%s] for %s>" % (self.id, self.state, ' '.join(map(lambda x: x.ip, self.path)), self.purpose)
Exemplo n.º 5
0
    def __init__(self, protocol, bootstrap=True):
        self.protocol = ITorControlProtocol(protocol)
        self.protocol.connectionLost = self.connection_lost

        ## could override these to get your own Circuit/Stream subclasses
        ## to track these things
        self.circuit_factory = Circuit
        self.stream_factory = Stream

        self.attacher = None
        """If set, provides :class:`txtorcon.interface.IStreamAttacher` to attach new streams we hear about."""

        self.tor_binary = 'tor'

        self.circuit_listeners = []
        self.stream_listeners = []

        self.addrmap = AddrMap()
        self.circuits = {}              # keys on id (integer)
        self.streams = {}               # keys on id (integer)

        self.routers = {}               # keys by hexid (string) and by unique names
        self.routers_by_name = {}       # keys on name, value always list (many duplicate "Unnamed" routers, for example)
        self.guards = {}                # potentially-usable as entry guards, I think? (any router with 'Guard' flag)
        self.entry_guards = {}          # from GETINFO entry-guards, our current entry guards
        self.unusable_entry_guards = [] # list of entry guards we didn't parse out
        self.authorities = {}           # keys by name

        self.cleanup = None             # see set_attacher

        class die(object):
            def __init__(self, msg):
                self.msg = msg
            def __call__(self, *args):
                raise RuntimeError(self.msg%tuple(args))

        def nothing(*args):
            pass

        waiting_r = State("waiting_r")
        waiting_w = State("waiting_w")
        waiting_p = State("waiting_p")
        waiting_s = State("waiting_s")

        def ignorable_line(x):
            return x.strip() == '.' or x.strip() == 'OK' or x[:3] == 'ns/' or x.strip() == ''
            
        waiting_r.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_r.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin))
        ## FIXME use better method/func than die!!
        waiting_r.add_transition(Transition(waiting_r, lambda x: x[:2] != 'r ', die('Expected "r " while parsing routers not "%s"')))
        
        waiting_s.add_transition(Transition(waiting_w, lambda x: x[:2] == 's ', self._router_flags))
        waiting_s.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_s.add_transition(Transition(waiting_r, lambda x: x[:2] != 's ', die('Expected "s " while parsing routers not "%s"')))
        waiting_s.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        waiting_w.add_transition(Transition(waiting_p, lambda x: x[:2] == 'w ', self._router_bandwidth))
        waiting_w.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_w.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin)) # "w" lines are optional
        waiting_w.add_transition(Transition(waiting_r, lambda x: x[:2] != 'w ', die('Expected "w " while parsing routers not "%s"')))
        waiting_w.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        waiting_p.add_transition(Transition(waiting_r, lambda x: x[:2] == 'p ', self._router_policy))
        waiting_p.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_p.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin)) # "p" lines are optional
        waiting_p.add_transition(Transition(waiting_r, lambda x: x[:2] != 'p ', die('Expected "p " while parsing routers not "%s"')))
        waiting_p.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        self._network_status_parser = FSM([waiting_r, waiting_s, waiting_w, waiting_p])
        if False:
            with open('routerfsm.dot', 'w') as fsmfile:
                fsmfile.write(self._network_status_parser.dotty())

        self.post_bootstrap = defer.Deferred()
        if bootstrap:
            if self.protocol.post_bootstrap:
                self.protocol.post_bootstrap.addCallback(self._bootstrap).addErrback(self.post_bootstrap.errback)
            else:
                self._bootstrap()
Exemplo n.º 6
0
class TorState(object):
    """
    This tracks the current state of Tor using a TorControlProtocol.

    On setup it first queries the initial state of streams and
    circuits. It then asks for updates via the listeners. It requires
    an ITorControlProtocol instance. The control protocol doesn't need
    to be bootstrapped yet. The Deferred .post_boostrap is driggered
    when the TorState instance is fully ready to go.  The easiest way
    is to use the helper method
    :func:`txtorcon.build_tor_connection`. For details, see the
    implementation of that.

    You may add an :class:`txtorcon.interface.IStreamAttacher` to
    provide a custom mapping for Strams to Circuits (by default Tor
    picks by itself).

    This is also a good example of the various listeners, and acts as
    an :class:`txtorcon.interface.ICircuitContainer` and
    :class:`txtorcon.interface.IRouterContainer`.
    """

    implements (ICircuitListener, ICircuitContainer, IRouterContainer, IStreamListener)

    def __init__(self, protocol, bootstrap=True):
        self.protocol = ITorControlProtocol(protocol)
        self.protocol.connectionLost = self.connection_lost

        ## could override these to get your own Circuit/Stream subclasses
        ## to track these things
        self.circuit_factory = Circuit
        self.stream_factory = Stream

        self.attacher = None
        """If set, provides :class:`txtorcon.interface.IStreamAttacher` to attach new streams we hear about."""

        self.tor_binary = 'tor'

        self.circuit_listeners = []
        self.stream_listeners = []

        self.addrmap = AddrMap()
        self.circuits = {}              # keys on id (integer)
        self.streams = {}               # keys on id (integer)

        self.routers = {}               # keys by hexid (string) and by unique names
        self.routers_by_name = {}       # keys on name, value always list (many duplicate "Unnamed" routers, for example)
        self.guards = {}                # potentially-usable as entry guards, I think? (any router with 'Guard' flag)
        self.entry_guards = {}          # from GETINFO entry-guards, our current entry guards
        self.unusable_entry_guards = [] # list of entry guards we didn't parse out
        self.authorities = {}           # keys by name

        self.cleanup = None             # see set_attacher

        class die(object):
            def __init__(self, msg):
                self.msg = msg
            def __call__(self, *args):
                raise RuntimeError(self.msg%tuple(args))

        def nothing(*args):
            pass

        waiting_r = State("waiting_r")
        waiting_w = State("waiting_w")
        waiting_p = State("waiting_p")
        waiting_s = State("waiting_s")

        def ignorable_line(x):
            return x.strip() == '.' or x.strip() == 'OK' or x[:3] == 'ns/' or x.strip() == ''
            
        waiting_r.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_r.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin))
        ## FIXME use better method/func than die!!
        waiting_r.add_transition(Transition(waiting_r, lambda x: x[:2] != 'r ', die('Expected "r " while parsing routers not "%s"')))
        
        waiting_s.add_transition(Transition(waiting_w, lambda x: x[:2] == 's ', self._router_flags))
        waiting_s.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_s.add_transition(Transition(waiting_r, lambda x: x[:2] != 's ', die('Expected "s " while parsing routers not "%s"')))
        waiting_s.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        waiting_w.add_transition(Transition(waiting_p, lambda x: x[:2] == 'w ', self._router_bandwidth))
        waiting_w.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_w.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin)) # "w" lines are optional
        waiting_w.add_transition(Transition(waiting_r, lambda x: x[:2] != 'w ', die('Expected "w " while parsing routers not "%s"')))
        waiting_w.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        waiting_p.add_transition(Transition(waiting_r, lambda x: x[:2] == 'p ', self._router_policy))
        waiting_p.add_transition(Transition(waiting_r, ignorable_line, nothing))
        waiting_p.add_transition(Transition(waiting_s, lambda x: x[:2] == 'r ', self._router_begin)) # "p" lines are optional
        waiting_p.add_transition(Transition(waiting_r, lambda x: x[:2] != 'p ', die('Expected "p " while parsing routers not "%s"')))
        waiting_p.add_transition(Transition(waiting_r, lambda x: x.strip() == '.', nothing))

        self._network_status_parser = FSM([waiting_r, waiting_s, waiting_w, waiting_p])
        if False:
            with open('routerfsm.dot', 'w') as fsmfile:
                fsmfile.write(self._network_status_parser.dotty())

        self.post_bootstrap = defer.Deferred()
        if bootstrap:
            if self.protocol.post_bootstrap:
                self.protocol.post_bootstrap.addCallback(self._bootstrap).addErrback(self.post_bootstrap.errback)
            else:
                self._bootstrap()

    def _router_begin(self, data):
        args = data.split()
        self._router = Router(self.protocol)
        self._router.update(args[1],         # nickname
                            args[2],         # idhash
                            args[3],         # orhash
                            datetime.datetime.strptime(args[4]+args[5], '%Y-%m-%f%H:%M:%S'),
                            args[6],         # ip address
                            args[7],         # ORPort
                            args[8])         # DirPort

        if self.routers.has_key(self._router.id_hex):
            ## FIXME should I do an update() on this one??
            self._router = self.routers[self._router.id_hex]
            return

        if self.routers_by_name.has_key(self._router.name):
            self.routers_by_name[self._router.name].append(self._router)

        else:
            self.routers_by_name[self._router.name] = [self._router]

        if self.routers.has_key(self._router.name):
            self.routers[self._router.name] = None

        else:
            self.routers[self._router.name] = self._router
        self.routers[self._router.id_hex] = self._router

    def _router_flags(self, data):
        args = data.split()
        self._router.flags = args[1:]
        if 'guard' in self._router.flags:
            self.guards[self._router.id_hex] = self._router
        if 'authority' in self._router.flags:
            self.authorities[self._router.name] = self._router

    def _router_bandwidth(self, data):
        args = data.split()
        self._router.bandwidth = int(args[1].split('=')[1])

    def _router_policy(self, data):
        args = data.split()
        self._router.policy = args[1:]
        self._router = None

    def connection_lost(self, *args):
        pass

    @defer.inlineCallbacks
    def _bootstrap(self, arg=None):
        "This takes an arg so we can use it as a callback (see __init__)."

        ## update list of routers (must be before we do the
        ## circuit-status) note that we're feeding each line
        ## incrementally to a state-machine called
        ## _network_status_parser, set up in constructor. "ns" should
        ## be the empty string, but we call _update_network_status for
        ## the de-duplication of named routers

        ns = yield self.protocol.get_info_incremental('ns/all', self._network_status_parser.process)
        self._update_network_status(ns)

        ## update list of existing circuits
        cs = yield self.protocol.get_info_raw('circuit-status')
        self._circuit_status(cs)

        ## update list of streams
        ss = yield self.protocol.get_info_raw('stream-status')
        self._stream_status(ss)

        ## update list of existing address-maps
        key = 'address-mappings/all'
        am = yield self.protocol.get_info_raw(key)
        ## strip addressmappsings/all= and OK\n from raw data
        am = am[len(key)+1:]
        if am.strip() != 'OK':
            for line in am.split('\n')[:-1]:
                if len(line.strip()) == 0:
                    continue            # FIXME
                self.addrmap.update(line)

        self._add_events()

        entries = yield self.protocol.get_info_raw("entry-guards")
        for line in entries.split('\n')[1:]:
            if len(line.strip()) == 0 or line.strip() == 'OK':
                continue
            args = line.split()
            (name, status) = args[:2]
            name = name[:41]

            ## this is sometimes redundant, as a missing entry guard
            ## usually means it won't be in our list of routers right
            ## now, but just being on the safe side
            if status.lower() != 'up':
                self.unusable_entry_guards.append(line)
                continue

            try:
                self.entry_guards[name] = self.router_from_id(name)
            except KeyError:
                self.unusable_entry_guards.append(line)

        ## who our Tor process is (process/pid is fairly new, so we
        ## guess at the Tor otherwise, by taking PID of the only
        ## available "tor" process, not guessing at all if there's 0
        ## or > 1 tor processes.
        pid = yield self.protocol.get_info_raw("process/pid").addErrback(self.guess_tor_pid)
        if pid:
            self.tor_pid = pid

        self.post_bootstrap.callback(self)
        self.post_boostrap = None

    def guess_tor_pid(self, *args):
        if self.protocol.is_owned:
            self.tor_pid = self.protocol.is_owned

        else:
            self.tor_pid = 0
            try:
                procs = filter(lambda x: x.name.startswith(self.tor_binary),
                               psutil.get_process_list())
                if len(procs) == 1:
                    self.tor_pid = procs[0].pid
            except psutil.AccessDenied:
                pass

    def undo_attacher(self):
        """
        Shouldn't Tor handle this by turning this back to 0 if the
        controller that twiddled it disconnects?
        """

        return self.protocol.set_conf("__LeaveStreamsUnattached", 0)

    def set_attacher(self, attacher, myreactor):
        """
        Provide an :class:`txtorcon.interface.IStreamAttacher to associate streams to
        circuits. This won't get turned on until after bootstrapping
        is completed. ("__LeaveStreamsUnattached" needs to be set to "1"
        and the existing circuits list needs to be populated).
        """

        react = IReactorCore(myreactor)
        if attacher:
            self.attacher = IStreamAttacher(attacher)
        else:
            self.attacher = None

        if self.attacher is None:
            self.undo_attacher()
            if self.cleanup:
                react.removeSystemEventTrigger(self.cleanup)
                self.cleanup = None

        else:
            self.protocol.set_conf("__LeaveStreamsUnattached", "1")
            self.cleanup = react.addSystemEventTrigger('before', 'shutdown',
                                                       self.undo_attacher)
        return None

    stream_close_reasons = {
        'REASON_MISC': 1,               # (catch-all for unlisted reasons)
        'REASON_RESOLVEFAILED': 2,      # (couldn't look up hostname)
        'REASON_CONNECTREFUSED': 3,     # (remote host refused connection) [*]
        'REASON_EXITPOLICY': 4,         # (OR refuses to connect to host or port)
        'REASON_DESTROY': 5,            # (Circuit is being destroyed)
        'REASON_DONE': 6,               # (Anonymized TCP connection was closed)
        'REASON_TIMEOUT': 7,            # (Connection timed out, or OR timed out while connecting)
        'REASON_NOROUTE': 8,            # (Routing error while attempting to contact destination)
        'REASON_HIBERNATING': 9,        # (OR is temporarily hibernating)
        'REASON_INTERNAL': 10,          # (Internal error at the OR)
        'REASON_RESOURCELIMIT': 11,     # (OR has no resources to fulfill request)
        'REASON_CONNRESET': 12,         # (Connection was unexpectedly reset)
        'REASON_TORPROTOCOL': 13,       # (Sent when closing connection because of Tor protocol violations.)
        'REASON_NOTDIRECTORY': 14,      # (Client sent RELAY_BEGIN_DIR to a non-directory relay.)
        }

    def close_stream(self, stream, reason='REASON_MISC'):
        if not self.streams.has_key(stream.id):
            raise KeyError("No such stream: %d" % stream.id)

        return self.protocol.queue_command("CLOSESTREAM %d %d" % (stream.id, self.stream_close_reasons[reason]))

    def add_circuit_listener(self, icircuitlistener):
        listen = ICircuitListener(icircuitlistener)
        for circ in self.circuits.values():
            circ.listen(listen)
        self.circuit_listeners.append(listen)

    def add_stream_listener(self, istreamlistener):
        listen = IStreamListener(istreamlistener)
        for stream in self.streams.values():
            stream.listen(listen)
        self.stream_listeners.append(listen)

    def _find_circuit_after_extend(self, x):
        ex, circ_id = x.split()
        if ex != 'EXTENDED':
            raise RuntimeError('Expected EXTENDED, got "%s"' % x)
        circ_id = int(circ_id)
        circ = self._maybe_create_circuit(circ_id)
        circ.update([str(circ_id), 'EXTENDED'])
        return circ

    def build_circuit(self, routers):
        """
        Builds a circuit consisting of exactly the routers specified,
        in order.  This issues an EXTENDCIRCUIT call to Tor with all
        the routers specified.

        :param routers: a list of Router instances which is the path
            desired. A warming is issued if the first one isn't in
            self.entry_guards

        :return:
            A Deferred that will callback with a Circuit instance
            (with the .id member being valid, and probably nothing
            else).
        """

        if routers[0] not in self.entry_guards.values():
            warnings.warn("Building a circuit not starting with a guard: %s" % (str(routers),), RuntimeWarning)
        d = self.protocol.queue_command("EXTENDCIRCUIT 0 " + ','.join(map(lambda x: x.id_hex[1:], routers)))
        d.addCallback(self._find_circuit_after_extend)
        return d

    DO_NOT_ATTACH = object()
    def _maybe_attach(self, stream):
        """
        If we've got a custom stream-attachment instance (see
        set_attacher) this will ask it for the appropriate
        circuit. Note that we ignore .exit URIs and let Tor deal with
        those (by passing circuit ID 0).

        The stream attacher is allowed to return a Deferred which will
        callback with the desired circuit.

        You may return the special object DO_NOT_ATTACH which will
        cause the circuit attacher to simply ignore the stream
        (neither attaching it, nor telling Tor to attach it).
        """

        if self.attacher:
            if stream.target_host is not None and '.exit' in stream.target_host:
                ## we want to totally ignore .exit URIs as these are
                ## used to specify a particular exit node, and trying
                ## to do STREAMATTACH on them will fail with an error
                ## from Tor anyway.
                txtorlog.msg("ignore attacher:", stream)
                return

            circ = IStreamAttacher(self.attacher).attach_stream(stream, self.circuits)
            if circ is self.DO_NOT_ATTACH:
                return

            if circ == None:
                self.protocol.queue_command("ATTACHSTREAM %d 0" % stream.id)

            else:
                if isinstance(circ, defer.Deferred):
                    class IssueStreamAttach:
                        def __init__(self, state, streamid):
                            self.stream_id = streamid
                            self.state = state
                        def __call__(self, arg):
                            circid = arg.id
                            self.state.protocol.queue_command("ATTACHSTREAM %d %d" % (self.stream_id, circid))
                    circ.addCallback(IssueStreamAttach(self, stream.id)).addErrback(log.err)

                else:
                    if not self.circuits.has_key(circ.id):
                        raise RuntimeError("Attacher returned a circuit unknown to me.")
                    if circ.state != 'BUILT':
                        raise RuntimeError("Can only attach to BUILT circuits; %d is in %s." % (circ.id, circ.state))
                    self.protocol.queue_command("ATTACHSTREAM %d %d" % (stream.id, circ.id))

    def _circuit_status(self, data):
        "Used internally as a callback for updating Circuit information"
        for line in data.split('\n')[1:-1]:
            self._circuit_update(line)

    def _stream_status(self, data):
        "Used internally as a callback for updating Stream information"
        # there's a slight issue with a single-stream vs >= 2 streams,
        # in that in the latter case we have a line by itself with
        # "stream-status=" on it followed by the streams EXCEPT in the
        # single-stream case which has "stream-status=123 blahblah"
        # (i.e. the key + value on one line)

        lines = data.split('\n')[:-1]
        if len(lines) == 1:
            d = lines[0][len('stream-status='):]
            # if there are actually 0 streams, then there's nothing
            # left to parse
            if len(d):
                self._stream_update(d)
        else:
            [self._stream_update(line) for line in lines[1:]]

    def _update_network_status(self, data):
        """
        Used internally as a callback for updating Router information
        from NS and NEWCONSENSUS events.
        """

        for line in data.split('\n'):
            self._network_status_parser.process(line)

        txtorlog.msg(len(self.routers_by_name), "named routers found.")
        ## remove any names we added that turned out to have dups
        for (k,v) in self.routers.items():
            if v is None:
                txtorlog.msg(len(self.routers_by_name[k]), "dups:", k)  ##,self.routers_by_name[k]
                del self.routers[k]

        txtorlog.msg(len(self.guards), "GUARDs")

    def _newdesc_update(self, args):
        """
        Callback used internall for ORCONN and NEWDESC events to update Router information.

        FIXME: need to look at state for NEWDESC; if it's CLOSED we
        probably want to remove it from dicts...
        """

        hsh = args[:41]
        if not self.routers.has_key(hsh):
            txtorlog.msg("haven't seen", hsh, "yet!")
        self.protocol.get_info_raw('ns/id/%s' % hsh[1:]).addCallback(self._update_network_status).addErrback(log.err)
        txtorlog.msg("NEWDESC", args)

    def _maybe_create_circuit(self, circ_id):
        if not self.circuits.has_key(circ_id):
            c = self.circuit_factory(self)
            c.listen(self)
            [c.listen(x) for x in self.circuit_listeners]

        else:
            c = self.circuits[circ_id]
        return c

    def _circuit_update(self, line):
        "Used internally as a callback to update Circuit information from CIRC events."
        #print "circuit_update",line
        args = line.split()
        circ_id = int(args[0])

        c = self._maybe_create_circuit(circ_id)
        c.update(args)

    def _stream_update(self, line):
        "Used internally as a callback to update Stream information from STREAM events."
        #print "stream_update",line
        if line.strip() == 'stream-status=':
            ## this happens if there are no active streams
            return

        args = line.split()
        assert len(args) >= 3

        stream_id = int(args[0])
        wasnew = False
        if not self.streams.has_key(stream_id):
            stream = self.stream_factory(self)
            self.streams[stream_id] = stream
            stream.listen(self)
            [stream.listen(x) for x in self.stream_listeners]
            wasnew = True
        self.streams[stream_id].update(args)

        ## if the update closed the stream, it won't be in our list
        ## anymore. FIXME: how can we ever hit such a case as the
        ## first update being a CLOSE?
        if wasnew and self.streams.has_key(stream_id):
            self._maybe_attach(self.streams[stream_id])

    def _addr_map(self, addr):
        "Internal callback to update DNS cache. Listens to ADDRMAP."
        txtorlog.msg(" --> addr_map", addr)
        self.addrmap.update(addr)

    event_map = {
        'STREAM': _stream_update,
        'CIRC': _circuit_update,
        'NS': _update_network_status,
        'NEWCONSENSUS': _update_network_status,
        'NEWDESC': _newdesc_update,
        'ADDRMAP': _addr_map
        }
    """event_map used by add_events to map event_name -> unbound method"""
    @defer.inlineCallbacks
    def _add_events(self):
        """
        Add listeners for all the events the controller is interested in.
        """

        for (event, func) in self.event_map.items():
            ## the map contains unbound methods, so we bind them
            ## to self so they call the right thing
            yield self.protocol.add_event_listener(event, types.MethodType(func, self, TorState))

    ## ICircuitContainer

    def find_circuit(self, circid):
        "ICircuitContainer API"
        return self.circuits[circid]

    ## IRouterContainer

    def router_from_id(self, routerid):
        "IRouterContainer API"
        return self.routers[routerid]

    ## implement IStreamListener

    def stream_new(self, stream):
        "IStreamListener: a new stream has been created"
        txtorlog.msg("stream_new", stream)

    def stream_succeeded(self, stream):
        "IStreamListener: stream has succeeded"
        txtorlog.msg("stream_succeeded", stream)

    def stream_attach(self, stream, circuit):
        """
        IStreamListener: the stream has been attached to a circuit. It
        seems you get an attach to None followed by an attach to real
        circuit fairly frequently. Perhaps related to __LeaveStreamsUnattached?
        """
        txtorlog.msg("stream_attach", stream.id,
                     stream.target_host, " -> ", circuit)

    def stream_detach(self, stream, circuit):
        """
        IStreamListener
        """
        txtorlog.msg("stream_detach", stream.id)

    def stream_closed(self, stream):
        "IStreamListener: stream has been closed (won't be in controller's list anymore)"
        txtorlog.msg("stream_closed", stream.id)
        del self.streams[stream.id]

    def stream_failed(self, stream, reason, remote_reason):
        "IStreamListener: stream failed for some reason (won't be in controller's list anymore)"
        txtorlog.msg("stream_failed", stream.id)
        del self.streams[stream.id]

    ## implement ICircuitListener

    def circuit_launched(self, circuit):
        "ICircuitListener API"
        txtorlog.msg("circuit_launched", circuit)
        self.circuits[circuit.id] = circuit

    def circuit_extend(self, circuit, router):
        "ICircuitListener API"
        txtorlog.msg("circuit_extend:", circuit.id, router)

    def circuit_built(self, circuit):
        "ICircuitListener API"
        txtorlog.msg("circuit_built:", circuit.id,
                     "->".join("%s.%s" % (x.name, x.location.countrycode) for x in circuit.path),
                     circuit.streams)

    def circuit_new(self, circuit):
        "ICircuitListener API"
        txtorlog.msg("circuit_new:", circuit.id)
        self.circuits[circuit.id] = circuit

    def circuit_destroy(self, circuit):
        "For circuit_closed and circuit_failed"
        txtorlog.msg("circuit_destroy:",circuit.id)
        del self.circuits[circuit.id]

    def circuit_closed(self, circuit):
        "ICircuitListener API"
        txtorlog.msg("circuit_closed", circuit)
        self.circuit_destroy(circuit)

    def circuit_failed(self, circuit, reason):
        "ICircuitListener API"
        txtorlog.msg("circuit_failed", circuit, reason)
        self.circuit_destroy(circuit)