EE122 Project #3: Phase 2
Page Last Updated: Dec 6, 3:30PM
Updates
- Dec 6, 2006: Submission guidelines added
In this phase you will implement a file sharing application. Your application will use the directory lookup protocol specified here for locating the files the user wishes to download.
Once the IP address and port number of a peer having the file is found, the application will contact the peer and download the requested file.
The download is done using your own custom, reliable transport protocol,
which you design and implement. (You are not allowed to use TCP.)
You should also design your own peer-to-peer protocol for requesting and transferring the requested file - this design must be described in the README file.
For full credit,
the reliable transport protocol you implement needs to use a window-based
scheme. (Simple stop-and-wait is worth partial credit.) Your reliable transport protocol must be able to handle dropped and re-ordered packets. However,
to keep the project tractable in the time available, you are not required to implement congestion control.
You must describe your protocol in your README file.
The computers available for testing your implementation are all located
in the same building, possibly on the same LAN. In such a scenario, the
RTT is often very low, and packet drops are rare. In order to simulate
packet drops, packet re-ordering and high RTTs, you will send your UDP
packets through a network emulator and not directly using the
regular UDP sendto() function. You do this by use the
MNL Emulator (MNL = My Network Layer), which
replaces sendto() with its own custom call, MNL_sendto().
Please click
on the link for more information on how to use the MNL
emulator.
Input/Output Specifications
Your code should compile to create an executable program called BFS (BFS = Berkeley File Sharer).
You MUST supply a Makefile and a README file. The program should have 5 modes of operation.
- Listen : In this mode, BFS will wait for file get requests from other peers. BFS will be invoked as follows:
BFS listen PORT
where PORT is the port on which BFS waits for file get requests from other peers. Depending on how you structure your implementation,
PORT is most likely to be the UDP port associated with your reliable transport. When BFS is started in this mode, it will continuously listen
for file get requests. The program will be terminated only if you kill it using Ctrl-C.
- Register : This mode is used to register a file that you wish to share with directory server. BFS will be invoked as follows:
BFS register FILENAME PORT PASSWORD
where FILENAME is the name of the file you wish to share. All files that you wish to share must be located in a sub-directory called ToShareDir,
located in the same directory as the BFS executable. This means that you need to specify only the file name and not the entire file path while registering a file.
You can assume that the sub-directory ToShareDir will exist in the evaluation setup. PORT is the port which we passed to an instance of BFS we already have started in listen mode.
PASSWORD is the password associated with this file registration. The password will be required if we need to unregister the file at a later time.
If some error occurs while registering, print an appropriate error message.
BFS should exit after registering the file - either successfully or unsuccessfully.
- Unregister : This mode is used to unregister a file which you no longer wish to share. BFS will be invoked as follows:
BFS unregister FILENAME PORT PASSWORD
where FILENAME is the name of the file you wish to unregister; PORT and PASSWORD are the port number and password specified while registering the file.
The unregister message that is sent to the directory server needs to include the port number (as well as the IP address) in order to uniquely
identify the record to be removed (Other peers might have registered the same filename with the a different IP address or port).
If some error occurs while unregistering, print an appropriate error message.
BFS should exit after unregistering the file - either successfully or unsuccessfully.
- Lookup : This mode is used to list the peers (IP address and port number) which are sharing a specific file. BFS will be invoked as follows:
BFS lookup FILENAME
where FILENAME is the name of the file we wish to look up. BFS should query the directory server and print out a list of peers offering FILENAME.
The file should not be transferred in this mode of operation - we just want to see if anyone has the file we are interested in. BFS should exit after printing the list of peers.
- Fetch : This mode is used to fetch a file from one of the peers that has it. BFS will be invoked as follows:
BFS fetch FILENAME
where FILENAME is the name of the file we are interested in. BFS should obtain a list of peers offering the file from the directory server and then
fetch the file from the peer. If multiple peers have the file, fetch the file from any one of them and exit. It is possible that no one has the file we are looking for. In that case,
BFS will print an error message and exit. The fetched file should be stored in a subdirectory called FetchedFiles. You can assume that this subdirectory will exist in the
directory containing the BFS executable.
The popular file sharing applications have much simpler user interfaces. For example, you do not have to start two separate instances of the client - one for listening for file requests and the other for registering files to be shared. The simple interface above has been suggested only for the sake of easy implementation. You are free to implement your own interface as long as it can support the above operations and works on the EECS instructional accounts. If you are implementing your own interface, you must provide instructions on how to invoke the above operations in the README.
You do not have to submit any tcpdump trace files. However, you may want to use tcpdump as a debugging tool while implementing your program.
Evaluation Setup
The following is an example evaluation setup with 3 machines A, B and C.
- Machine A : Start BFS in listen mode in one terminal window.
BFS listen 2222
- Machine A : Register multiple files file1, file2, file3, etc. from a different terminal window (but logged into
the same machine as the server you already started).
BFS register file1 2222
BFS register file2 2222
BFS register file3 2222
- Machine B : Machine B has a setup similar to A. BFS in listen mode will be listening on port 3333. A possibly different set of files will be registered by B.
- Machine C : Run BFS to look up a file. Run BFS to fetch a file.
BFS lookup file1
BFS fetch file4
- Different file names and port numbers will be used during evaluation.
The actual evaluation setup will involve more machines and files. Files of different sizes - from 1 byte to 10 MB - will be fetched between different machines. A file fetched from a peer should be identical to the original file at the peer. The diff program will be used to check if two files are identical. If the fetched file is not identical to the original file, you will not receive any points for that particular test case. Your program will be tested under different network conditions (Please see MNL for details about different network conditions).
Deliverables
- Source code of your file sharing application. A Makefile must be supplied - otherwise you will lose 5 points.
- A README file with the following information:
- Description of the user interface of your application (if different from the interface described in Input/Output Specifications)
- Design and features of your reliable transport protocol.
- Design and features of your peer-to-peer protocol.
- Specify which reliable transport scheme you should be graded for (See section on Grading for more information).
- tcpdump tracefiles are NOT required.
Reliable Transport: Congestion Control, Flow Control and Unidirectional Transfers
- Congestion control is not required. It is now part of extra credit.
- Flow control is not mandatory. However, depending on how you structure your implementation, flow control may turn out to be essential to transfer files reliably.
- You do not have to optimize for unidirectional transfers. This requirement was removed as some students expressed interest in implementing a common reliable bi-directional transport protocol which can be used for the p2p protocol as well as the actual file transfer.
Please Note
- You will not be implementing the directory lookup protocol you designed in phase 1. Instead you will be implementing the directory protocol described here.
- You are not allowed to use TCP anywhere inside your program.
- The directory lookup protocol operates over regular UDP.
- The reliable transport protocol does NOT operate over regular UDP. You must use the MNL emulator.
- The peer-to-peer protocol can use regular UDP or the reliable transport protocol you implement. The peer-to-peer protocol involves messages like telling the peer the name of the file you wish to fetch. Actual transfer of the file data must use the reliable transport protocol you implement, and not regular UDP.
- Please prefix the filenames you register with the last 2 letters of the instructional login id of one of the team members. This is strictly not required, but may help while debugging your program.
Grading
Phase 2 is worth 160 points (80% of the project 3 grade) + 30 extra credits.
- Directory Lookup Protocol Implementation (60 points)
You will receive full points in this category if you support all the operations of the directory lookup protocol described above.
You must also gracefully handle errors by printing out appropriate error messages.
- Reliable Transport - Stop and Wait (60 points)
If you implement the simple Stop and Wait scheme, you can get up to 60 points for the reliable transport portion of the project, for a total possible score of 120 out of 160 points.
- Reliable Transport - Sliding Window-based scheme (100 points)
If instead you implement a sliding window based scheme, you can get up to the maximum 100 points for the reliable transport portion of the project, for a total possible score of 160 out of 160 points.
You should implement ONE of the two possible reliable transport schemes. You will be graded for only one of the schemes. You must specify which scheme
you wish to be graded for in your README file. For example, if you choose to implement the Stop and Wait scheme and pass all test cases, you will receive 120/160 for project 3 phase 2. If you choose to implement the Sliding Window-based scheme and pass all test cases, you will receive 160/160.
- Extra Credits - Congestion Control and Flow Control (30 points)
You will receive 23 extra credit points if you implement congestion control.
You may use a subset of TCP-like congestion control mechanisms. Points will be awarded on the basis of how comprehensive your scheme is; For example, implementing Fast Retransmit will fetch you more points than only relying on packet drops to detect congestion.
Be sure to describe the congestion control scheme you use in the README. You will receive 7 extra credit points for implementing flow control.
Submission Guidelines For Phase 2
- Log in to your instructional account.
- Create a directory called "proj3phase2" : mkdir proj3phase2
- Change to that directory: cd proj3phase2
- Copy all the files/subdirs that you wish to submit to this directory
- Run the submit program: submit proj3phase2
- Make sure that no error messages are displayed. If some error occurs, retry. If it still occurs, contact the TAs.
FAQs and Clarifications
-
Should my BFS program be interoperable with programs built by other teams?
Answer: No.