NetServ 2012-03-gec13 ====================== This software package contains the NetServ core and a few selected applications for the NetServ tutorial at the 13th GENI Engineering Conference (GEC13). Copyright notice ================= The following copyright notice applies to all files in this package unless stated otherwise: Copyright (c) 2012 The Trustees of Columbia University in the City of New York All rights reserved. Third-party software packages included here are subject to their respective copyrights. Getting started: how to build and test NetServ router ====================================================== System requirements -------------------- The current version of NetServ runs on Linux, and it requires a recent kernel because of its use of netfilter queue. We tested NetServ with Ubuntu 10.04 or later. (Fedora 10 or later may also work with some tweaking.) Preparation ------------ * Enable IP forwarding: sudo echo 1 > /proc/sys/net/ipv4/ip_forward * Create netserv-root symlink Make a symlink "netserv-root" in the root directory that points to the top-level directory (i.e. the directory containing this README). For example: cd / sudo ln -s /home/user/netserv/trunk netserv-root * Install required software packages For Ubuntu: sudo apt-get install \ build-essential \ automake \ openssl \ libtool \ libnetfilter-queue-dev \ openjdk-6-jdk \ ntp \ libpoco-dev \ libssl-dev \ libxerces-c-dev \ xsdcxx For Fedora: sudo yum install \ gcc \ automake \ libtool \ java-1.6.0-openjdk-devel \ libnetfilter_queue-devel \ ntp \ xerces-c-devel \ openssl-devel Fedora 10 does not provide a package for POCO C++ library that NetServ depends on, so it needs to be built from the source. Refer to POCO web site (http://pocoproject.org/). Building and running NetServ Controller ---------------------------------------- * Run the appropriate build script for your system: cd /netserv-root ./build-netserv-ubuntu.sh * Run NetServ Controller You need to be root and source the appropriate setenv-* script. sudo su cd /netserv-root/core/linux . setenv-ubuntu.bash ./run-controller.sh run-controller.sh script in the core/linux directory launches the NetServ Controller with user/container configuration specified in the configuration file. If the configuration file is omitted, it defaults to "conf-default.xml". Testing NetServ router with UDPEcho module ------------------------------------------- * Verify NetServ is running At this point, the NetServ Controller has forked one Container process (assuming you ran it with conf-default.xml). Run "ps afxw" in another window and you'll see something like: \_ su \_ bash \_ ./netserv-controller 7000 jae,172.16.178.129,101,7001 \_ netserv-container jae 101 7001 172.16.178.129 * Build UDPEcho module The UDPEcho module is a simple packet processing module for NetServ. It is installed with a destination port (and optionally a destination IP address). When a UDP packet matching the destination is transiting the NetServ router, the UDPEcho module intercepts it, swaps the source and destination address and port in the packet, and sends it out again. In short, it "echoes" the packet back to the sender. UDPEcho is provided as an example of how to write a packet processing module in NetServ. Build udpecho.jar: cd /netserv-root/apps/udpecho/modules make * Install the UDPEcho module in the NetServ Container process The NetServ Controller is listening on port 7000 for control commands. The control commands are sent using the NetServ Control Protocol, which looks similar to HTTP. You can use netcat (nc) tool to connect to the NetServ Controller and send a command. First run netcat as follows: nc 127.0.0.1 7000 And then type (or copy and paste) the following: SETUP NetServ.apps.UDPEcho_1.0.0 NETSERV/0.1 url: file:/netserv-root/apps/udpecho/modules/udpecho.jar ttl: 6000 user: jae filter-ipv4: 127.0.0.1 filter-port: 22222 filter-proto: udp The last "" means you simply press ENTER without typing anything. You should see the response, "NETSERV/0.1 200 OK", and in the window where you ran run-controller.sh, you should see logging messages indicating that the UDPEcho module has been installed. * Send a UDP packet and get an echo back! Use netcat to send a UDP packet to the NetServ router: nc -u 127.0.0.1 22222 Type "hello" and press ENTER, and then it should be echoed back to you. As you type more lines, they will be echoed back to you as well. If you don't see the echo, you may try disabling Linux's rp_filter. Disable the rp_filters as follows and try sending the packets again: sudo su for i in /proc/sys/net/ipv4/conf/*/rp_filter ; do echo 0 > $i done * Uninstall the UDPEcho module Remove the module from the NetServ router by sending the following command (using netcat, as you did when you installed it): REMOVE NetServ.apps.UDPEcho_1.0.0 NETSERV/0.1 user: jae Now try sending UDP packets to port 22222 again. They will not be echoed back. You can repeat the install/uninstall cycle for fun. Further information ==================== NetServ home page: http://www.cs.columbia.edu/irt/project/netserv/ Mailing list: https://lists.cs.columbia.edu/cucslists/listinfo/netserv-users Feedback or questions: Jae Woo Lee Roberto Francescangeli