Project - User Interface

In this project you will expand your software router to add additional features and a user interface.

Getting Started

Your user interface will run as a networked application using a standard sockets interface, allowing it to be accessed remotely over the network. For more information on socket programming, refer to Beej's Guide to Network Programming. Note that you cannot simply use system calls like send, recv, connect, etc... as shown in the guide, however.  Those calls will result in packets being processed by the Linux network stack and sent out your normal network port. Instead, we want packets to be sent and received over VNS, and later, your NetFPGA board. To resolve this challenge, your router must have an integrated network stack to deal with a transport protocol (like TCP) that runs over IP.

A modified version of the LwIP stack ("Lightweight IP") has been provided to you and is already integrated in the project base code.  All you need to do when writing your user interface program is to use this custom network stack instead of the network stack provided by Linux.  (LwIP has been integrated in such a way as to send and receive packets via VNS or NetFPGA ports, while the Linux network stack will send and receive real packets out your real network card, which is not what we want!)

To use LwIP, you should make sure to use the corresponding LwIP-specific include files instead of the normal system include files. Then, either set the preprocessor variable LWIP_COMPAT_SOCKETS, or change your system calls to use the prefix lwip_.  (i.e. you used to call socket() to open a socket in the normal Linux network stack, but now you should call lwip_socket() to open a socket through the LwIP stack).

As discussed in COMP / ECPE 177 (and in Beej's guide), Unix I/O on sockets has its own sets of constraints and challenges. Be sure to check all function return values to ensure they completed successfully.  For example, send() is not guaranteed to send all data the first time - it might return after only partially sending data. Similarly, recv() might only partially fill the provided buffer with incoming data.

For a good tutorial on threads, locks, and synchronization, please see http://www.cs.cf.ac.uk/Dave/C/node29.html (part of the larger Programming in C: UNIX System Calls and Subroutines tutorial)

Requirements

Your software router must support the following functions in addition to those required in the first project.

• Your code must compile and run under Linux on the 64-bit ecs-network class server.
  • Note that when you integrate your code with the hardware it will need to run on your 32-bit netfpgaXX machine, so it would be a good idea to verify that it works there, as well.
• ARP
  • Add an ARP timeout thread
    • This thread should drop packets waiting for an ARP reply after a configurable number of seconds (set via the user interface - default 30) and send an appropriate ICMP message
    • This thread should remove ARP entries from the ARP table after a configurable number of seconds (set via the user interface - default 300)
  • Enable the addition and deletion of static ARP entries through the user interface
    • Static entries should never be removed by the timeout thread
• IP
  • Enable the addition and deletion of static routes through the user interface
• TCP
  • Receiving packets: When parsing incoming packets received by your router, you should specifically identify TCP packets destined for any of the router's IP addresses and forward these packets to the TCP stack for processing.  To do so, call sr_transport_input(...) in sr_lwtcp_glue.c. Note that this function takes a pointer to the start of the IP header in the packet, not the start of the full packet.  (The transport layer does not need to process the Ethernet frame headers, so we don't even pass it that data).
  • Sending packets: The transport layer (TCP stack) must also be able to send packets out of your software router. To accomplish this, implement the following functions:
    • sr_integ_findsrcip(...)
      • This function is called by the transport layer for outgoing packets generated by the router. The transport layer provides the destination IP address in network byte order of the packet it would like to send. This function should consult the current routing table and return the IP address in network byte order of the router that should be used as the source address to send a packet to that destination. LwIP will use the source IP address when constructing the outgoing packet.  If no route exists, return 0.
    • sr_integ_ip_output(...)
      • This function is called by the transport layer for outgoing packets that need to be encapsulated in an IP packet and sent out over the network. This function must construct the appropriate IP header and Ethernet header and send the packet over the network (by eventually calling sr_integ_low_level_output()).
  • Create a thread that runs an echo server on TCP port 7
  • Create a user interface thread that does one of the following:
    • Runs a web server on TCP port 80 that presents a self explanatory web user interface, or
    • Runs a command line server on TCP port 1234 that presents a command line interface with a self explanatory help command
• ICMP
  • ICMP destination unreachable (unreachable protocol) should be returned if the transport layer is not TCP
  • ICMP destination unreachable (host or network unreachable) should be returned if there is no ARP response within the timeout period
• Your User Interface must allow the user to accomplish the following tasks
  • View VNS info (user, server, vhost, lhost, topology id)
  • View IP info (interfaces, routing table, ARP cache)
  • You must be able to modify the router state in the following ways:
    • Add a static ARP entry (given an IP address and a MAC address)
    • Delete any ARP entry (given an IP address)
    • Add a routing table entry (given a destination IP address, mask, gateway/next-hop IP address, and interface name)
    • Delete a routing table entry (given a destination IP address and mask)
    • Enable or disable an interface (given an interface name)
      • No packets should be sent or received over a disabled interface
    • Modify an interface (given an interface name, IP address, subnet mask, and MAC address)
    • Modify the ARP timouts
  • Provide the ability to generate a ping packet (ICMP echo request) to a given IP address and display the response

Echo Server

Your echo server must accept connections on TCP port 7 on all router interfaces. The server does not need to be concurrent - you only need to process one connection at a time. All the echo server needs to do is receive text over the network and echo it back to the sender a line at a time until the client closes the connection.

We strongly recommend that you implement the echo server before trying to implement your user interface. This will allow you to easily debug the interface between your router and the TCP/IP stack.

There are many echo server examples available online.  (Example 1, Example 2:  echo.c, echoserveri.c, csapp.h, csapp.c). Feel free to incorporate and build upon code you find, provided that you document it as such in the source code and your project report.

You do not need to implement an echo client in order to access the echo server. You can simply use telnet:

telnet <router ip address> 7

You will then have an open connection to the echo server. You should be able to type arbitrary text, hit enter, and receive the exact text back from the server.

User Interface

Your user interface must accept TCP connections on the appropriate port on all interfaces. You may choose to either implement a web interface or a command line interface (you do not need to do both). Your interface does not need to be concurrent - you only need to process one connection at a time.

If you choose to implement the user interface as a web server, you should integrate the web server directly into the user interface thread. It does not need to be a general purpose web server. You can simply accept simple HTTP requests and perform different functions based on the URL. The web pages you return should be intuitively obvious to use, but do not have to be elaborate or fancy.

• Tip: Instead of writing your own web server from scratch, you could integrate and modify an existing project, like the tiny web server [.tar file download].

If you choose to implement the user interface as a command line utility, it should also be directly integrated into the user interface thread. Your command line interface must support the command "help", which should provide sufficient information to perform all of the functions of the user interface. Do not assume that we will read your code in order to figure out your command line interface. You do not need to implement a client to access your command line interface - it can be accessed via telnet:

telnet <router ip address> 1234

You must fully document your user interface in the project report. We should be able to read your documentation as if it were a user manual. Therefore, it should explicitly tell us how to perform all of the functions required of the user interface.

Style

Coding style is very important for a large scale project of this type. Good style simplifies coding, debugging, maintenance, and extension of your code. You should refer to the following Software Style Guide for some pointers.

Deliverables

Project meetings

We will have regular project meetings throughout the semester. (Please consult the Schedule for the specific days). Over the course of this project, you group will be asked to informally discuss your design and implementation during these meetings.

Source code

You will submit your source code for the software router, which we will then build, run, and test on ecs-network.serv.pacific.edu. For more details, see Project Submission.

Project Report

Your should extend your project report from the first software project to include a clear and concise description of the overall design of your software router. You should update the document to address issues that were identified after the first project and you should add at least the following:

• A clear, concise description of how your router handles ARP timeouts
• A clear, concise description of how the TCP/IP stack is integrated into your router
• A clear, concise description of the design of your echo server
• A clear, concise description of the design of your user interface
• A user manual for your user interface
• An updated and expanded description of your testing methodology

We strongly encourage you to develop this document over the course of the project. It should serve as a design document for you in the beginning of the project, and should evolve to clearly describe the decisions you made and why you made them. This document serves to describe what you feel to be the correct functionality of your router. If it does not match your implementation, you will be penalized.

Grading

This project will be graded out of 100 points.

• Implementation / correctness: 60 points
• Usability of the user interface: 10 points
• Written report: 30 points

This guideline is not binding; we reserve the right to assign whatever grade we believe is fair.