
  distributed.net client documentation
  document revision $Id: dnetc.txt,v 1.1.2.4 2000/04/21 13:26:33 cyp Exp $

  Copyright distributed.net 1997-2000 - All Rights Reserved
  For use in distributed.net projects only.
  Any other distribution violates copyright.

  Use of the distributed.net client implies agreement with
  the prize terms listed on http://www.distributed.net/

 Index ---------------------------------------------------------------

    1.0  Introduction   
    2.0  General system requirements 
         refer to platform specific readme.s for details
    3.0  Getting and starting the client
         refer to platform specific readme.s for details
    4.0  Upgrading from a client older than the 2.7xxx
    5.0  Fetching and flushing work
         5.1 over a TCP/IP network connection (and/or through a firewall)
         5.2 via e-mail
         5.3 to/from "remote" buffers that are serviced by another client 
    6.0  Help!

 1.0  Introduction ---------------------------------------------------

    Congratulations! This distributed.net client will make your computer 
    a part of the world's largest computer, distributed.net. The client 
    you have downloaded is capable of working on two of distributed.net's
    ongoing projects: The brute-force decryption of a RC5-64 message, and
    the brute force decryption of a DES message. The RC5-64 contest is a
    long-term contest, which may take a couple of years to solve. The DES
    contests, run twice a year, are short (refer to the DES contest 
    documentation for details). As a result, this client will work on DES 
    during DES contests, and switch back to RC5-64 when no DES contest is 
    running. No user intervention is required for this switchover.

 2.0  General system requirements ------------------------------------

    The system requirements for the client vary from platform to platform
    and are detailed in the readme.* you should have received when you
    downloaded the client.

    In general, all that is required is:
    - a 32-bit processor
    - one megabyte of free memory
    - a method to update local buffers (fetch/flush work). See section 5.
    - less than a megabyte of disk space (optional)

    The most important requirement for running the distributed.net client,
    of course, is authorization to run the client on the computer that it
    is installed on. This is not an issue with your home computer, but 
    many companies and schools have policies against running outside 
    programs on their computers. In cases where such a policy exists, ask 
    your system administrator BEFORE attempting to install the client. 
    It is very possible that he/she will like the idea, and choose to 
    install the client on all computers at that site. However, if the 
    answer is a 'no', do not push the issue. RSA's contest rules stipulate 
    that all clients must be run on authorized systems. The only support 
    we will give to unauthorized installations is help in uninstalling 
    them.

    Although there are a number of platforms that meet these requirements,
    distributed.net cannot create or maintain clients for them all. The
    prerequisites for creating a client for a platform are: 
    - a C++ compiler is available for that platform
    - the compiler 'understands' 64bit quanta ('long long', 'wide' etc)
    - distributed.net must have access to such a machine

    If you know of a platform that fulfills these requirements, and would
    like to have a client for the platform, you can request it at
    http://www.distributed.net/porting/

                                                                     
 3.0  Getting and starting the client --------------------------------

    Clients are (barring a few exceptions) *only* available from 
    http://www.distributed.net/download/ or from ftp servers linked from 
    that page. They are occasionally available directly from distributed.net 
    coders in the #distributed channel on EFNet IRC. FreeBSD clients are 
    also available on FreeBSD distribution CDs. 

    Once you have downloaded the client, it is a simple matter of getting
    going. Simply unpack/unzip/unarc the archive you downloaded and fire 
    it up. 
    
    If you have never run the client before, it will initiate the
    menu-driven configuration. Save and quit when done, the 
    configuration file will be saved in the same directory as the 
    client. Then, simply restart the client. From that point on it will 
    use the saved configuration.
    
    Each configuration option is accompanied by a description that will
    assist you in making the right decisions. Most default values can be
    accepted as-is. Refer to the Help! section at the end of this document
    for sources of assistance.

    A "Complete Step-by-Step Guide to Running Your First Client" is 
    available from http://distributed.net/faq/

    The client's configuration may be adjusted at any time by starting 
    the client with the -config switch. A list of other command line 
    options can be obtained by starting the client with -help.


 4.0  Upgrading from a client older than the 2.7xxx ------------------

     If you are upgrading from a version of the client older than the 
     2.7xxx series, please stop the existing client, flush its buffers, 
     delete all of its files before installing the new client. Buffer 
     files formats have changed, and this will help prevent compatibility 
     problems. If you are sharing buffer files between multiple clients, 
     please make sure that the clients have compatible buffer formats.

                                                                          
 5.0  Fetching and flushing work -------------------------------------
 
     The distributed.net client can fetch/flush work using 3 methods:
     1) over a TCP/IP network connection
     2) via e-mail
     3) to/from "remote" buffers that are serviced by another client 
     In addition, it can share buffers with another client.
 
  5.1  Fetching and flushing work over a TCP/IP connection ---

     The client uses normal TCP/IP to communicate with keyservers.
     It connects to port TCP port 2064 by default. 

     distributed.net keyserver hostnames follow the following naming
     convention: <us|euro|asia|aussie|jp>[port].v27.distributed.net .
     The "port" is an optional field and may be either "80" or "23".
     All other numbers cause the client to ignore it and automatically
     select a hostname (see next para).
     
     It is generally not necessary to set a specific distributed.net
     keyserver hostname. The client can automatically pick one in your 
     approximate vicinity if you leave it blank.
          
     If you do not connect through a firewall, or access to port 2064 is
     permitted, you can leave all network-related options at their
     default values.

     If you are connected through a strict firewall, port 2064 may
     be blocked by default. There are a number of methods to allow your
     client to fetch/flush...

     Configuring for firewall support is easy.
     a) Enter the configuration
     b) Select "Buffer and Buffer Update Options" menu
        If "Disable buffer updates to/from a keyserver" is "on",
	turn it off.
     c) Select in the "Keyserver<->client connectivity" submenu. 
     Read on...
     
     If you have administrative access to the firewall machine, it is
     probably easiest to use a "data pipe" or if you are using WinGate 
     or Internet Gate, using "direct port mapping". Both describe 
     essentially the same thing: A piece of software, either internal
     to or separate from the firewall software itself, map ports on one
     side of the firewall to ports on the other side. That is, the "data
     pipe" listens for connections on a particular port on the inside of
     the firewall, and forwards these to a predefined host/port on the 
     other side. Set the client's "keyserver host" and "keyserver port" 
     to point to the datapipe, and configure the datapipe to connect
     to a distributed.net host (refer to the beginning of this section 
     for information on distributed.net host names).
     
     Another method requiring administrative access, but with great 
     advantages if you have a number of clients running inside the 
     firewall, is to use a distributed.net personal proxy on the 
     firewall machine. Personal proxies may be downloaded from 
     http://www.distributed.net/download/. Configuration guides for setting 
     up a personal proxy are beyond the scope of this document, but for 
     the client, configuration is the same as that for a "datapipe" (in 
     the section above).

     If your firewall permits access to telnet ports (port 23), or
     to HTTP ports (port 80), simply set the "Keyserver port" to that
     port. If it doesn't work, and you are sure that access to telnet 
     ports is permitted, it is possible that your firewall does not
     cleanly handle 8bit data. Try again after enabling "Always use 
     UUEncoding". UUE converts the 8bit data that that the client tries 
     to send into 7bit data, permitting buffer updates to work even when 
     8bit data is not handled cleanly. This situation does not happen
     very often, but it does occur now and then.
     
     In addition to these "native" connectivity methods, the client
     also has HTTP and SOCKS proxy support:
     
     Select the "Firewall/proxy protocol" option from the menu and...

     For SOCKS support:
          
        Both SOCKS[4] and SOCKSv5 are supported. If you are unsure about 
	which to use, try SOCKS4 first. Now, edit the "HTTP/SOCKS host" and 
	"HTTP/SOCKS proxy port" and ensure that they point to the SOCKS 
        proxy you will be communicating through. If you must use a SOCKS 
        userid/password, enter it in the appropriate field as well. (Note:
	only SOCKS5 uses passwords, so that field is invisible if you
	select SOCKS4).
	
     For HTTP proxy support:
     
        The most compatible firewall communications method is to select
        "HTTP proxy" support. Next, enter the name/address of the HTTP 
	proxy in the "HTTP/SOCKS proxy host" field and the port number 
	of the HTTP proxy in the "HTTP/SOCKS proxy port" field. If you 
	cannot connect to a host without explicitely specifying one, 
	select one based on the naming conventions described in the 
	beginning of this section.
	
     Firewall software Known to work with the distributed.net client.

     Software              Platform    Method       Download from
     --------------------- ----------- ------------ -------------------
     Squid                 Unix        HTTP Proxy   http://squid.nlanr.net
     Internet Gate         OS/2        Port Mapping
     MS Proxy Server       WinNT       HTTP Proxy
     Novell BorderManager  NetWare     HTTP Proxy
     Purveyor HTTP Proxy   VMS/NetWare HTTP Proxy
     Wingate 2.x           Win32       HTTP Proxy   http://www.wingate.com
                                       Port Mapping
     AltaVista 97 proxy    Unix/Win32  HTTP

  5.2  Flushing and fetching via e-mail ----

     If you can not get your client to flush/fetch directly (due to a 
     very stringent firewall), or are running a networkless client, 
     such as the MS-DOS client, there is one last way for your client  
     to fetch and flush: e-mail.

     1. Send a message to fetch@distributed.net; an auto-responder 
        will reply with information on the proper options to use.
     2. Once you know the correct format, send a correctly formatted 
        message in. You should quickly receive a message back with 
        the specified amount of work attached as "buff-in.rc5".
     3. Stop the client. 
     4. Save the file to the directory from which you are running the 
        client. 
     5. Restart the client.

     Once your client has completed the work provided to it, you may 
     send in back via e-mail as follows:

     1. Create a message to flush@distributed.net with the file 
        "buff-out.rc5" attached as a MIME/base64 or UUencoded (UUE) file. 
        You will be send a "receipt" of the proper flushing within a few 
        minutes.
     2. Delete the buff-out.rc5 file so that you do not accidently 
        send part of its contents twice.

  5.3  Flushing and fetching using remote buffers ----
  
     "Remote buffers" are simply buffers that are serviced by another
     client. When fetching/flushing from/to remote buffers, the client
     opens the remote files and moves what it needs from/to its "local"
     buffer files. The difference betwees "remote buffers" and "shared
     buffers" is of course the fact that with "remote buffers" each
     client has its own files. Lock contention is thus minimized and
     they can work without the user having to worry about the network
     (if one exists) between them failing.
                                                                     
 6.0  Help! ----------------------------------------------------------

     If you've having a problem with the client, the first place you 
     should visit is http://www.distributed.net/download/ to 
     see if a newer version is available. It is likely that a given 
     bug you have been experiencing will be fixed by the new version.

     If you are still having problems, here are a few places you can 
     find help (in order of responsiveness).

     - The quickest way to get question(s) answered about the operation 
       and setup of the client is to connect to an EFNet IRC server and 
       join the channel #distributed. Although there are dozens of EFNet
       servers world-wide, the following should give you a starting point:
       In the U.S: irc.cs.cmu.edu:6667, ingenue.eecs.berkeley.edu:6667,
       piglet.cc.utexas.edu:6667. In Europe: irc.homelien.no:6667, 
       irc.df.lth.se:6667, or efnet.demon.co.uk:6667 

     - If you need further assistance with client use or operation, refer 
       to the the list of "Frequently asked Questions" (FAQs) available 
       online at http://www.distributed.net/faq/  Documents cover every 
       aspect of running a client including "The Complete Step by Step 
       Guide to Running Your First Client", "How To Join A Team", and 
       the popular "Statistics Server FAQ".

     - If you don't mind your mailbox receiving a few messages a day, 
       you may consider subscribing to the general client mailing list
       at <rc5@lists.distributed.net> (To subscribe to the mailing list, 
       send a message to <majordomo@lists.distributed.net> with 
       "subscribe rc5" as the message text).

     - More user support is available from <help@distributed.net> 
       as well as from our regional support representatives listed at 
       http://www.distributed.net/regional/index.html
    
     - If you believe you have found a bug in the client or would like 
       to make a suggestion, please use the bug tracking pages at 
       http://www.distributed.net/bugs/  
       DO NOT FORGET TO PROVIDE THE **FULL** VERSION NUMBER OF YOUR CLIENT
       Don't fret if you don't get a response right away - porters are 
       usually very busy and it may take weeks before they get around to 
       answering your message.
       
