tests/net_test/README

   1                                 net_test v0.1
   2                                 =============
   3
   4 A simple framework for blackbox testing of kernel networking code.
   5
   6
   7 Why use it?
   8 ===========
   9
  10 - Fast test / boot cycle.
  11 - Access to host filesystem and networking via L2 bridging.
  12 - Full Linux userland including Python, etc.
  13 - Kernel bugs don't crash the system.
  14
  15
  16 How to use it
  17 =============
  18
  19 cd <kerneldir>
  20 path/to/net_test/run_net_test.sh <test>
  21
  22 where <test> is the name of a test binary in the net_test directory. This can
  23 be an x86 binary, a shell script, a Python script. etc.
  24
  25
  26 How it works
  27 ============
  28
  29 net_test compiles the kernel to a user-mode linux binary, which runs as a
  30 process on the host machine. It runs the binary to start a Linux "virtual
  31 machine" whose root filesystem is the supplied Debian disk image. The machine
  32 boots, mounts the root filesystem read-only, runs the specified test from init, and then drops to a shell.
  33
  34
  35 Access to host filesystem
  36 =========================
  37
  38 The VM mounts the host filesystem at /host, so the test can be modified and
  39 re-run without rebooting the VM.
  40
  41
  42 Access to host networking
  43 =========================
  44
  45 Access to host networking is provided by tap interfaces. On the host, the
  46 interfaces are named <user>TAP0, <user>TAP1, etc., where <user> is the first
  47 10 characters of the username running net_test. (10 characters because
  48 IFNAMSIZ = 16). On the guest, they are named eth0, eth1, etc.
  49
  50 net_test does not do any networking setup beyond creating the tap interfaces.
  51 IP connectivity can be provided on the host side by setting up a DHCP server
  52 and NAT, sending IPv6 router advertisements, etc. By default, the VM has IPv6
  53 privacy addresses disabled, so its IPv6 addresses can be predicted using a tool
  54 such as ipv6calc.
  55
  56 The provided filesystem contains a DHCPv4 client and simple networking
  57 utilities such as ping[6], traceroute[6], and wget.
  58
  59 The number of tap interfaces is currently hardcoded to two. To change this
  60 number, modify run_net_test.sh.
  61
  62
  63 Logging into the VM, installing packages, etc.
  64 ==============================================
  65
  66 net_test mounts the root filesystem read-only, and runs the test from init, but
  67 since the filesystem contains a full Linux userland, it's possible to boot into
  68 userland and modify the filesystem, for example to install packages using
  69 apt-get install. Log in as root with no password. By default, the filesystem is
  70 configured to perform DHCPv4 on eth0 and listen to RAs.
  71
  72
  73 Bugs
  74 ====
  75
  76 Since the test mounts the filesystem read-only, tests cannot modify
  77 /etc/resolv.conf and the system resolver is hardcoded to 8.8.8.8.