Improve docs, and import files from wiki.

BUILDING.md

+# How to build nemu
+
+## Dependencies
+
+  * python-unshare (http://pypi.python.org/pypi/python-unshare)
+  * python-passfd (http://pypi.python.org/pypi/python-passfd)
+  * linux-kernel >= 2.6.35
+  * bridge-utils
+  * iproute
+  * procps
+  * xauth (Needed only for X11 forwarding support)
+
+## Details
+
+Once the dependencies are installed, run:
+
+    $ make
+    $ sudo make test # optional
+    $ sudo make install

DEPENDENCIES

-Required packages for using nemu
-================================
-
-python-unshare		http://pypi.python.org/pypi/python-unshare
-python-passfd		http://pypi.python.org/pypi/python-passfd
-
-linux-kernel >= 2.6.35	http://kernel.org/
-bridge-utils
-iproute
-procps
-xauth			Needed only for X11 forwarding support.

README.md

 nemu
 ====
 
- A lightweight network emulator embedded in a small python library 
+Nemu (Netwok EMUlator) is a small Python library to create emulated networks
+and run and test programs in them.
+
+Different programs, or copies of the same program, can run in different
+emulated nodes, using only the emulated network to communicate, without ever
+noticing they all run in the same computer.
+
+Nemu provides a very simple interface to create nodes, connect them arbitrarily
+with virtual interfaces, configure IPv4 and IPv6 addresses and routes, and
+start programs in the nodes. The virtual interfaces also support emulation of
+delays, loss, and reordering of packets, and bandwidth limitations.
+
+You can even start interactive sessions by opening xterms on different nodes,
+Nemu has special support for forwarding X sessions to the emulated nodes.
+
+More advanced configurations, like setting up netfilter (iptables) rules,
+starting VPN tunnels, routing daemons, etc, are simply supported by executing
+the appropriate commands in the emulated nodes, exactly as if they were
+executed in real machines in a real network.
+
+All this is achieved with very small overhead, thanks to the Linux kernel's
+[network name spaces][] capabilities, part of the bigger [Linux containers][]
+project.
+
+To get a feeling of what you can do with Nemu, take a peek at this [sample
+script](examples/sample.py) that creates 3 interconnected nodes, runs some
+tests and then starts xterms running tcpdump so you can see the packets flowing
+from one node to the other.
+
+Nemu was started as a research project at [INRIA][] (Institut de Recheche en
+Informatique et Automatique, a French research institution) and now it is
+developed jointly by INRIA staff and external developers.
+
+
+Nemu is now part of [Debian][]! You can just `apt-get install python-nemu` and
+start using it.
+
+[network name spaces]: http://lxc.sourceforge.net/index.php/about/kernel-namespaces/network/
+[Linux containers]: http://lxc.sourceforge.net/
+[INRIA]: http://www.inria.fr/en/
+[Debian]: http://packages.qa.debian.org/p/python-nemu.html

docs/X11Forwarding.md

+# Support for X11 forwarding in Nemu
+
+## Introduction
+
+Nemu has special support for forwarding X11 sessions, so interactive programs can be run from inside virtual nodes.
+
+When running in a different network namespace (a virtual node), UNIX domain sockets cannot be used to communicate to the main namespace, or with other namespaces. Because of this, the usual way to start X11 applications does not work.
+
+Furthermore, as the network topology is constructed by the user, and can be completely arbitrary, in general there is no guarantee that normal X11-over-TCP would work either!
+
+To solve this problem, Nemu starts a separate process per virtual node that will forward TCP connections inside the node to the local X11 UNIX domain or TCP socket, in a very similar way to what SSH does to forward X11 connections. A nice UNIX trick is used to pass the listening socket to the virtual node while keeping the other end in the "normal" main namespace (see http://pypi.python.org/pypi/python-passfd).
+
+## Troubleshooting
+
+To enable this feature, create your `nemu.Node` object with the optional argument `forward_X11` set to `True`.
+
+Note that when switching to root to run your Nemu scripts, it could happen that the X11 libraries are not able to obtain the proper credentials to connect to your display:
+
+    $ sudo xeyes
+    Error: Can't open display: localhost:11.0
+
+This is usually seen when using forwarded X11 connections through SSH, as it does not set the `XAUTHORITY` variable, and the libraries take the default value, which is different for you and for the root user.
+
+As a simple workaround, you can set the `XAUTHORITY` variable to the full path of your xauth file (sudo keeps `XAUTHORITY` unchanged):
+
+    $ XAUTHORITY=${HOME}/.Xauthority sudo xeyes
+
+This will not work in most NFS-mounted home directories, you will need to copy the xauth file out of NFS first:
+
+    $ cp ${HOME}/.Xauthority /tmp/${USER}-Xauthority
+    $ export XAUTHORITY=/tmp/${USER}-Xauthority
+    $ sudo xeyes