Dates

• Friday, May 3, 2013: Review session from 4:15-5:05pm in the NVIDIA Auditorium
• Friday, May 10, 2013: Protocol specification due (the first part of your final write-up). Submit it using the submit script.
• Friday, May 17, 2013: Final submission due.

Intro

The goal of this assignment is to implement client and server prototypes for a distributed file system in which the files are replicated. The purpose of this assignment is to explore a service-specific protocol, relying on transactions for reliable delivery rather than conventional transport techniques; the prototype you will create will focus on this aspect of the file system. The primary invariant that must be maintained is that all available copies of the file must be the same. This is useful in systems that support read-any, i.e., where clients may read from any available replica and know they're getting the latest version.

Machine Compatibility

Your program must run on the myth Linux machines in Gates B08 (myth*.stanford.edu). You should use multicast packets to disseminate state as with the previous Mazewar assignment. You are not allowed to use physical broadcast packets to disseminate state. You can re-use the multicast setup code from your first asssignment. The multicast group address is same as first assignment, namely 0xe0010101.

Structure, Interfaces, and Implementation

Your goal is to provide us with the following:

• A client-side library libclientReplFs.a that communicates with the servers. It handles accesses from the application and propagates them to the servers. The application interface that the client library has to support is specified later in this specification.
• The server executable is called replFsServer. Each server maintains a copy of the replicated files and keeps track of all updates made to the files.
• A makefile that produces the above.

• The interface to be supported by your client API.
• A few simple restrictions on how the server & client executables behave (e.g., required parameters).
• A sample client application. The application uses the client interface to make write calls to a replicated file. This code links with your client library and runs on the client host, thereby providing a basic test case for your client and server implementations. Note that this does not necessarily include all of the routines we will use to test your system; it is a starting point only.
• Skeleton client-side code. You may use this code and fill in the missing parts or write your own client-side code from scratch.
• A sample makefile that builds the client-side library libclientReplFs.a and links the sample application code. You are free to extend the given makefile and add replFsServer generation to it or to write your own makefile.

The framework code we provide is in /usr/class/cs244b/replFs.
Applications which wish to use the distributed filesystem link to the client-side library and use the client-side interface to make write calls to replicated files. Of course, to this application, the replication and use of the network must be entirely transparent. Your most important tasks are to design and implement the client/server protocol.

Required Client API (Application Programming Interface)

Conspicuous by its absence is the lack of a ReadBlock() call in this API. Reading is not required for this assignment. We will use the files that your server stores locally to validate committed writes.

• InitReplFs() gives your filesystem a chance to perform any startup tasks and informs your system which UDP port # it is to use. It is also given the percentage (0 to 100) of packets that should be randomly dropped, on the client only, when they are received from the network. (Servers have a similar argument to drop packets randomly on receipt; in no case should packets be randomly dropped on transmit.) Finally, numServers specifies the number of servers that must be present in order to successfully commit changes to a file (you can assume servers will not come and go while your client is running). Your system does not have to function correctly if InitReplFs() is not called prior to using the other calls.
  
  Return value: 0 (NormalReturn)
  Return value: -1 on failure (ErrorReturn) MAY be returned if a server is unavailable.
  
  
• OpenFile() takes the name of a file and returns a file descriptor or error code. The server must not truncate existing files when reopened. Your code only needs to handle flat names; it does not need to handle names containing a slash. Your implementation MUST handle names up to at least 127 bytes in length, including the null terminator. Your server must open this exact file relative to your mount directory; this will be used to test your code.
  
  Return value: a file descriptor >0 on success.
  Return value: -1 on failure (ErrorReturn) MAY be returned if a server is unavailable. It MAY also be returned if the implementation can only handle one open file at a time and the application is attempting to open a second.
  
  
• WriteBlock() stages a contiguous chunk of data to be written upon Commit(). fd is the file descriptor of the file to write to, as returned by a previous call to OpenFile. buffer is a pointer to the data to be written, and blockSize is the number of bytes in buffer. byteOffset is the offset within the file to write to. Your code must handle overlapping writes.
  
  Return value: The number of bytes staged (blockSize).
  Return value: -1 (ErrorReturn) MAY be returned if the client violates the maximum block size, file size, or number of staged writes before Commit(). Assumptions you may make about these limits are listed here. This MUST be returned if the file descriptor is invalid. This value MUST NOT be returned if a server is unavailable.
  
  
• Commit() takes a file descriptor and commits all writes made via WriteBlock() since the last Commit() or Abort().
  
  Return value: 0 (NormalReturn) on success (i.e., changes made were committed).
  Return value: -1 (ErrorReturn) MUST be returned if the client had outstanding changes and a server is unavailable (so the changes could not be committed). It MAY be returned if the client had no outstanding changes and a server is unavailable.
  
  
• Abort() takes a file descriptor and discards all changes since the last commit.
  
  Return value: 0 (NormalReturn).
  Return value: -1 (ErrorReturn) may be returned if the file descriptor is invalid.
  
  
• Close() relinquishes all control that the client had with the file. Close() also attempts to commit all changes that have not been saved.
  
  Return values: same as in Commit().

Protocol Skeleton

In providing the API listed above, the library code at the client and the file servers conspire to provide distributed replicated files. While we have provided an outline of how you should do this, your first job should be to flesh out this skeleton.

A brief outline of the steps involved with accessing a file:

1. The client opens the file by multicasting to the servers and collecting responses. All reachable & running servers must be accounted for.
2. The client multicasts writes across the net. Upon receiving these writes, the servers buffer the changes to the file. Note specifically that there are no ACKs at this stage.
3. If the application commits, two phase commit is used to ensure that all updates from the previous step were received. (If not received, this information must somehow be retransmitted). Upon preparing to commit changes to a file, the client needs to identify to the servers in some way the list of updates to the server to commit, making sure that every server has all of the changes before sending a commit message. If all of the servers return an ``OK to commit'' message, the client then sends out a commit message. Alternatively, the client may send an abort message whereupon the servers revert the file to its previous state.

Assignment Assumptions

For this assignment, you are allowed and required to assume the following:

System-Wide Details

• Servers must handle at least a single client, single file, and single pending transaction at a time.
• Your server executable must accept and honor these parameters:
  • -port port#: UDP port # for fs communication. (so we can test it)
    
  • -mount filepath : place where committed local copies are to be stored by the server.
    
  • -drop percentage : the percentage (0 to 100) of packets that should be randomly dropped, on this server only, when they are received from the network. (Clients have a similar argument to drop packets randomly on receipt; in no case should packets be randomly dropped on transmit.)
    

• You may assume these parameters are always specified in that exact order to simplify your command line parsing.
• Your server must maintain committed versions of files in the location specified by the -mount parameter. On server startup, if this directory already exists, the server MUST die with a message "machine already in use". If such a directory does not exist, it MUST create it. Your server MUST NOT remove the mount directory on server termination! For example, if the server is started with:

  replFsServer -port 4137 -mount /folder1/fs244b -drop 3

  And a client opens file "jane.txt" using OpenFile("jane.txt"), the server must create the file: /folder1/fs244b/jane.txt.

  Note: you must comply with this scheme. It will be used to grade your system. Systems which do not comply will be considered nonworking.