hammer farther on the status events. still a lot of questions.

     EventCode = "CIRC" / "STREAM" / "ORCONN" / "BW" / "DEBUG" /

         "INFO" / "NOTICE" / "WARN" / "ERR" / "NEWDESC" / "ADDRMAP" /

         "AUTHDIR_NEWDESCS" / "DESCCHANGED" / "STATUS_GENERAL" /

         "STATUS_CLIENT" / "STATUS_SERVER"

         "STATUS_CLIENT" / "STATUS_SERVER" / "GUARDS"

  Any events *not* listed in the SETEVENTS line are turned off; thus, sending

  SETEVENTS with an empty body turns off all event reporting.

      status events are available as getinfo's currently. Let us know if

      you want more exposed.)

    "status/client"

    "status/server"

      These two special cases of internal Tor values return a (possibly

      empty) list of status events from Section 4.1.10 that Tor believes

      are still accurate. Controllers can use them to get a summary of

      any current problems with Tor's operation.

      [The answers should include notice events, not just warns and

      errs, for example so Tor can learn whether any circuits have been

      established yet.]

      [Does this mean that Tor must keep state on its side of all the

      statuses it's sent, and recognize when they're cancelled out,

      and so on? It's a shame that Tor needs to do this and also Vidalia

      needs to do this.]

  Examples:

     C: GETINFO version desc/name/moria1

     S: 250+desc/name/moria=

  [Don't rely on any of these until we work out more of the details. -RD]

  Syntax:

     "650" SP Type SP Action SP Arguments

     Type = "STATUS_NOTICE" / "STATUS_WARN"

     "650" SP Type SP Severity SP Action SP Arguments

     Type = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER"

     Severity = "NOTICE" / "WARN" / "ERR"

     Action is a string, and Arguments is a series of key=value

     pairs on the same line.

  Actions for STATUS_NOTICE events can be as follows:

     The reserved keyword "message" can optionally be used to provide a

     string describing the nature of the action. Message strings MUST

     NOT include items that a controller might be tempted to parse,

     such as numbers.

client notices:

     CIRCUIT_ESTABLISHED

       Tor is able to establish circuits for client use. This event will

       only be sent if we just built a circuit that changed our mind --

       that is, prior to this event we didn't know whether we could

       establish circuits.

  Actions for STATUS_GENERAL severity NOTICE events can be as follows:

     DIR_ALL_UNREACHABLE

       Tor believes that none of the known directory servers are

       reachable -- this is most likely because the local network is

       down or otherwise not working, and might help to explain for the

       user why Tor appears to be broken.

     [none yet]

     GUARD_NODES_CHANGED

server notices:

     EXTERNAL_ADDRESS

     "address=IP"

     "method=guessed/resolved/..."

     // hibernating

  Actions for STATUS_GENERAL severity WARN events can be as follows:

     CHECKING_REACHABILITY

     "oraddress=IP:port"

     "diraddress=IP:port"

     "timeout=NUM"

  Actions for STATUS_WARN events can be as follows:

general warns:

     DANGEROUS_VERSION

     "current=version"

     "recommended=version,version,..."

       also happens when the system is swapping so heavily that Tor is

       starving. The "time" argument includes the number of seconds Tor

       thinks it was unconscious for.

       [This status event can generally be ignored by the controller,

       since we don't really know what the user should do anyway. Hm.]

     TOO_MANY_CONNECTIONS

     "limit=NUM"

       the controller can explain this to the user and encourage her to

       file a bug report?

     // unexpected dir response. behind a hotel/airport firewall?

     [The following two are sent as WARNs if CIRCUIT_ESTABLISHED and

     not DIR_ALL_UNREACHABLE, else as ERRs:]

     // bad http or https proxy?

     BAD_DIR_RESPONSE

     // unexpected dir response. behind a hotel/airport firewall?

     // clock is skewed

     CLOCK_SKEWED

     // (either from talking to a dir authority, or from perusing a

     //  network-status timestamp)

client warns:

  Actions for STATUS_GENERAL severity ERR events can be as follows:

     BAD_PROXY

     // bad http or https proxy?

     DIR_ALL_UNREACHABLE

       Tor believes that none of the known directory servers are

       reachable -- this is most likely because the local network is

       down or otherwise not working, and might help to explain for the

       user why Tor appears to be broken.

  Actions for STATUS_CLIENT severity NOTICE events can be as follows:

     CIRCUIT_ESTABLISHED

       Tor is able to establish circuits for client use. This event will

       only be sent if we just built a circuit that changed our mind --

       that is, prior to this event we didn't know whether we could

       establish circuits.

     ENOUGH_DIR_INFO

       Tor now knows enough network-status documents and enough server

       descriptors that it's going to start trying to build circuits now.

  Actions for STATUS_CLIENT severity WARN events can be as follows:

     DANGEROUS_SOCKS

     "protocol=socks4/socks4a/socks5"

     "address=IP:port"

     // a nickname we asked for is unavailable. no need for this

     // quite yet, since no end-user controllers let you configure that.

server warns:

  Actions for STATUS_CLIENT severity ERR events can be as follows:

     [none yet]

  Actions for STATUS_SERVER severity NOTICE events can be as follows:

     EXTERNAL_ADDRESS

     "address=IP"

     "method=guessed/resolved/..."

     // hibernating

     CHECKING_REACHABILITY

     "oraddress=IP:port"

     "diraddress=IP:port"

     "timeout=NUM"

     GOOD_SERVER_DESCRIPTOR

       We successfully uploaded our server descriptor to each of the

       directory authorities, with no complaints.

  Actions for STATUS_SERVER severity WARN events can be as follows:

     // something about failing to parse our address?

     // from resolve_my_address() in config.c

     // too many onions queued. threading problem or slow cpu?

     REACHABILITY_FAILED

     "oraddress=IP:port"

     "diraddress=IP:port"

     // eventdns statements. like, hijacked dns.

     BAD_SERVER_DESCRIPTOR

     "dirauth=nickname"

     // dir authorities didn't like my descriptor

     // eventdns statements. like, hijacked dns.

  Actions for STATUS_SERVER severity ERR events can be as follows:

     REACHABILITY_FAILED

     "oraddress=IP:port"

     "diraddress=IP:port"

  Controllers must tolerate hearing about actions that they don't

  recognize.

4.1.11. Our set of guard nodes has changed

  Syntax:

     "650" SP "GUARDS" SP Type SP ...

     Type = "ENTRY"

     ...

  [needs to be fleshed out; not implemented yet]

5. Implementation notes

5.1. Authentication

   ...

7.0 Error and return codes in the directory protocol

We should write down what return codes dirservers send in what situations.