
  distributed.net client documentation
  document revision $Id: dnetc.txt,v 1.5 2007/10/22 16:48:28 jlawson Exp $

  Copyright distributed.net 1997-2005 - 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.9xxx
    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-72 message, and
    the search for Optimal Golomb Rulers (OGR). Both are long-term projects
    that will go on for some time.


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

    The system requirements for the client vary from platform to platform
    and are detailed in the platform-specific 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 --------------------------------

    Official clients are generally *only* available from
    http://www.distributed.net/download/ or from FTP servers linked
    from that page.

    Once you have downloaded the client, starting it is easy. 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 at: http://www.distributed.net/docs/tutor_clients.php
    There is also a great deal of useful information at the
    FAQ-O-Matic: http://faq.distributed.net/

    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.9xxx ------------------

     If you are upgrading from a version of the client older than the 
     2.9xxx 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.

     If you use a personal proxy with your client, please make sure
     that you upgrade it at the same time as your client. Clients in
     version 2.9xxx or later will only work with personal proxy builds
     of at least build 330 or later.


 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].v29.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 paragraph).
     
     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://www.squid-cache.org
     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.r72".
     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.r72" 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.r72 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).

     - If you need further assistance with client use or operation, refer 
       to the distributed.net FAQ-O-Matic (Frequently Asked Questions)
       available online at: http://faq.distributed.net/
       Documents there include every aspect of running the client,
       common questions about distributed.net projects, and the ever-
       popular statistics questions.

     - Another way to get question(s) answered about the operation and
       setup of the client is to connect to the distributed.net IRC
       network and join the channel #distributed. To connect, point
       your IRC client at the server irc.distributed.net, port 6667.
       If your IRC client supports SSL, you may also use port 994.
       For more info on using IRC and distributed.net, see the IRC
       Tutorial:  http://www.distributed.net/docs/tutor_irc.php

     - 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/
     
     - If you believe you have found a bug in the client or would like 
       to make a suggestion, please use our Bugzilla bug tracking pages
       located at: http://bugs.distributed.net/
       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.
       

     We thank you for running our client and contributing your idle
     computing power to our projects.  If you are feeling especially
     generous, we also appreciate other types of contributions in
     order to support our equipment and networking costs:
     http://www.distributed.net/donation.php
