Introduction to Fishnet

Last Update: Mon Apr 28 23:23:45 PDT 2003 - The update is to make it more clear, no requirement is changed or added.

This informational handout covers introductory material describing the Fishnet software that you use, the Fishnet programs that you write, the development environment, and testing strategies.

1. What is Fishnet?

Fishnet is a class-sized network that we will build over the quarter! You will each build one node of the network, working in pairs, over a series of assignments. Once we are done, nodes from each team will be able to route messages and share files over a shared network that we will build.

The term "Fishnet" is somewhat overloaded, and before going further we want to clarify what it means. First, it is the code that makes up all of the assignments. This is the Fishnet development environment. Second, it is a running network of many nodes. This is what we most commonly mean by Fishnet. Note, however, that there are many potential running Fishnet networks. You will all start your own, private, fishnet as a managed overlay controlled by a single fishhead (a key component to be described shortly) to develop and test the code required for assignments. It will run as cluster of processes on one or more PCs. In this form your nodes will not interact with nodes of other students' networks. There is also The Fishnet, with a capital “T”. This is the one, shared network that everyone's node is able to join and participate in a collective class network. This is accomplished simply by pointing your code at a public fishhead server that we run.

1.1 Fishnet Components

The Fishnet project code, like everything else you need, is available from the course web site. The package we provide you with contains the following key components.

1.1.1 fishhead

fishhead is a program that manages fishnet nodes for your development and testing. A fishnet contains many nodes, but one fishhead. The main function of the fishhead is to tell individual nodes who their neighbors are. It is important to understand the fishhead manages the network topology and decides who connected to whom, not you or your program. We will run a special instance of fishhead at pisa.ucsd.edu:7777 to host the production class fishnet.

As you develop your Fishnet node and test it, one of the first things it will do is to join a private 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. Type ./fishhead -h to get usage information.

1.1.2 libfish.a

The fishnet library implements all of the Fishnet functionality that you will need for your assignments. When you send a message using the fish_send() function, for example, libfish.a is called to do the work of sending the packet. libfish.a also prints a large (but controllable by using fish_setdebuglevel()) amount of debugging information to help you understand what is going on with your program.

1.1.3 fish.h

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 and only Fishnet API documentation.

2 Hello World in Fishnet

2.1 Setup a fishnet

The first exercise you should complete is to learn how to compile and run Fishnet, and inspect the hello program that is bundled with the distribution.

Login to one of the lab (uAPE, EBU1, or ieng9) machines. All of your work should take place on these machines.
After login, do the following commands to get our fishnet package:
```
% cd $HOME

% cp ../public/cs123b.tar  .

% tar xvf cs123b.tar

% make hello

Pick a random port between 1024 and 65535, say 4173

% ./fishhead -p 4173
```
Note: do not kill the fishhead (do not hit CTRL-C).
Now start a new shell. If you are using X window (i.e. your are in the lab), you can start a new terminal window. If you are remotely logged in, you can start antoher remote login connection to get new shell.
```
% ./hello [hostname]:4173 105
```
This creates a node with address 105. If it is not running, make sure your fishhead is running at the same port (Did you kill fishhead by hitting CTRL-C or closing the window?).
Now start another new shell and run another hello node with address 33.
```
% ./hello [hostname]:4173 33

This creates another node with address 33, now you can try to say 
hello to each other by input these command to these nodes

hi 105

hi 33
```
If something is wrong, please email TA (ycheng@cs.ucsd.edu) including which step is wrong and the error messages.
Check the fishnet topology at web http://[hostname]:4173/ . You can try to run more fish nodes by creating more shells and runing more hello programs.

2.2 Learn to program fishnet from hello.c

hello.c provides good sample code to start first homework with two important aspects:

Fishnet API is in fish.h As you look at hello.c, you will see that it calls functions with names like fish_send(). These are Fishnet API calls. All of these calls are explained and documented with comments in fish.h. The documentation includes comments for the structures representing packets that are passed to and from. You won't find this information anywhere else.
Fishnet program structure All Fishnet programs have a similar structure. They are event-driven, like much real world code and especially any programs with GUIs that you may have written. What this means is that they typically use main() to initialize and then enter the main event loop. Initializing involves joining the fishnet with fish_joinnetwork() and setting up functions to be called on specific events, e.g., a on_receive() function to be called when there is keyboard input. Entering the main event loop is done by calling fish_main(), a call that never returns and from which the program is terminated directly when "exit" is typed at the keyboard. Events such as packet reception are handled as "upcalls" from the main loop.

3. Development and Testing

Here are some other points you should note before start coding:

Develop the entire code in files called hw1.c, hw2.c, etc. We supply a Makefile so you can simply type "make hw1" to compile your program. We will also compile your program exactly the same way ("make hw1"). Please avoid chaning the Makefile to fix your program. Note, it is your problem if your program don't compile with the provided Makefile.
Access the Fishnet API by including fish.h in your program.
These C library functions maybe helpful: atoi, printf, sscanf, strlen, and strncpy. Type man -s 3c <function> to get more help.
The feasible way to develop complex software is to break the task down into simpler, checkable subtasks. You might first write a program that had a main() function that simply accepts the command line arguments, prints them out, and exits. When this compiles and runs properly (experience shows most of you will have found and fixed at least one error already!) move to the next task. The next task might be joining the network and sitting in fish_main(). You can use debugging messages to check if this program has worked, as you will get messages when you have joined. Next, you might try for keyboard input, and print it out but not send a packet yet, and so forth. While this strategy might seem like overkill at this stage, you should get used to it before attempting the larger assignments, and particularly when you find that something is not working properly. The beauty of testing functions is that the problems are rarely where you think they are and testing is the only way to pin them down. Despite this strategy, more difficult bugs will require you to use the debugger, gdb.
The first way you should test your code when it is written is to run multiple copies of your node in your own private fishnet, as you did for hello. Unless you've disabled them using the fish_setdebuglevel() function, you will see libfish debugging messages that show how your packets move through the network. Also, note that there are Fishnet API functions for logging debugging output to a file for later inspection.
The second way you should test your code is to run it with a combination of your node and our sample executables called hw1-sol, hw2-sol, etc. This will check whether the different versions are interoperable. You must have an interoperable node before joining the live class network, or you may cause that network to experience problems.
Remember you can always observe the topology of the fishnet by browsing http://[hostname]:[port]/
You may use other development tools, but we won't support them.
Finally you should test on The Fishnet by connecting your programs to the fishhead at pisa.ucsd.edu:7777.

Congradulations! Since you hit here so far, you are certainly ready for the first assignment.

April 24, 2003
UCSD CSE123b Communications Software