|
CSE 588 - Spring 2002 - Fishnet Documentation |
|
 CSE Home |
CSE 588 Home |
About Us |
Search |
Contact Info |
Fishnet is a library which simplifies the process of building and deploying network protocols.
The term "Fishnet" is somewhat overloaded, and before going further we want to clarify what it means. First, it is a library (see the description of libfish.a below). This is also called the Fishnet development environment. Second, it is a running network of many nodes and a single fishhead (a key component described below). This is what we most commonly mean by a Fishnet. Note, however, that there are many potential Fishnets. You may all have independent, private Fishnets to develop and run your code, or you may want to combine your Fishnet with someone else's. Each Fishnet has a single Fishhead. Nodes within a Fishnet interact with the Fishhead they are pointed to. So if you want to run a shared Fishnet, you run a public, shared Fishhead.
Fishnet is only available for Linux, and only provides a C API. You have access to the blackbox cluster to develop and run your projects. The compiler we will use is gcc, and the debugger we will use is gdb. You can use any editor you prefer, such as emacs.
The Fishnet code is available for linux users or for Windows users with cygwin installed. See below for notes about using it with Windows. The package we provide you with contains the following key components:
fishhead is a program that manages Fishnet nodes. A network can contain many nodes, but only one fishhead. The main function of the fishhead is to tell individual nodes who their neighbors are. It is important to understand that the fishhead manages the network topology and decides who is connected to whom, not you in your programs. (For the curious, the nodes of networks you operate are run as separate processes that communicate with each other using a UDP overlay.)
When you develop a Fishnet node and run it, one of the first things it will do is to join a Fishnet network by contacting the fishhead. This means that before you start one of your Fishnet nodes there must be a fishhead process running. You only need to start a fishhead for your network once, even though the nodes in the network can come and go.
The fish library implements all of the Fishnet functionality that you will need for your assignments. When you send a message using the fish_sendframe() function, for example, libfish.a is called to do the work of sending the packet. libfish.a also prints a large (but controllable) amount of debugging information to the console (stderr) to help you understand what is going on with your program. The library source code is available in the fishsrc directory so that you can see how the Fishnet really works and to help with your debugging. If you want to interact with other people's nodes, you should not change this code. In fact, you should not need to in general. If you feel the need, please let bart@cs.washington.edu know.
This is the header file that you should include in your C program to gain access to the functionality implemented in the fish library. It contains the dozen or so Fishnet API functions that you can call, as well as the structures that define packet formats, and other Fishnet constants. You should read the comments in this file, as it contains the definitive Fishnet API documentation.
Here is a sample program (with source) to help you get started. You might want to look at the CSE461 web pages as well to get more information.
The program takes three whitespace separated command line arguments: first, a string representing the location of the fishhead, in the format "hostname:port"; second, the name of the domain which your node will belong to, which is simply a string and can be anything; third, the address you want for your Fishnet node, which is simply a small unique number.
When run, it joins the Fishnet described by the command line arguments using the fish_joinnetwork() call (you will need to have started the fishhead before running your program). Remember, you choose the address of the node, but the fishhead decides what other nodes it is connected to, and the neighbors can change as other nodes come and go.
Once running, it waits to get a line of input from the keyboard using fish_recvhook() and checks to see if the input is of the form "send <address> <message>", where <address> is a number representing the address of the node to send to, and <message> is a string that may contain spaces and is terminated by the end of the line.
When a command of this form has been received, the program sends a packet containing the message to a random neighbor using fish_send(). It does this by constructing a packet structure (struct packet) and filling in the source address, destination address, TTL, protocol, and packet contents as appropriate. In this example, the value of the TTL is the constant MAX_TTL, and the protocol is FISH_PROTOCOL_ECHO_REQUEST. These constants are defined in fish.h. The rest of the program described below will forward the packet through the network to its destination and cause an acknowledgement packet to be returned to the sending node.
The sample also waits to receive a packet from the network using fish_recvhook(). When a packet is received, it is dealt with as follows:
If the packet’s destination is not the current node, the TTL field is decremented. If the new value of the TTL is greater than 0, the packet will be forwarded to a random neighbor. Otherwise, the packet’s time to live has expired and it is dropped.
If the packet’s destination is the current node and the protocol is FISH_PROTOCOL_ECHO_REQUEST, the program (implementing that node) will print "Echo request from <address>: <message>", where <address> is the source of the packet and <message> is its data. It then makes a new packet with the protocol FISH_PROTOCOL_ECHO_RESPONSE and sends it back to the node that sent the original packet, with the original message as its data.
If the packet’s destination is the current node and the protocol is FISH_PROTOCOL_ECHO_RESPONSE, the program implementing that node will print "Echo response from <address>: <message>".
The sample program will repeat taking input, sending, receiving, and printing indefinitely, until you type "exit".
Read fish.h. The comments in this file tell you what the Fishnet API calls are, what they do, what arguments they take and return, and so forth. You won’t find this information anywhere else.
Make sure you can log into the blackbox cluster ( check machine status, individuals are often down). You are by no means required to use this cluster, but it is there for you if you want it.
Start a fishhead process to manage a Fishnet by running the fishhead program that is inside the fishnet directory. Type './fishhead --help' to find out what command line arguments it accepts. You will need to give it a argument to indicate which port it should listen on for messages. Pick a number between 1024 and 32K. If the number you choose is the same as someone else’s fishhead will fail to start. The fishhead program runs indefinitely to keep the Fishnet it is running up. You should leave it running and create another window in which to do your development. When you’re done, stop it by typing CTRL-C (^C).
When testing your programs, you will probably find it easiest to bring up a separate window for each node, as well as the window for the fishhead. If you enabled libfish debugging messages using the fish_setdebuglevel() function, you should also see how your packets move through the network.
Thanks to Rajesh Hegde, we now have a Visual Studio port of fishnet. There is a version for Visual Studio 6 users and a version for Visual Studio .NET.
When you unzip the file of your choice, you will get three directories:
 |
Department of Computer Science & Engineering University of Washington Box 352350 Seattle, WA 98195-2350 (206) 543-1695 voice, (206) 543-2969 FAX [comments to owner-cse588] |