1. INTRODUCTION 2. A SAMPLE SESSION 3. FILES IN THIS DISTRIBUTION 4. ENVIRONMENT VARIABLES 5. COMMAND LINE USAGE 6. QUERYDB FORMAT 7. DEBUGGING OUTPUT 8. UNIX 101 ------------------------------------------------------------ 1. INTRODUCTION ------------------------------------------------------------ This is an implementation of the PEFF protocol. There are two components, peffd and peffc (the daemon and client). The job of peffd is to speak the PEFF protocol to other servers. It does not interact with the user at all. The peffc program is used to make individual queries; it does this by connecting to the peffd program over a unix-domain socket and specifying its request. This separation was done to make the implementation more straightforward. The peffd program does not have to deal with an interactive interface. ------------------------------------------------------------ 2. A SAMPLE SESSION ------------------------------------------------------------ 1. User starts peffd: ./peffd querydb 2. peffd connects to other PEFF nodes 3. User makes a query with peffc: ./peffc somefile 4. peffc connects to peffd over $PEFFD_CLIENT socket and indicates query 5. peffd assigns an id to client connection and sends QUERY message to other nodes 6. peffd receives FOUND messages from other nodes; the id field is used to correlate them with the client connection 7. peffd reports FOUND results to peffc client over socket 8. peffc reports results to stdout 9. peffc decides it has waited long enough for results and exits A user may repeat steps 3-9 without restarting peffd. Multiple queries can be done simultaneously. ------------------------------------------------------------ 3. FILES IN THIS DISTRIBUTION ------------------------------------------------------------ peffd-sunos-5.8 - peffd compiled on gaia.cc.gatech.edu; it should work on any of the Solaris machines peffc-sunos-5.8 - peffc for Solaris peffd-linux - peffd compile for linux; it is statically linked, so it should work on any distribution with a 2.4 series kernel. It will probably also work on a 2.2 series kernel. peffc-linux - peffc for Linux querydb - a sample query database file README - this file ------------------------------------------------------------ 4. ENVIRONMENT VARIABLES ------------------------------------------------------------ PEFFD_CLIENT - filename of the socket to be used for communication between peffd and peffc. peffd will create the socket. This must be in a directory writeable by the user running peffd. PEFFD_LOCALIP - the local IP address to use. peffd will bind to this address and use it in MISSING and QUERY messages. The format is either a hostname (whose IP will be used) or an IP in dotted-decimal (e.g., 127.0.0.1) format. ------------------------------------------------------------ 5. COMMAND LINE USAGE ------------------------------------------------------------ peffd querydb [neighbor] querydb - the name of the file containing the "answers" to queries. The format is described in the next section. neighbor - this parameter is optional. If specified, it is the hostname or IP address of a node in the ring. peffd will attempt to connect to it to join the ring. Otherwise, peffd will wait for another node to connect to it. peffd will produce copious debugging output on stderr describing the protocol. The format of this output is described later. peffc query [timeout] query - this parameter is a string to search for in the PEFF network timeout - this parameter is optional. If specified, it indicates the number of seconds after which peffc will exit. If not specified, defaults to 10. peffc will produce output on stdout; each FOUND result that is returned will be on its own line. ------------------------------------------------------------ 6. QUERYDB FORMAT ------------------------------------------------------------ The format of the querydb file is: - one entry per line - blank lines are ignored - lines beginning with the '#' character are ignored Each entry should be a URL pointing to a particular file. The entire string will be matched against when determining if a query matches. The entire string will be sent as the results in a FOUND message. NOTE: peffc does not actually do anything with the URLs (like try to access them). It only prints them to stdout. So you can just put random strings in the querydb and match against them (unless the requesting client actually tries to do something useful with them). ------------------------------------------------------------ 7. DEBUGGING OUTPUT ------------------------------------------------------------ The debugging output from peffd is fairly simple. Every line begins with "peffd: debug: ". After that is type, which is one of: - send; peffd tried to send a message. The destination IP and message type follow, along with any type-specific fields: - QUERY is followed by one of: - (forward); the message is a forward of the last QUERY received - qtype id ttl localip string - MISSING is followed by one of: - (forward); the message is a forward of the last MISSING received - localip - FOUND is followed by: ftype id string - recv; peffd received a packet. The sender IP and message type follow, along with any type-specific fields: - QUERY is followed by one of: - ignore; the message was ignored; a reason is given afterwards. - qtype id ttl localip string - MISSING is followed by one of: - ignore; the message was ignored; a reason is given afterwards. - localip - FOUND is followed by: ftype id string - expire; a timer expired; the name of the timer follows. - status; the current state of the protocol. This is output after every "event" (either a message being handled, or a timer expiring). It specifies the current numeric state, followed by the values of c0, c0_alive, c1, and c1_alive. ------------------------------------------------------------ 8. UNIX 101 ------------------------------------------------------------ Here are things you'll need to know about Unix in order to get this running on one of the Solaris machines. Examples of the form "$ foo" mean to type "foo" at the shell prompt (which is generally a "$"). UNPACKING THE ARCHIVE: $ gunzip -c peffd-reference.tar.gz | tar xvf - will unpack the archive into the peffd-reference directory. I will give the next set of instructions for Bourne-shell (/bin/sh or bash). If you're using the C-shell, you should run the Bourne-shell "bash". If you don't know which shell you're running, start bash just to be sure. SETTING ENVIRONMENT VARIABLES $ export VARIABLENAME=value $ export PEFFD_CLIENT=/tmp/p2psocket will set the variables for the current shell only. Note that each terminal window or login that yo ustart runs its own shell. RUNNING PROGRAMS Unlike other operating systems, the current directory isn't generally in your PATH, so you need to indicate the location of the program when you execute it: $ ./peffc my-query $ ./peffd querydb gaia.cc.gatech.edu REDIRECTING OUTPUT If you want to save output to a file, you can use redirection. Redirect stdout like this: $ ./peffc my-query >query.output Redirect stderr like this: $ ./peffd querydb gaia.cc.gatech.edu 2>peffd.log