Distributed.Net RC5-64/DES Client Readme file version 2.7100
Last modified June 24th by Mike Silbersack (silby@execpc.com)

Copyright distributed.net 1998 - All Rights Reserved
For use in distributed.net projects only.
Any other distribution or use of this program violates copyright.

Use of this client or its variants implies agreement with
the prize terms listed on http://www.distributed.net/rc5/ and
http://www.distributed.net/des/

Index:
------

1.  Introduction
2.  System requirements
3.  Installation of the client
    a.  Windows 95/98/NT CLI installation instructions
    b.  Windows NT Service installation instructions
    c.  OS/2 CLI installation instructions
    d.  Unix installation instructions
    e.  MS-DOS client installation instructions
    f.  Amiga client installation instructions
    g.  RISC OS CLI installation instructions
   (Amiga, Windows, Macintosh, NetWare, OS/2 and RISC OS GUI installation 
   instructions are included with their respective programs.)
4.  Upgrading from a previous version of the client
5.  Configuration of the client via the client config menu
6.  Client commands
7.  Client options
8.  Operation of the client
9.  Format of the log file
10. Platform specific information
    a.  Windows NT Service client
    b.  MS-DOS client
    c.  Amiga client
    d.  RISC OS CLI
11. Frequently asked questions
12. Firewall support / Network protocol description
13. Flushing and fetching buffers via e-mail
14. How to get help
15. Revisions to this document


1.  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, and should take less than a month
to solve. As a result, this client will work on DES during DES contests,
and switch back to RC5-64 when no DES contest is going on. No user
intervention is required for this switchover.

If you'd like more information on our current project status, you should
view the RC5-64 and DES homepages.  RC5-64 may be found at
"http://www.distributed.net/rc5/", and DES may be found at
"http://www.distributed.net/des/". In the next few months, Distributed.net
will begin working on other (non-encryption related) projects. For
information on other projects, please look at
"http://www.distributed.net/projects/".

2.  System Requirements
-----------------------

The system requirements for this client vary from platform to platform;
in general, all that is required is a 32-bit processor with less than 1
megabyte of ram, less than a megabyte of disk space, and a TCP/IP
internet connection or a method of sharing files with another computer
that has internet connectivity.

Note that there may be systems that meet this requirement, but lack a
client.  If you have one of these systems, e-mail
coders@lists.distributed.net to request a client for it.  Please
include processor type an operating system in your request.

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.


3.  Installation of the client
------------------------------

3a.  Windows 95/98/NT CLI installation instructions:

     a.  Unzip the compressed file into the directory in which you
         will be running the client, most likely
         "c:\program files\rc5des\".
     b.  Run rc5des.exe.  This will initiate the menu-driven
         configuration (described below.)  Set the options for your
         configuration.
     c.  Run "rc5des.exe -install" this will set the client so that
         it will automatically start itself when you enter windows.
     d.  Start the client up again; it should now receive some
         blocks, and begin working.

3b.  Windows NT Service installation instructions:

     a.  Unzip the compressed file into the directory from which you
         will be running the client, most likely
         "c:\program files\rc5des\".
     b.  Execute rc5dessrv.exe - this will begin the menu driven
         configuration utility. Set the options for your client as
         described in section 5 of this document. (Note that you
         will not need to configure most of the options unless you
         are behind a firewall or have other special configuration
         needs.) When you are done, type 0 [ENTER] to exit and save
         the settings.
     c.  Run "rc5desrv.exe -install" so that the client will
         install itself as a system service. You must have
         administrator access for this to work properly.
     d.  Go into the windows control panel and into "Services". If
         the client installed properly, you should see the listing
         "Distributed.Net RC5/DES service client". In the startup
         column you should see the listing "Automatic", indicating
         that the client will start on each boot automatically. If
         the current status is blank, click "Start" to begin the
         client's operation.
     e.  If you have logging enabled (which is highly recommended in
         this case, as the service client has no user feedback
         otherwise) you may wish to inspect the log file a few hours
         later to ensure that the client is operating properly.

3c.  OS/2 CLI installation instructions:

     a.  Unzip the compressed file into the directory in which
         you will be running the client, most likely "c:\rc5des\".
     b.  Read the documentation (this file) through so that you
         completely understand how to operate the client.
     c.  Run rc5des.exe.  This will initiate the menu-driven
         configuration (described below.)  Set the options for your
         configuration.
     d.  Run "rc5des.exe -install" this will set the client so that
         it will automatically start itself when you restart OS/2.
         Run "rc5des.exe -install -hide" if you want the client to
         start hidden.
     e.  Start the client up again; it should now receive some
         blocks, and begin working.

3d.  Unix client installation instructions:

     a.  Untar/gzip the compressed file into the directory in which
         you will be running the client.
     b.  Read the documentation (this file) through so that you
         completely understand how to operate the client.
     c.  Run rc5des.  This will initiate the menu-driven
         configuration (described below.)  Set the options for your
         configuration.
     d.  Set the client so that it will auto-start on system boot.
     e.  Start the client up again; it should now receive some
         blocks, and begin working.

3e.  MS-DOS client installation instructions:

     a.  Unzip the compressed file into the directory in which
         you will be running the client, most likely "c:\rc5des\".
     b.  Read the documentation (this file) through so that you
         completely understand how to operate the client.
     c.  Run rc5des.exe.  This will initiate the menu-driven
         configuration (described below.)  Set the options for your
         configuration.
     d.  Start the client up again; it should now receive some
         blocks, and begin working.
     
     Note: The MS-DOS client is not a standalone client; it requires 
     "feeding" of buffer files from a networkable client. Please 
     refer to section 10b for more information on how to use it.

3f.  Amiga client installation instructions:

     a.  Unpack the compressed file into the directory from which you
         will be running the client.
     b.  From a shell, use "rc5des -config". This will initiate the
         menu-driven configuration (described below.) Set the options for
         your client as described in section 5 of this document. (Note
         that you will not need to configure most of the options unless
         you are behind a firewall or have other special configuration
         needs.) When you are done, type 0 [ENTER] to exit and save the
         settings.
     c.  Run rc5des to start up the client; make sure you are connected
         to the internet at this time so it may obtain blocks to work
         on.
     d.  Make sure to add rc5des to your system startup sequence so that
         it will automatically start in the future.

      If you are running a PPC accelerator board in your amiga, you should
      also download and run the PPC version of the client (installing it
      in the same manner as above.) Both a 680x0 and PPC client can be run
      at the same time. Make sure to use seperate checkpoint files for each
      client, as sharing checkpoint files will result in duplicate work.

      Please read section 10c of this document for more Amiga specific
      information.

3g.  RISC OS CLI installation instructions:

     a.  Unpack the archive into the directory from which you will be
         running the client.
     b.  From a task window, run rc5des. This will initiate the menu-
         driven configuration (described below.) Set the options for
         your client as described in section 5 of this document. (Note
         that you will not need to configure most of the options unless
         you are behind a firewall or have other special configuration
         needs.) When you are done, type 0 [ENTER] to exit and save the
         settings.
     c.  Run rc5des to start up the client; make sure you are connected
         to the internet at this time so it may obtain blocks to work
         on.
     d.  Make sure to add rc5des to your boot sequence so that it will
         automatically start in the future.

      Please read section 10d of this document for more RISC OS specific
      information.

4.  Upgrading from a previous version of the client
---------------------------------------------------

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.  Configuration of the client via the client config menu
----------------------------------------------------------

When you first run a CLI client, it will take you to this menu, which
allows you to configure the client in a manner a little simpler than by
.ini file editing.  (If you are .ini inclined, check section #7.)

(Note that some options on the menus are dependant on other options,
and will not show up unless the parent option is enabled.)

Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
------------------------------------------------------------

 1) Required Options
 2) Logging Options
 3) Communication Options
 4) Performance Options
 5) Miscellaneous Options
 6) Filenames & Path Options

 9) Discard settings and exit
 0) Save settings and exit

Choice -->

As the screen suggests, only the options under "Required Options" are
necessary to configure for most users. If you are new to the RC5/DES
client, you may wish to hold off configuring within the other menus
until you are familiar with the client's operation, and have read the
documentation completely.

To select the menu you'd like to edit, enter the number of the menu, and
press the [ENTER] key. To change an option (once inside a menu), type
the number of the option and press the [ENTER] key.  The client will prompt
you for the value of the option you wish to change.  Type in the number of
the option you wish to change, and press [ENTER] again. The default setting
and possible options will be listed on screen. Type in the value you wish to
set for the option, and press [ENTER].  To exit back to the main menu, simply
press 0 and the [ENTER] key.

All of these options are settable through .ini files entries; the name
in brackets is the equivalent option.  wish to configure via .ini file
editing, see section #7.

Here is a breakdown of the different menus, in order:

Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
Required Options
------------------------------------------------------------

 1) Your E-mail address ==> rc5@distributed.net
 2) RC5 Blocks to Buffer ==> 10
 3) DES Blocks to Buffer ==> 10

 0) Return to main menu

Choice -->


1) [id] This is the email address that will show up at the statistics
   site (http://rc5stats.diststributed.net).  It is also the address
   that will be used to find the winner!  Consequently, this needs to
   be your personal address, not a team's.  Please see the questions
   regarding teams in the FAQ section for more information.

2) [threshold X:Y] X is how many RC5 blocks your client will buffer between
   communications with the proxies. The client operates directly on
   blocks stored in the input buffer, and puts finished blocks into the
   output buffer. When the number of blocks in the input buffer reaches 0,
   the client will attempt to connect to the proxies, fill the input buffer
   to the in threshold, and send in all completed blocks. If you have a
   constant internet connection, the default setting of 10 is optimal.
   However, if your computer is only connected to the internet once a day
   (or less), you should probably specify 50 or more blocks so that there
   will be enough blocks for it to process.  In this case, you should
   either enable "lurk mode" (if you are running windows or OS/2), or
   run a "rc5des -update" each time you are connected to the internet.

3) [threshold2 X:Y] This operates the same as #2 above, but applies to DES
   blocks. Note that you should set the DES options even when a DES
   contest is not in progress so that your client is ready to leap into
   action when a DES contest does start.

Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
Logging Options
------------------------------------------------------------

 1) File to log to ==> none
 2) Message Mailing (bytes) ==> 10000
 3) SMTP Server to use ==> your.smtp.server
 4) SMTP Port ==> 25
 5) E-mail address that logs will be mailed from ==> a.computer@your.site
 6) E-mail address to send logs to ==> you@your.site

 0) Return to main menu

Choice -->

1) [logname] This specifies the name of a file the client will log its
   output to.  If a path is not specified, the log file will be created
   in the client's directory.

2) [messagelen] Specifies how often (size of the log wise in bytes) that
   the client should mail out logs.  A setting of 0 means that no logs
   will be mailed.

(Options 2 through 6 will only be shown if option the message mailing
size is set > 0.)

3) [smtpsrvr] If you use log mailing, this sets the address of the SMTP
   server that will be used to mail out the logs.

4) [smtpport] If you use log mailing, this sets the port that the SMTP
   server will be connect to on (usually 25).

5) [smtpfrom] If you use log mailing, this sets the e-mail address that
   the logs will be "from".

6) [smtpdest] If you use log mailing, this is the e-mail address that
   the log files will be sent to.

Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
Communication Options
------------------------------------------------------------

 1) Firewall Communications mode (UUE/HTTP/SOCKS) ==> HTTP encoding
 2) Preferred KeyServer Proxy ==> us80.v27.distributed.net
 3) Preferred KeyServer Port ==> 80
 4) Local HTTP/SOCKS proxy address ==> wwwproxy.corporate.com
 5) Local HTTP/SOCKS proxy port ==> 80
 6) HTTP/SOCKS proxy userid/password ==>
 7) Disable fallback to US Round-Robin? ==> no
 8) Network Timeout (seconds) ==> 60
 9) Offline operation mode ==> Normal Operation
10) Modem detection options ==> Normal mode

 0) Return to main menu

Choice -->

1) [uuehttpmode] This determines the firewall communications 
   mode the client will use to communicate with a proxy server.

2) [keyproxy] This determines which proxy the client will attempt to
   connect to for sending and receiving blocks.

3) [keyport] This determines the port on the keyserver to which the
   client will try to connect.

(options 4->6 will only appear if uuehttpmode is set to HTTP or SOCKS
mode.)

4) [httpproxy] This tells the client the address of the HTTP/SOCKS proxy
   which it should attempt to connect through.

5) [httpport] This determines the port on the proxy server which the
   client will try to connect to.  See the section on httpport for
   more information.

6) [httpid] This is the username/password the client will tell the
   proxy server it attempts to connect through.

7) [nofallback] Normally, if the specified proxy is not working
   properly, the client will automatically fall back to the main US
   proxy round-robin. Enabling this option will make sure the fallback
   never occurs.

8) [nettimeout] This determines the amount of time the client will wait
   before it determines a connection to a keyserver has failed, and abort.

9) [runoffline/runbuffers] This determines how the client will operate
   in relation to its internet connection:

   Normal Operation: The client will connect to a keyserver as needed,
        and use random blocks if a keyserver connection cannot be made.
   Offline Always: The client will never connect to a keyserver, and will
        generate random blocks if the block buffers empty.)
   Finish Buffers and exit: The client will never connect
        to a keyserver, and when the block buffers empty, it will
        terminate.

10) [lurk/lurkonly] On windows & OS/2 computers this determines how the
    client will detect connections to the internet and use them:

    Normal mode: the client will send/receive blocks only when it
        empties the in buffer, hits the flush threshold, or the user
        specifically requests a flush/fetch.
    Dial-up detection mode: This acts like mode 0, with the addition
        that the client will automatically send/receive blocks when a
        dial-up networking connection is established. Modem users
        will probably wish to use this option so that their client
        never runs out of blocks.
    Dial-up detection ONLY mode: Like the previous mode, this will cause
        the client to automatically send/receive blocks when
        connected. HOWEVER, if the client runs out of blocks,
        it will NOT trigger auto-dial, and will instead work
        on random blocks until a connection is detected.


Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
Performance Options
------------------------------------------------------------

 1) Level of niceness to run at ==> Extremely Nice
 2) Optimize performance for CPU type ==> Autodetect
 3) Number of CPUs in this machine ==> -1

 0) Return to main menu

Choice -->

1) [niceness] This allows you to select the priority that the client will
   execute at.  A setting of 0, or 'very nice' will ensure that the client
   will use *only* idle processor time.  A setting of 1, or 'nice'
   allows the client to take priority over a few background processes.
   A setting of 2, or 'normal' allows the client to run at the same
   priority as a normal program.  In almost all cases, you should leave
   this at the default setting of zero so that it does not impact the
   performance of the computer.  In most instances a higher setting will
   not make the client operate any fast anyway.

2) [cputype] (applies to x86, PPC and ARM clients only)  This determines
   for which processor the client will optimize RC5 operations (and DES
   operations on the ARM).  Auto-detect should work for most processors,
   but if your processor is not auto-detected, you will wish to set it
   here.

3) [numcpu] Allows you to specify how many CPUs are in this computer.

(Option 4 will only show on netware/macos/windows 3.1)

4) [timeslice] This should be left alone for optimal performance on
   true pre-emptive multitasking systems.  It should only be changed on
   Mac/Netware/Win 3.1/RISC OS clients where it will change the
   multitasking priority.


Distributed.Net RC5/DES Client build vX.XXXX.XXX config menu
Miscellaneous Options
------------------------------------------------------------

 1) Complete this many blocks, then exit ==> 0
 2) Run for this many hours, then exit ==> 0.00
 3) RC5 block flush threshold ==> 10
 4) DES block flush threshold ==> 10
 5) Preferred Block Size (2^X keys/block) ==> 30
 6) Compete in DES contests? ==> yes
 7) Disable all screen output? (quiet mode) ==> no
 8) Disable exit file checking? ==> no
 9) Disable block percent completion indicators? ==> no
10) Buffer blocks in RAM only? (no disk I/O) ==> no
11) Interval between saving of checkpoints (minutes): ==> 5
12) Exit file check time (seconds) ==> 30

 0) Return to main menu

Choice -->

1) [count] The client will do the specified number of blocks and then
   exit.

2) [hours] The client will work for the specified number of hours and
   then exit.

3) [threshold X:Y] Y, if less than X (aka the size of the input buffer)
   will cause the client to initiate a connection to the keyservers to
   flush and fetch. Setting this value may be useful if you want your
   client to connect BEFORE it needs blocks (as may be necessary if you
   have an unreliable network connection.)

4) [threshold2 X:Y] Same as threshold, but applies to DES blocks.

5) [preferredblocksize] Sets the preferred number of keys per block
   for the client.
 
6) [processdes] When enabled, this will cause the client to participate
   in DES contests. Unless you have an overwhelming reason not to
   participate in DES contests, it is recommended that you leave this
   option enabled.

7) [quietmode] When enabled, this will cause the client to display no
   output.

8) [noexitfilecheck] When enabled, this will cause the client to NOT
   check for "exitrc5.now", which the existance of would normally cause
   the client to exit.

9) [percentprintingoff] When enabled, this will cause the client to
   display no block percentage completion output.

10) [nodisk] This option is quite dangerous, as it causes the client to
    use NO disk I/O for buffers. As a result, much work can be lost when
    the client is stopped, as unfinished blocks will not be written to
    disk.

11) [cktime] This determines the interval (in minutes) between writings
    to the checkpoint file.

12) [exitfilechecktime] This determines the interval (in seconds)
    between checks for the exit and pausefiles (if enabled.)

Distributed.Net RC5/DES Client build v2.7025.410 config menu
Filenames & Path Options
------------------------------------------------------------

 1) RC5 Checkpoint Path/Name ==> none
 2) DES Checkpoint Path/Name ==> none
 3) Pausefile Path/Name ==> none
 4) RC5 In-Buffer Path/Name ==> buff-in.rc5
 5) RC5 Out-Buffer Path/Name ==> buff-out.rc5
 6) DES In-Buffer Path/Name ==> buff-in.des
 7) DES Out-Buffer Path/Name ==> buff-out.des

 0) Return to main menu

Choice -->

1) [checkpointfile] Sets the location of the RC5 checkpoint file.
   This is the place where your client writes its progress to disk in
   case there's a crash or power outage in the middle of a block.
   Don't share this between clients.

2) [checkpointfile2] Sets the location of the DES checkpoint file.

3) [pausefile] Sets the location of the pausefile. If this option is
   set, and the specified file is created, the client will pause until it
   is deleted.

4) [in] This sets the location of the buff-in.rc5 file. You may need to
   change this if sharing buffers between clients.

5) [out] This sets the location of the buff-out.rc5 file. You may need
   to change this if sharing buffers between clients.

6) [in2] This sets the location of the buff-in.des file. You may need to
   change this if sharing buffers between clients.

7) [out2] This sets the location of the buff-out.des file. You may need
   to change this if sharing buffers between clients.


6.  Client commands
-------------------

Commands that can be invoked from the command line only:

-config   Invokes the configuration menu

-test     Tests the client's integrity and ensures it contains no
          errors.

-flush    Flushes the output buffers (buff-out.*) file by returning all
          completed blocks back to the keyserver.

-forceflush   Forces a repeated flushing (no matter what error occurs) until
              all completed blocks have been sent in. This may be useful
              if you have a corrupted bufferfile that contains some good
              blocks, but will not flush with the -flush option.

-fetch    Fills up the input buffer file (buff-in.*) to the limit by
          fetching additional blocks from the keyserver.

-forcefetch   Will continually fetch until the input buffer has been filled
              to the specified limit. You may wish to use this option if
              -fetch frequently fails before getting the requested number
              of blocks.

-update       Combination of flush/fetch

-benchmark    Benchmarks the client's speed on the system.

-benchmark2   Performs a shorter and less accurate benchmark.

-forceunlock <filename>
                Unlocks the buffer file indicated by <filename>

-run          Runs the client in normal mode. Invoking the client with
              no arguments is identical to this option.  If no .ini
              file exists, the client configuration menu will appear.

-install      Under Windows, this causes the client to install
              itself so that it will start on each boot-up.

-uninstall    Under Windows, this causes the client to uninstall
              itself so that it will no longer start on boot-up.

-ini <path/name of .ini file>
              Tells the client an alternate place to look for the .ini
              file. Normally the client uses a file with the name of
              the executable+".ini" in the executable's directory.

              You may also specify the .ini file's location with the
              environment variable $RC5INI.

7.  Client options
------------------

There are two places from which the client can get its configuration
options; from command line parameters and .ini file settings.  The most
reliable way to specify options is by using settings in the .ini.  We
strongly suggest that you use rc5des -config to configure the client, as
it provides the easiest avenue for configuration.  For more advanced
configurations, however, this section may be useful.

----------------------------------
Command line argument: -runoffline
Config file entry: runoffline=<0/1>
Default setting: 0

Runs the client in offline mode.  In this mode, the client will not
automatically fetch or flush. If the input buffer becomes empty, the
client will generate random RC5 blocks to work on.

---------------------------------
Command line argument: -runbuffers
Config file entry: runbuffers=<0/1>
Default setting: 0

Similar to -runoffline except that when the client runs out of blocks
to process, it will exit.

---------------------------------------------
Command line argument: -a <keyserver address>
Config file entry: keyproxy=<keyserver address>
Default setting: us.v27.distributed.net

This allows you to specify the hostname or IP address of a specific
keyserver you wish to use. The default setting automatically rotates
among the keyservers, so you should not normally need to change this
address.  You may need to change this value if you are sending blocks to
a personal proxy, or you're trying to connect through a firewall. If
you're trying to connect through a firewall, you're probably best off
picking a nearby keyserver and doing a nslookup to get the true IP
address of the server in the form x.x.x.x - many proxies won't connect
if you enter the hostname of the proxy.

If you are located outside of the continental united states, you should
check to see if there is an alternate keyproxy round-robin for your
continent.

A list of currently operating proxies and round-robins can be found at
http://www.distributed.net/rc5/proxyinfo.html.

--------------------------------
Command line argument: -p <port>
Config file entry: keyport=<port>
Default setting: 2064

This option tells the client which port of the specified proxy to
connect to. The default port, 2064, should not need to be changed
unless you have set your personal proxy to answer on a different port or
are trying to connect through a http or telnet proxy.

-----------------------------------------
Command line argument: -e <e-mail address>
Config file entry: id=<e-mail address>
Default setting: <your e-mail address!>

This is the place where you set your e-mail address.  Please note that
you should specify *your* e-mail address at all times, not one of a team
or a friend.  The reason for this policy is that if you win, and are not
using your own address, we'll have an extremely difficult time finding
you, and your friend/team captain will end up with the prize.  There are
only two cases where more than one computer should be using the same
e-mail address:

1)  They're all your computers.
2)  The computers are all in a large cluster, such as a computer lab.
    In this case, the e-mail address of the administrator of these
    computers should be used.

See the FAQ of this document for an explanation of teams.

---------------------------------
Command line argument: -c <cpuID>
Config file entry: cputype=<cpuID>
Default setting: -1

If you are using a x86, PPC or ARM client, this will allow you to set
which optimized cores you wish to use.  All x86 cores will work on
all 386+ processors, all PPC cores will work on all PPC processors, and
all ARM cores will work on all ARM processors. The autoselected core will
usually be the fastest, so unless there is a misdetection (as may occur
with Cyrix processors), you need not manually set a core.

For x86 and PPC, cputype changes the RC5 core only. On the ARM, cputype
selects a permutation of the two RC5 and two DES cores.

x86 CPU types:
     -1  : Auto detect
      0  : Intel Pentium, Intel Pentium MMX, Cyrix
      1  : Intel 80386 (386), Intel 80486 (486)
      2  : Intel Pentium Pro, Intel Pentium II
      3  : AMD 486, Cyrix 6x86/6x86MMX/M2
      4  : AMD K5
      5  : AMD K6

PPC CPU types:
     -1  : Auto detect
      0  : PPC 601
      1  : PPC 603/603e/604/604e/750

ARM CPU types:
     -1  : Auto detect
      0  : ARM 3/600/610/700/7500/7500FE       [RC5 core 0, DES core 0]
      1  : ARM 810/StrongARM 110               [RC5 core 1, DES core 1]
      2  : ARM 2/250                           [RC5 core 0, DES core 1]
      3  : ARM 710                             [RC5 core 1, DES core 0]

--------------------------------------------
Command line argument: -l <path/logfilename>
Config file entry: /logname=<path/logfilename>
Default setting: None

This is the name of the file to which the client will log its activity.
Make sure to specify the full path, as otherwise the log file will end up
in the current directory.  If the entry is left blank, no log will be
recorded.

----------------------------------------------------------
Command line argument: -b <number of RC5 blocks to buffer>
Config file entry: threshold=X:Y
Default setting: 10:10

Specifies the number of RC5 blocks to buffer.  Using -b sets both X
and Y to the same value.  -bin sets the X parameter, and
-bout sets the Y parameter.

The X parameter is the maximum size of the in buffer. The client will
refuse to fetch any more blocks into the in buffer than is specified by
X. If you lower the in-buffer size, it will just process blocks until
it gets down to that high water mark, and proceed normally from there.
The client has a built in limit of 1000 blocks as a maximum in-buffer
size.  Note that having a in buffer larger than X is not a problem; the
client will simply not receive any new blocks until the buffer is
depleted to below the value of X.

The Y parameter sets the send threshold. Whenever the size of the out-
buffer reaches Y, it will automatically initiate a flush/fetch,
regardless of the status of the in buffer.  Note that there is no limit
to the amount of blocks that will fit in an out buffer; this parameter
just determines when flushes of the out buffer will be attempted.

--------------------------------------------------------------------
Command line argument: -bin <number of RC5 blocks for the in buffer>
Config file entry: None

This parameter sets the X argument of the threshold .ini option above on
the fly for RC5 blocks.

----------------------------------------------------------------
Command line argument: -bout <size of buff-out.rc5 before flush>
Config file entry: None

This parameter sets the Y argument of the threshold .ini option above on
the fly for RC5 blocks.

-----------------------------------------------------------
Command line argument: -b2 <number of DES blocks to buffer>
Config file entry: threshold2=X:Y
Default setting: 10:10

This operates exactly the same way as the -b / threshold .ini option
described above, only on the DES buffer files instead.

---------------------------------------------------------------------
Command line argument: -bin2 <number of RC5 blocks for the in buffer>
Config file entry: None

The DES equivalent of -bin.

-----------------------------------------------------------------
Command line argument: -bout2 <size of buff-out.rc5 before flush>
Config file entry: None

The DES equivalent of -bout.

---------------------------------------------
Command line argument: -h <# of hours to run>
Config file entry: hours=<# of hours to run>
Default setting: 0

This tells the client to terminate after running for the specified period
of hours.  The default value will cause the client to run infinitely.

--------------------------------------------------
Command line argument: -n <# of blocks to process>
Config file entry: count=<# of blocks to process>
Default setting: 0

This tells the client to terminate after processing the specified number
of blocks.  The default setting eliminates causes client to process an
infinite amount of blocks.

--------------------------------------------------
Command line argument: -until <HHMM time to quit at>
Config file entry:
Default setting: <none>

This setting will tell the client to start execution, and run until
the time specified has been reached, at which point it will terminate.
This may be useful if you wish to run the client during known low usage
periods on a system; simply start it with a CRON job, and tell it to
run until a specific period of time.

--------------------------------------------------
Command line argument: -nice <client nice setting>
Config file entry: niceness=<client nice setting>
Default setting: 0

This sets the client priority level, based off the following chart:
   0  : Very nice. DOES NOT intefere with system operations at all.
        Runs on idle CPU time only.
   1  : Runs with slightly higher priority than idle processes.
   2  : Runs as a normal process with higher priority.

Note that these numbers don't correspond to unix nice settings; the client
internally converts 0 to the nicest setting possible for a platform, 1 to
slightly higher than idle, and 2 to normal user-level process.  Don't
bother trying to re-nice the clients, level 0 nices the client as much
as possible.

-----------------------------------------
Command line argument: -u <UUE/HTTP mode>
Config file entry: uuehttpmode=<UUE/HTTP mode>
Default setting: 0

This option determines the firewall communications mode the client will
use. The types of modes are:

   0  : Direct communications mode, no firewall support
   1  : UUE encoding (for telnet proxies)
   2  : HTTP encoding 
   3  : HTTP+UUE encoding
   4  : SOCKS4 proxy
   5  : SOCKS5 proxy

The operation of these modes is influenced greatly by the other related
options.

-----------------------------------------------
Command line argument: -ha <HTTP Proxy address>
Config file entry: httpproxy=<HTTP Proxy address>
Default setting:

Specifies the IP address or hostname of the HTTP proxy.

--------------------------------------------
Command line argument: -hp <HTTP proxy port>
Config file entry: httpport=<HTTP proxy port>
Default setting:

Specifies the port of the HTTP proxy to which the client should connect.

---------------------------------------------------------
Command line argument: -in <location/name of RC5 in buffer>
Config file entry: in=<location/name of RC5 in buffer>
Default setting: buff-in.rc5

Allows you to override the default name buff-in.rc5 and specify a
different path/file name for the RC5 in buffer.

-----------------------------------------------------------
Command line argument: -out <location/name of RC5 out buffer>
Config file entry: out=<location/name of RC5 out buffer>
Default setting: buff-out.rc5

Allows you to override the default name buff-out.rc5 and specify a
different path/file name for the RC5 out buffer.

----------------------------------------------------------
Command line argument: -in2 <location/name of DES in buffer>
Config file entry: in2=<location/name of DES in buffer>
Default setting: buff-in.des

Allows you to override the default name buff-in.des and specify a
different path/file name for the DES in buffer.

--------------------------------------------------------------
Command line argument: -out2 <location/name of DES out buffer>
Config file entry: out2=<location/name of DES out buffer>
Default setting: buff-out.des

Allows you to override the default name buff-out.des and specify a
different path/file name for the DES out buffer.


---------------------------------------------------
Command line argument: -smtpsrvr <SMTP server name>
Config file entry: smtpsrvr=<SMTP server name>
Default setting: None

This specifies the address of the SMTP server through which your client
will e-mail log files (if log file mailing is enabled.)

--------------------------------------------------------------
Command line argument: -smtplen <mail message length in bytes>
Config file entry: messagelen=<mail message length in bytes>
Default setting: 0

This determines the size of the parts of the log file that will be e-
mailed. As a result, it also determines send interval.  0 indicates
that log mailing is disabled.

---------------------------------------
Command line argument: -smtpport <port>
Config file entry: smtpport=<port>
Default setting: 25

This tells the client the port of the SMTP server to use for message
mailing. The default SMTP port used is 25; you should not need to
change this.

---------------------------------------------
Command line argument: -smtpfrom <Identifier>
Config file entry: smtpfrom=<Indentifier>
Default setting: None

This just tells the client what to put in the From: field of any log
files it mails to you. You can use this to make different systems send
with different names so that you can auto-sort them in your mail
program.

-------------------------------------------------
Command line argument: -smtpdest <e-mail address>
Config file entry: smtpdest=<e-mail address>
Default setting: None

This specifies the e-mail address to which the client will send log
files if log file mailing is enabled.

-----------------------------------------------------------------
Command line argument: -ckpoint <checkpoint file path / filename>
Config file entry: checkpointfile=<checkpoint file path / filename>
Default setting: None

This specifies the name of the file the client will use to store
checkpoints of its work during a RC5 block. This is an extremely useful
option: if you have a system which experiences frequent crashes or
terminates the client abruptly, you will want to enable this option
so that you loose only a few minutes' work, rather than an entire block.
Please note that checkpoint files MUST be unique for EACH RUNNING
CLIENT. Sharing checkpoint files will cause major problems.

------------------------------------------------------------------
Command line argument: -ckpoint2 <checkpoint file path / filename>
Config file entry: checkpointfile2=<checkpoint file path / filename>
Default setting: None

Has the same effect as -ckpoint, except that it affects DES blocks
being processed.

--------------------------------------
Command line argument: -cktime [# min]
Config file entry: cktime=#
Default setting:

Time in minutes between the client would saving current work to the
checkpoint file.

--------------------------------
Command line argument: -frequent
Config file entry: connectoften=1
Default setting: 0

This will cause the client to flush/fetch every few minutes or so. You
might want to use this if you have a single computer with a network
connecting "feeding" other clients via a buff-in.* file so that the
buffer never reaches empty. If you're behind a firewall and experience
frequent connection failures, this may be useful as well.

----------------------------------
Command line argument: -nofallback
Config file entry: nofallback=1
Default setting: 0

If this is set, the client will not attempt to fall back to the main
RC5/DES proxy round-robin address after a connection failure.

----------------------------
Command line argument: -lurk
Config file entry: lurk=<0/1>
Default setting: 0

If you're using Windows, this will cause the client to automatically do
a -update whenever you're connected. If you're on a dial-up connection,
you'll probably want to use this option, as it will allow you to not
have to worry about updating (as long as you connect to the internet on
a regular basis.)  Note that if you're offline and run out of blocks,
lurk will still try to do an update.

--------------------------------
Command line argument: -lurkonly
Config file entry: lurkonly=<0/1>
Default setting: 0

Works like lurk, except that lurkonly will *never* try to -update unless
you're already online.

---------------------------------------
Command line argument: -noexitfilecheck
Config file entry: noexitfilecheck=1
Default setting: 0

If the client sees the existence of the exit file, exitrc5.now, it will
shut down. If set to 1, this will cause the client NOT to check for
exitrc5.now.

-----------------------------------------
Command line argument: -exitfilechecktime <number of seconds>
Config file entry: exitfilechecktime=<number of seconds>
Default setting: 30

Determines how often the client checks for the existence of the
exitfile. If your computer does not cache properly and you are
experiencing a lot of disk activity, you may wish to set this value
higher.

------------------------------
Command line argument: -nodisk
Config file entry: nodiskbuffers=1
Default setting: 0

If enabled, this will cause the client NOT to buffer to disk. Unless
you have an extreme circumstance that requires the client not to
access a disk anywhere, this option is highly discouraged. If it is
enabled, you tend to loose hours worth of work if the computer crashes
or restarts.

-----------------------------
Command line argument: -quiet
Config file entry: quietmode=<0/1>
Default setting: 0

When set, this option will cause the client to run with no output to
the screen.

-------------------------------------------
Command line argument: -blsize <block size>
Config file entry: preferredblocksize=<block size>
Default setting: 30

This determines the size of blocks (of 2^<block size> keys) that the
client will request. You can choose block sizes from 28 -> 31 bits in
size. We suggest that you use larger blocks (30 or 31), as it helps to
keep network activity down and keep our system running smoothly. Note
that the client may receive blocks smaller than the requested size on
occasion.

------------------------------
Command line argument: -prefer
Config file entry: preferredcontest=
Default setting: 2

Sets the contest that the client will work on when possible. 1 is the
setting for RC5-64, 2 is the setting for DES.  Since the DES contests
are timed and we need all processor power to get them done, it's
suggested that you keep this set to two, even when no DES contest is
going on so that when a DES contest starts, the client will auto-switch
to DES.

----------------------------------
Command line argument: -nettimeout <timeout in seconds>
Config file entry: nettimeout=<timeout in seconds>
Default setting: 60

This sets the length in seconds before attempts to connect to keyservers
will time out.  You may need to increase this setting if your connection
is slow or unreliable.

--------------------------------------------------
Command line argument: -pausefile <pausefile name>
Config file entry: pausefile=<pausefile name>
Default setting: None

If the client detects the existence of this file, it will temporarily
stop working until the pausefile disappears.

----------------------------------------------------------
Command line argument: -numcpu <number of cpus to utilize>
Config file entry: numcpu=<number of cpus to utilize>
Default setting: -1

This tells the client how many CPUs on the computer to use for
decryption. -1 indicates that the client will try to auto-detect.

----------------------------------
Command line argument: -percentoff
Config file entry: percentprintingoff=<0/1>
Default setting: 0

If this command line option is specified, or the config file option is
set to 1, the percent indicator will not be shown on screen during the
progress of a block.

---------------------------
Command line argument: none
Config file entry: randomprefix=<some number>
Default setting: Whatever it's at - leave it alone.
This setting is used / set by the client to specify where in the RC5
keyspace random blocks should be created from.  Please do not change it.

8.  Operation of the client
---------------------------

The RC5/DES client is quite simple in overall operation, and should not
be hard to adapt to any configuration. The basic operation for a
multi-threaded client is as follows:

1.  The client attempts to load two blocks from the buff-in.* file, and
    begins working on decrypting the first block.
2.  The client (in a seperate thread) checks if the buff-in.* file is
    empty, or the buff-out.* file has reached its thresholds as set in the
    configuration. If this has occured, a network update will be
    attempted, which will send all completed blocks in the buff-out.*
    files to the server, and fill the buff-in.* file up fresh blocks.
    If an error occurs in the network communications, the computer will
    attempt to connect a few more times, and then not try until the
    completion of the next block.
3.  When the client has finished with a block from the buff-in.*, it
    will write it to the buff-out.* file, at which point the above
    empty/full check will occur again.
4.  The client will loop back to step one. This process will go on
    until the completion of the RC5-64 contest.

Note that this is only a basic description of a multi-threaded client's
operation, of course. Non-multithreaded clients must do these steps
sequentially. There are a few primary ways to change overall operation:
If you use the runoffline option, the client will never try to connect
to the servers, and start creating random blocks to decrypt if the
buff-in.* files become empty.  By specifying runbuffers, you would cause
the client to exit when the buffers empty.

9.  Format of the log file
--------------------------

The RC5/DES client log file may seem very confusing at first sight; the
important thing to remember is that the client (on most platforms) is
multithreaded, so the order of entries in the log sometimes doesn't make
much sense; this is normal, as the network code may retrieve and send in
some blocks while another block is being worked on. The buff-in.* file is
a stack.  As a result, you may notice that if the client is stopped and
new blocks are put into the buffer, blocks will *appear* to diappear.
Don't worry; the block that was saved during client shutdown was put back
on top of the stack, and then covered over by the newer blocks.  The
partially completed block will surface again.

Here are the basic entries you will see in the log file:

[dd/mm/yy hh:mm:ss GMT] Shutdown message received - Block being saved.

This message tells you that the client has begun its shutdown, either
due to system shutdown, client termination, or the creation of the
exitrc5.now file.

[dd/mm/yy hh:mm:ss GMT] Saved block xxxxxxxx:yyyyyyyy (xx.xx percent complete)

Immediately after the client begins shutdown, you will see this line
twice per each processor in the system.  There are two lines because each
thread of the client keeps two blocks in memory at all times in case of
network errors.

[dd/mm/yy hh:mm:ss GMT] RC5 1*2^bb Block: xxxxxxxx:xxxxxxxx ready to process
[dd/mm/yy hh:mm:ss GMT] xxx Blocks remain in file <path/name of in buffer>
[dd/mm/yy hh:mm:ss GMT] xxx Blocks are in file <path/name of in buffer>

Each time a block is completed by the client (or at startup), the client
needs to load

Child thread # x has been started.

During startup, you should see this message once per processor.

[dd/mm/yy hh:mm:ss GMT] Completed block xxxxxxxx:xxxxxxxx (xxxxxxxxxx keys)
                        hh:mm:ss.ms - [xxxxxx.xx keys/sec]

This message is printed to indicate the completion of each block. Note
that the time and keys/sec rate given here are for the duration of that
block only.

[dd/mm/yy hh:mm:ss GMT] The proxy says: "<insert some message>"

Each time the client connects to send or receive blocks, you'll see a
message from the proxy. Generally, this is just whatever the proxy
operator decided to set as a message. So, if it doesn't make sense,
just ignore it.

>

You'll see a '>' for each block that the client successfully sent to the
server during the connection.

<

You'll see a '<' for each block that the client successfully receives
from the server during the connection.

[dd/mm/yy hh:mm:ss GMT] Sent x <type> block(s) to server

If the client just received some blocks from the server, it'll tell you
how many and what kind.

[dd/mm/yy hh:mm:ss GMT] Retrieved x block(s) from server

If the client just sent some blocks to the server, it'll tell you how
many.

[dd/mm/yy hh:mm:ss GMT] Tot: x RC5 blocks hh:mm:ss.ms - [xxxxxx.xx keys/sec]
                        Tot: x DES blocks hh:mm:ss.ms - [xxxxxx.xx keys/sec]

These averages are printed after the completion of each block.  Be careful
how you read them.  The averages

10. Platform specific information
---------------------------------
    10a.  Windows NT Service client

          For those running windows NT, especially on multiuser systems,
          the NT service client is the best choice of a client to run.
          The service client can run without requiring a user to be
          logged in, and can not be stopped by a non administrator.
          Users of NT workstation who are always logged in may still
          consider using the GUI client, as the service has no user
          interface.

    10b.  MS-DOS client

          The MS-DOS client operates in the same manner as the other
          non-GUI clients, with three major differences:

          1. Due to the fact that MS-DOS is not a multitasking operating
             system, this client has no way to run in the background 
             unless it has been set up to run under the control of an
             external multitasker such as Desqview, or Windows.
          2. Due to a lack of standards for TCP/IP stacks (and a lack
             of time), there is no TCP/IP support in the MS-DOS client.
             To use this client, you must use a file sharing method to
             feed it buffer files (NFS, NetWare, SMB, etc are all
             acceptable). You may also transfer buffers to an offline
             MS-DOS machine via a floppy disk if you so desire.
          3. For reasons of efficiency, the DOS client runs entirely
             in protected mode, but requires the assistance of a
             'DOS extender' to do so. One such 'extender' is dos4gw.exe
             (so called because it makes upto 4 gigabytes of memory 
             available to the client) and is distributed together with 
             the client. 
             
    10c.  Amiga client

          Please refer to 'readme.amiga' for detailed notes.

          The original amiga port was made by `caw', and rewritten for
          RC5-64 and DES by Stefan Smietanowski (aka Blast).

          For help with the Amiga client, you can either ask through
          "standard" support channels (listed below), or visit the Amiga
          RC5 team homepage (http://homepage.cistron.nl/~ttavoly/rc5/) for
          more Amiga-specific information. (Or e-mail rc5@amiga.cistron.nl)

          If you have problems with the AMIGA port you believe to be AMIGA
          specific, mail blast@amiganet.org, or look for him as `Blast' or
          `Blast2' on ANet #Amiga. (irc.amiganet.org or any other ANet
          server will work.)

    10d.  RISC OS CLI

          The RISC OS CLI client requires:

          -RISC OS 3.10 or later
          -The Acorn Internet module, or a compatible stack (eg FreeNet)

          The RISC OS port was created by ant.org (team 553).

          If you run the RISC OS client in a task window, you can reduce
          the amount of processor time used by decreasing the keys per
          timeslice setting.

          The RISC OS CLI client can be run in a task window at boot time
          by adding the command

            TaskWindow "Run {path to client}.rc5des" -wimpslot 352K
                  -name "RC5DES client"

          to your desktop boot file. Changing the quoted command to
          "Run {path to client}.rc5des { > null: }" will make the client
          invisible. Stop it by killing it via the task manager or by
          creating a file "exitrc5/now" in the client's directory.
          Alternatively, you will probably be better off installing the
          RISC OS GUI client.

          For help with the RISC OS client, you can either ask through
          "standard" support channels (listed below), or visit the ant.org
          RC5 team homepage (http://www.ant.org/rc5/) for more RISC OS-
          specific information. (Or e-mail rc5@ant.org)

          If you have problems with the RISC OS port you believe to be
          RISC OS specific, mail kbracey@acorn.co.uk.


11.  Frequently asked questions
------------------------------

Q:  What is a team?

    A team is an entity on our stats server that allows a group of
people to work together in order to show their combined keyrate. Note
that creating a team doesn't necessarily mean you'll hit the top 100
listings, because teams are ranked separately from individuals.

Q:  Do I need to join a team?

    No, you do not need to join a team.  Teams exist so that you can show
group strength, help advocate a platform, etc. You can see a listing of
teams based sorted by their type at
http://stats.distributed.net/teamlist.html

Q:  Are there any disadvantages to joining a team?

    The only disadvantage to joining a team is that part of the prize money
that would normally go to you will be split with your team.

Q:  How do I join a team?

    To join a team, go to http://stats.distributed.net/ and search
for your "personal page". To do this, scroll down to the entry "search
for team" and enter your e-mail address, then click "go". You should be
gived a screen that shows your current rank, e-mail address, total
blocks, time working, date of last block, and averate keyrate. Click on
your e-mail address, and you will be taken to your personal page.

From your personal page, scroll to the bottom where it says 'Mail me a
password' and click. Then, wait for your password to arrive. If it
hasn't arrived in your e-mail in 15 minutes or so, go back to your
personal page and click 'Whoops! I can't seem to find my password.
Can you send it to me again?'.

Once your password arrives, enter your password on your personal page,
and click "Edit participant information". Once inside, you'll see a
screen with your e-mail address, team affiliation, Charity selection,
and a button that says "update participant information." Here enter the
team id of the team you wish to join (the team id of the team is on the
page of the team you decided to join.) You may also wish to vote on
where the charity part of the prize money will go to at this time as
well. When you're done, click "update participant information."

Q:  I can't find my personal stats page!

A:  It will take an average of 24 hours since the time you sent your
first block in for your name to appear on the stats page; the database
is updated only daily.

Q:  What does "stats are offline for the daily update" mean?

A:  To keep calculations simpler and cause less load on the stats server,
the stats server is only updated once a day at approximately 0:00 GMT.
During this time, only the top 100 listings from the previous day are
available. The update (at this time) usually takes 2.5 hours or so.

Q:  How can I create a team?

A:  Go to http://stats.distributed.net/tm_new.html

Q:  I have to switch e-mail accounts / I typed in the wrong e-mail address.
Can you move my blocks to my new e-mail?

A:  No. We have no provisions for moving blocks from one e-mail to another.
However, if you e-mail rc5help@distributed.net you can request the password
for the incorrect/dead e-mail address so that you can join it to your
team.

Q:  I'm behind a firewall, can I send and recieve blocks?

A:  Please read section 12 of this document, which describes life with
firewalls.

Q:  My <insert computer name> doesn't have an internet connection, how
can I get it blocks to work on?

There are three ways you can get blocks to a computer that does not have
a direct internet connection:

#1 - If you have a single computer that has a constant connection to the
internet, and a TCP/IP network between the other computers, you can set up
a personal proxy on the computer with the connection, and direct the other
computers to connect to that computer (see the section on "network
settings" for more explanation on how to do this.)

#2 - If you have a method of file sharing (Novell Netware, NT server,
NFS, etc), you can share the same set of buff*.* files between clients.
Simply run all the clients from the same directory, making sure to set
the ones without the direct connection to -runoffline so that they will
not attempt to make a network connection. Then, use just one client to
fetch/flush buffers at your convenience (or automatically).

#3 - If worst comes to worst, and you can't automate the transfer between
computers in any manner, you can always manually copy buffer files between
computers. To do this, simply set up a second copy of the client on the
computer with the internet connection. Then, MOVE the buff*.* files to that
computer (via FTP, e-mail, or a floppy disk), perform a flush/fetch, then
MOVE them back to the offline computer. This procedure can get somewhat
messy if not done properly, but is effective for a small number of
computers.  If you're working this way, you'll probably want to use large
buffers so that you need to flush only once a week or so.

Q:  The display is bugging me, how can I hide the display of the client?

A:  This is a simple process on unix machines; instead of using the
command "./rc5des", use the command "./rc5des >/dev/null &". This
should start the client running in the background with all output
redirected to /dev/null. If you need to kill it, do a kill -HUP <pid>,
or create the exitrc5.now file in the directory, as described below.

On Windows 95, you're best off installing the GUI version of the client,
which has the option "Run hidden and without system tray icon". Under
Windows NT, you can(/should) run the NT service client, which will be
hidden all of the time (and start running before login).

In all cases, enabling logging will still let you go back and see what
the client has done.

Q:  I see this R in the middle of my percentage bar - what does it mean?

A:  A 'R' in the middle of a percentage bar stands for 'resume'. This
is the point at which the client was working on last time it was
shutdown; it just resumed and jumped to that point in the block. Note
that as a result of not having to process the entire block, resumed
blocks will be processed faster than normal blocks; the time difference
this makes obviously depends on where in the block it resumed.

Q:  I just saw the message:  "Read partial DES block from another
cpu/os/build.  Marking entire block as unchecked."  What does this mean,
and how can I fix it?

A:  This message means that the client just loaded in a partially
completed block that had been started with a different version of the
client.  This normally occurs if you upgrade the client revision or are
sharing buffer files with a dissimilar computer.  Note that this is not
a problem; all that is happening is that the client is reprocessing that
entire block.  This is a precaution in the circumstance that an
incompatibility between partial buffer formats occurs.  If this is an
upgrade, you probably won't see that message again.  If you're sharing
buffer files, you can minimize the occurance by never shutting down the
clients.

Q:  But it just did two blocks with 'R'! How is that possible?

A:  Partially completed blocks can be 'buried' in the buff-in.* files; if
you routinely shut the client down and then fetch new blocks, new, full
blocks will be added to the buff-in.*.  The partially completed blocks
will not resurface for a while, perhaps a couple of days.

Q:  How can I stop hidden clients / I need to upgrade an entire network of
    clients, how can I stop them all?

A:  The easiest, most reliable way to stop all clients is to create
a file named 'exitrc5.now' in the directory where the client is running
from. Upon seeing this file, the client will perform a proper shutdown
and exist. The client checks for the existance of this file every few
seconds, so the shutdown should be almost instant.  (Note that this will
not work if noexitfilecheck=1 is set in the .ini file.)

Q:  Why is my client downloading both RC5 and DES blocks?

A:  Even during a DES contest, the dual-mode client will attempt to keep
the RC5 and DES in buffers full; this is not a problem. The client
won't revert to RC5 blocks until it has completed all DES blocks, so
you won't loose a bit of DES keyrate. If a DES is not currently in
progress, and you would like the client to stop getting DES blocks, set
the DES in and out buffer to 0.

Q:  Will this slowdown my computer at all? I raytrace/play
quake/compile large programs, and I can't afford any slowdown.

A:  If you leave the client at its default niceness setting (0), it will
run at the lowest priority level on your system so that it does not
interfere with the running of any program. The only exceptions to this
rule are the Windows 3.1, Macintosh and RISC OS clients, which are
hindered by non-preemptively multitasking operating systems. On these
systems, you can reduce the processor time consumed by reducing the keys
per timeslice setting.

Q:  I've been watching my keyrate, and it seems that it gets SLOWER
during the times I'm not at my computer! Shouldn't the processor be
busier while I'm working?

A:  If you're seeing slowdown during the night / lunch / whenever you're
away from the computer, it's probably due to one of two things. The
most likely cause is that another program is hogging processor time. Some
web browsers are known to eat processor time, especially while on pages
with animated images. However, the programs that eat the most processor
time are screensavers. OpenGL and 3-D screensavers in particular are known
to consume a LOT of processor time. For this reason, we recommend that you
either disable your screen saver, or switch to a less CPU intensive one
(a blank screen one, or one that shows a simple text message, perhaps.)
The other cause of a slowdown could be your computer entering a 'sleep
mode' where it powers most components down. To disable automatic power
down, consult your system's documentation.

Q:  I set my client to receive 2^30 sized blocks.  However, I have been
watching, and it has done many differently sized blocks smaller than
2^30. What is going on?

A:  The block size is really only a "request" by the client. Depending
on the fragmentation of the current keyspace we are working on, the
keyproxy may be forced to give you a block smaller than requested. This
is not a problem, just an oddity.

Q:  I just got all blocks smaller than expected, and I ran out of blocks
too soon as a result! How am I supposed to calculate how many blocks to
get if they aren't always the same size?

A:  This is a known problem; for now, simply buffer more blocks than you
plan on needing. We will probably add a more exact count to future clients.
There is no ETA at this time.

Q:  What happens if my client finds the key?  Does it let me know or
do anything special?

A:  No, the client treats a success just like a normal block and flushes
it during the next network transaction.

12. Firewall support / Network protocol description
---------------------------------------------------

For network communications, the Distributed.Net RC5/DES client uses a
proprietary communications method which talks to our network of proxy
servers via TCP packets on port 2064. If you are connected through a
strict firewall, port 2064 will probably be blocked by default. There
are five primary methods to comminucating through a firewall:

1.  Run a personal proxy on the machine that runs the firewall.  A
personal proxy will receive connections from the client, buffer them,
and then communicate with the main proxy network to send/receive
blocks. The setup of this is simple and reliable; all you must do is
download a personal proxy (http://www.distributed.net/rc5/proxies.html),
set it up to run on the machine that functions as the firewall, and set
all the clients to connect to that machine to receive blocks (via
keyproxy=<IP/DNS of the computer with the personal
proxy.)  The major downside to this option is that you must be
authorized to run an outside program on the firewall computer.

2.  The next most reliable option is to set the firewall to allow
connections through port 2064 (the port the client uses for
communication to the keyservers.)  If this is done correctly, you will
be able to set the client with keyproxy=<IP/DNS of the
firewall> and have the proxy redirect communications to one of the main
proxies.  The problem with this configuration is that it requires that
you have access to the configuration of the firewall.  This method will
be referred to as "direct port mapping" throughout the rest of the
documentation.

3.  The most reliable option for sending/receiving blocks through the
firewall if you are unable to directly modify the firewall's
configuration is to use SOCKS support (if your firewall supports it, of
course.)  To configure SOCKS, enter the Communications Options menu
and select option 1 (Firewall Communications mode). If you are using
a SOCKS4 proxy, choose option 4, or choose option 5 if you are using a
SOCKS5 proxy. If you are unsure as to which version of SOCKS you are
using, select SOCKS4. Now, edit options 4 and 5 (Proxy address and
port, respectively), ensuring that they point to the SOCKS proxy you
will be communicating through. If you must use a SOCKS userid/password,
enter it in option 6. In some situations, option 2 (the address of the
keyproxy to use) may need to be changed to the specific IP address of a
proxy. However, SOCKS support *should* work "out of the box" on most 
proxies.

4.  The most compatible firewall communications option is to use the
http proxy support of the client. To setup http proxy support, enter
the client's configuration utility (rc5des -config) and enter the
Communications Options menu. Select option 1 (Firewall Communications
mode) and select mode 2 (HTTP encoding). Next, select option 4, and input
the address of the HTTP proxy you will be connecting through. Finally,
select option 2, enter "us80.v27.distributed.net", and select option 3
and enter "80". Also, if you must use a username/password to connect
through your http proxy, make sure to set option 6 (HTTP/SOCKS
userid/password).

*This should work, but it may not.*

If the HTTP proxy support does not work at this point, there are a few
more options to fiddle with. One of the first things to try is to edit
option two again, and enter the IP address of one of the us80 proxies
directly (obtainable by nslookup us80.v27.distributed.net). If this does
not fix the problem, try changing option 1 (Firewall Communications
mode) to 3 (HTTP+UUE encoding).

In all cases, whether it works or not, please e-mail silby@execpc.com so
the list of known working/non-working proxies can be kept up to date.

5.  If you can not get any of the above methods working, please see section
13 on the use of e-mail to flush/fetch buffers.

Known working firewalls/proxies:
(If you know of other working proxies/modes, please e-mail silby@execpc.com)

Name: Wingate 2.x
Connection method: HTTP proxy, Direct port mapping

Name: Internet Gate v1.30 for OS/2.
Connection method: Direct port mapping

Name: Microsoft Proxy Server 2.0
Connection method: HTTP proxy
Notes: userid + password are the normal NT domain login and password

Name: Novell BorderManager web proxy
Connection method: HTTP proxy



13.  Flushing and fetching buffers 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 you two receive blocks to
process: e-mail.

To receive blocks via e-mail:

1. Create a message to fetch@distributed.net with the following two lines
in the body:

blocksize=<number between 28 and 31>
numblocks=<number less than 1000>

(For explanations of the two options, please see the section of this
document on .ini file options.)

Within a few hours, you should receive a message back with the specified
number/size of blocks attached as "buff-in.rc5".

2. Extract this file from your mail program to the directory from which
you are running the RC5/DES client.

3. Start the client running.

Once your client has completed the blocks provided to it, you may send
in the completed blocks via e-mail in the following way:

1. Create a message to flush@distributed.net with the file "buff-out.rc5"
attached as either a uuencoded or MIME64 encoded file. You will be send a
"receipt" of the proper flushing of the blocks a few hours later.

2. Delete the buff-out.rc5 file so that you do not accidently send part
of its contents twice.

14.  How to get help
--------------------

If you've having a problem with the client, the first place you should
visit is http://www.distributed.net/des/clients.html 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, there are a few places you can find
help:

The quickest, though least reliable, 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 no
'official' support people there, the channel is often populated with
people who are familiar with the operation of distributed.net programs
and can offer quick answers.

More in depth questions, comments, or suggestions can be directed to
rc5help@distributed.net. Messages sent to this address will be reviewed
daily, and you should receive a quick answer to your question.

If you don't mind your mailbox receiving a few messages a day, you may
consider subscribing to the general RC5 mailing list; if you wish to do
so, send a message to majordomo@lists.distributed.net with the body
"subscribe rc5". Note that this is a moderated mailing list, so there
may be some lag in messages getting posted to the list.

15.  Revisions to this document
------------------------------

The original (v2.6401) version of this document was prepared by Daniel
"dbaker" Baker (dbaker@distributed.net).

Kiddo (alex) helped dbaker with some of the command line options.

Mike "Silby" Silbersack (silby@execpc.com) updated and greatly expanded
this document on 2/13/1998.

Paul Gentle (gentleps@muohio.edu) converted this document to a windows
help file.

Mike "Silby" Silbersack (silby@execpc.com) updated this document and
added information about specific platforms on 05/13/1998

Mike "Silby" Silbersack (silby@execpc.com) slightly updated this
document for 2.7100 on 6/26/1998
