$Id$ Vidalia Feature Specification 0. Introduction The purpose of this document is to give an overview of Vidalia's design goals, as well as a general description of what features must be present in Vidalia. In addition, this document contains descriptions of features which we have considered, but which Vidalia does not currently implement either for technical reasons or because there simply isn't any demand for a feature. 1. Design Overview Vidalia aims for a "minimalist" interface, meaning that its use should be unobtrusive wihle the user is doing other tasks on her machine, while still providing adequate information about the status of their Tor process. Vidalia also does not aim to support every configuration option offered by Tor. Tor's configuration file (the user's 'torrc' file) supports a plethora of configuration options, allowing the user extensive customization over the behavior of their Tor process; however, not all users need or want to configure every aspect of Tor. Additionally, it has been the author's experience that few users actually understand all of Tor's configuration options nor do they understand the implications of changing those configuration options (e.g., changing the set of default authoritative directory servers or allowing only nodes from a specified country). Vidalia should be able to run Tor with a standard set of default arguments that allow the user to run Tor without doing any complex initial configuration. Also, Vidalia users should be able to use and configure Tor without having to understand details of Tor's inner-workings. 2. Required Features Items described in this section represent features or functionality that MUST be present in Vidalia. These features are considered necessary for providing a useful Tor controller. 2.1. Tor Process Management Vidalia must support starting and stopping Tor at the user's request, without the user having to repeatedly specify the location of their Tor executable. In addition, Vidalia must be able to monitor the status of the Tor process and alert the user should Tor exit unexpectedly. Information about the status of Tor should be reflected in an icon on the user's screen in an area appropriate for their operating system (e.g., the system tray on Windows or the menu bar on Mac OS X). Hovering over the icon should give the user a brief description of what the currently displayed icon indicates (e.g., "Tor is stopped"). Any status indicators the user did not explicitly ask for, such as a notification balloon on Windows, should be able to be disabled at the user's discretion. 2.2. Tor Log Messages Tor has the ability to notify a controller about what it's doing by asking for a configurable set of log message severity levels. These messages should be displayed for the user in a single dialog, able to be hidden at the user's request while continuing to accept log messages from Tor in the background. Vidalia must also allow the user to configure the severity of messages in which he is interested. NOTE: It is entirely possible that the user's Tor process could terminate before the controller has the ability to connect to Tor's control port, meaning the user has no way of knowing why their Tor process exited unexpectedly. In such case, Vidalia must provide an alternative way to view Tor's output, such as capturing messages logged to stdout. 2.3. Tor Configuration Vidalia must provide a screen (or set of screens) through which the user can configure their Tor. As mentioned in Section 1, Vidalia does not need to support every possible configuratino option, but rather should allow the user to configure the most often modified options. Configuration options that are not often changed or have security implications should be placed on an "Advanced" configuration screen. With each configuration option displayed, Vidalia must provide a way for the user to read a text description of what the configuration option represents and how changing that option affects their Tor process. 2.4. Bandwidth Monitoring Users are often interested in the rate at which they are currently sending and receiving through the Tor network. Vidalia must provide a graph of the user's current transfer rates, based on the amount of data sent and received roughly each second as reported by Tor via the control protocol. The bandwidth graph must have an intuitive default appearance and interpretation, but should also be configurable should the user not like the defaults. The bandwidth graph must also be able to be resized and "docked" in a region of the user's screen. 2.5. Current Circuit Information Vidalia must provide a screen allowing the user to see a list of their currently opened circuits, including a list of Tor routers which are in each circuit. The user must be able to select one of the routers in a circuit and view detailed information about that router, as parsed from its server descriptor. Such information should include the router's nickname as chosen by the router operator, the router operator's contact information, that router's exit policy, etc. Vidalia should allow the user to see which streams are currently attached to which circuits. Vidalia may also provide information about the geographic location of the exit node for each circuit, since outbound connections from that circuit will appear to originate in the country of that circuit's exit node. Vidalia may also give users the ability to destroy a specific circuit should the user decide that the nodes in that circuit are not providing adequate performance. 2.6. Tor Network Status Vidalia must provide a way to view a list of routers currently in the Tor network and information about each router, such as its nickname, exit policy, uptime, or bandwidth. In essence, this is a compacted and more intuitive view of Tor's directory. Users should be able to search the list of current routers for a specific nickname or for a router that allows exiting to a specified port. In addition, users should be able to order the list of available routers by statistics such as uptime and bandwidth. 2.7. Server Management 2.7.1. Server Setup The Tor network depends on volunteers to run the Tor routers in the network. To further encourage users to run a router (server), server setup must be simple. A small form that prompts the user for necessary information, such as a nickname for the user's server or contact information, should be displayed. After completing the form and confirming the entered information, the user's Tor process should automatically be configured to run as a server with the information just entered. 2.7.2. Exit Policy Configuration Many server operators prefer to limit the types of traffic that they will relay for the Tor network. Since traffic from an exit node appears to originate from that machine's IP address, server operators may want to try to cut down on traffic that could get them in trouble, such as file-sharing traffic. Tor supports this through an ``exit policy'' at each router, which defines IPs and ports that the operator may either accept or reject. Server operators may also opt to be a ``middleman node'', who doesn't allow traffic to exit the Tor network from their node but is willing to relay traffic between other Tor routers. Vidalia must make configuring an exit policy easy and intuitive. Vidalia may also display helpful information for the user, such as what ports are commonly associated with what sorts of network traffic. 2.7.3. Rate-limiting Configuration In addition to exit policies, Tor also allows server operators to specify how much of their bandwidth they are willing to devote to relaying Tor traffic; however, users may want to devote varying amounts of bandwidth depending on the time of day. As an example, a server operator may be willing to devote all of his available bandwidth to the Tor network at night while he is sleeping, but only a small fraction of it during the day when he is using his machine for his own activities. Vidalia must allow server operators to easily schedule rate-limiting depending on the current date and time. Vidalia could also allow the user to configure ``rate-limiting profiles''. Examples of a profile may include ``weekday'' which would all Tor to use all available bandwidth while the user is at work and during the evening, ``weekend'' which is similar to ``weekday'' except the user keeps most of his bandwidth to himself during the day, or ``vacation'' which devotes all bandwidth to Tor all the time. 2.8. Signals On non-Windows machines, Tor performs a certain action when it receives a signal. For instance, Tor will reload its torrc if it receives a SIGHUP. Unfortunately, Windows users are unable to send Tor such signals. Vidalia must allow the user to simulate sending signals to Tor by using the SIGNAL feature of the control protocol. Vidalia should also include descriptions informing the user what each signal does and what it is used for. 3. Desired Features Features in this section are currently considered useful, but whose design has yet to be fully considered and planned. These features would be nice to have in Vidalia, but whose absence would not seriously adversely affect the usability or utility of Vidalia. 3.1. Graphical display of current circuits The user should be able to see a map of the world with indicators pointing to the rough geographic location of each router in the Tor network. Circuits will be represented by drawing a link between router indicators on the map. Hovering over an indicator on the map will display information about the router, as was mentioned in Section 2.5. The primary difficulty with this feature is finding a free, accurate database used to map an IP address to a latitude and longitude. Another difficulty with this is how to represent situations where multiple routers are run at the same geographic location. For example, there are currently three routers being run at MIT; the user should be able to easily distinguish between the three. 3.2. Circuit latency information Users are often interested in how their current circuit is performing, so they may be interested to see the additional delay added by routing their traffic through the Tor network. One could imagine an implementation as follows: Vidalia creates a circuit using the same sequence of nodes in the circuit whose performance we wish to measure. Vidalia then connects to itself through that circuit and sends small chunks of data to itself, measuring the delay between the time the chunk of data is sent and the time it is received. Vidalia is essentially "pinging" itself through a circuit. A technical problem with the above approach is that, if the user has a firewall configured, it must accept connections from the exit node of the circuit being measured otherwise Vidalia would be unable to connect back to itself. Also, an adversary who can observe the user would see that a Tor exit node is connecting back to the user and sending these "pings", yielding the identity of this user's exit node. 4. Questionable Features Features in this section may or may not be useful. We might consider implementing them pending a number of users who desire such features. 4.1. Support for running Vidalia on a separate machine than Tor Tor gives users the ability to run their Tor process on a server on a LAN and then point their browser's proxy settings to that server from other machines on the LAN. In such cases, users of the machines on the LAN not running Tor would still want to know about the status of the Tor process on the server but Vidalia would be unable to monitor the process on a remote machine. A possible solution for this would be to have an "agent" running on the server that monitored the state of the Tor process. Vidalia would then connect to this agent and ask the agent for the state of its Tor process. Vidalia could also tell the agent to start and stop Tor, forward control messages, etc. This is probably not worth the effort unless we hear an uproar from users demanding this feature.