diff options
| -rw-r--r-- | HACKING | 60 | ||||
| -rw-r--r-- | README | 76 |
2 files changed, 113 insertions, 23 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 000000000..77fb3a466 --- /dev/null +++ b/HACKING @@ -0,0 +1,60 @@ + +0. Intro. +Onion Routing is still very much in development stages. This document +aims to get you started in the right direction if you want to understand +the code, add features, fix bugs, etc. + +Read the README file first, so you can get familiar with the basics. + +1. The pieces. + +1.1 Connections. A connection is a long-standing tcp socket between +nodes. A connection is named based on what it's connected to -- an "OR +connection" has an onion router on the other end, an "OP connection" has +an onion proxy on the other end, an "exit connection" has a website or +other server on the other end, and an "AP connection" has an application +proxy (and thus a user) on the other end. + +1.2. Circuits. A circuit is a single conversation between two +participants over the onion routing network. One end of the circuit has +an AP connection, and the other end has an exit connection. AP and exit +connections have only one circuit associated with them, whereas OP and +OR connections multiplex many circuits at once. + +1.3. Cells. Some connections, specifically OR and OP connections, speak +"cells". This means that data over that connection is bundled into 128 +byte packets (8 bytes of header and 120 bytes of payload). Each cell has +a type, or "command", which indicates what it's for. + + + + +2. Other features. + +2.1. Bandwidth throttling. Each cell-speaking connection has a maximum +bandwidth it can use, as specified in the routers.or file. Bandwidth +throttling occurs on both the sender side and the receiving side. The +sending side sends cells at regularly spaced intervals (e.g., a connection +with a bandwidth of 12800B/s would queue a cell every 10ms). The receiving +side protects against misbehaving servers that send cells more frequently, +by using a simple token bucket: + +Each connection has a token bucket with a specified capacity. Tokens are +added to the bucket each second (when the bucket is full, new tokens +are discarded.) Each token represents permission to receive one byte +from the network --- to receive a byte, the connection must remove a +token from the bucket. Thus if the bucket is empty, that connection must +wait until more tokens arrive. The number of tokens we add enforces a +longterm average rate of incoming bytes, yet we still permit short-term +bursts above the allowed bandwidth. Currently bucket sizes are set to +ten seconds worth of traffic. + +The bandwidth throttling uses TCP to push back when we stop reading. +We extend it with token buckets to allow more flexibility for traffic +bursts. + +2.2. Data congestion control. + + + + @@ -1,25 +1,55 @@ -README ------- - -> ./autogen.sh - -runs auto* and then ./configure - -It should be all you need to do to get working Makefiles on your -platform, whatever your platform is. :) - -Then just do - -> make - -Roger: - -The summary is that I'm requiring all developers to have auto* -(aclocal, autoconf, automake) installed on their machine. - -Since different versions of auto* generate vastly different output, -I'm going to leave its output out of the repository. This means that -whenever you check out a repository, you need to run auto* to generate -a configure file, then run ./configure to get a Makefile, then build. +If you got the source from cvs: + + Run "./autogen.sh", which will run the various auto* programs and then + run ./configure for you. From there, you should be able to run 'make' + and you'll be on your way. + +If you got the source from a tarball: + + Run ./configure, make, make install as usual. + +If this doesn't work for you: + + Check out the list archives at http://archives.seul.org/or/dev/ and see + if somebody else has reported your problem. If not, please subscribe + and let us know what you did to fix it, or give us the details and + we'll see what we can do. + +Once you've got it compiled: + (these notes assume you started with source from cvs) + + It's a bit hard to figure out what to do with the binaries. If you + want to set up your own test network, go into src/config/ and look + at the routers.or file. Also in that directory are public and private + keys for various nodes (*-public, *-private) and configuration files + for the nodes (*-orrc). You can generate your own keypairs with the + orkeygen program, or use the provided ones for testing. + + Once you've got your config files ready, you're ready to start up your + network. I recommend using a screen session (man screen), or some + other way to handle many windows at once. I open a window for each + onion router, go into the src/config directory, and run something like + "../or/or -f moria2-orrc". In yet another window, I run something like + "../httpap/httpap -f httpaprc -p 9051". + + From here, you can point your browser/etc at localhost:9051 and treat + it as a web proxy. As a first test, you might telnet to it and enter + "GET http://seul.org/ HTTP/1.0" (without the quotes), followed by a pair + of carriage returns (one to separate your request from the headers, + and another to indicate that you're providing no headers). For more + convenient command-line use, I recommend making a ~/.wgetrc with + the line + http_proxy=localhost:9051" + Then you can do things like "wget seul.org" and watch as it downloads + from the onion routing network. + + For fun, you can wget a very large file (a megabyte or more), and + then ^z the wget a little bit in. The onion routers will continue + talking for a while, queueing around 500k in the kernel-level buffers. + When the kernel buffers are full, and the outbuf for the AP connection + also fills, the internal congestion control will kick in and the + exit connection will stop reading from the webserver. The circuit + will wait until you fg the wget -- and other circuits will work just + fine throughout. |