Commit 1f8f1253 authored by Martín Ferrari's avatar Martín Ferrari

Improve docs, and import files from wiki.

parent c461a0b6
# 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
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.
nemu 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
# 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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment