initial versions of README, for new users getting up to speed, and HACKING,

for people wanting to play with the code. the hacking doc is still incomplete.


svn:r58

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. 
+
+
+
+
diff --git a/README b/README
index c8669e01f..e20cda67f 100644
--- a/README
+++ b/README
@@ -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.