                      Bovine RC5-64 Personal Proxy
                           "The Readme File"
                              Version 27X

Updated 1998-01-29.

**** Pay attention!   Section names in the ini files have been revised
**** in this release to better clarify use.

Before using this proxy, flush all blocks from the existing proxy.
To do this, set maxkeysdone=1, then start the proxy.  It should flush
all blocks to the keyservers.

If you have blocks in ppbuffout.rc5, and cannot flush them, please
rename the file to something else.
ppbuffout.rc5 < 270 is not compatible with the newer release yet.


INTRODUCTION
------------

This release of the v2 Personal Proxy will allow you to serve all v2
Bovine RC564/DESII clients.  It allows you to establish one of your own
machines as a buffer between your clients and one of the "full
proxies" (keyservers) that are officially run by the distributed.net
organizers.  This will allow your clients to waste less time trying to
connect to one of the main proxies, since the personal proxy will
already have more key blocks waiting for your clients when they're
ready.

Running a personal proxy is definitely not needed by everyone, nor is
it recommended.  You should only run a personal proxy if you are very
confident of your abilities, and you have a very weak, unreliable, or
intermittant connection to the Internet to directly contact one of the
real proxies.

INSTALLATION AND OPERATION OF THE PERSONAL PROXY
------------------------------------------------
Since you have this file, you probably have already downloaded and
unpacked the proper distribution for your machine.  If not, see
ftp://ftp.distributed.net/pub/rc5/v2-proxyper/ and download the
proxy package for your machine.  Once the proxy is unpacked, you
will need to configure it.  You may rename the binary to anything
you like, but there must be a corresponding config file with ".ini"
as a suffix.  Then edit the .ini file with your favorite text editor
(configuration options are listed in the next section), and then
start the personal proxy in the directory you have installed it in.
The log and dump files will be created in this directory.

CONFIGURATION
-------------
Edit the ini file with a standard text edit and verify the settings.
Depending upon the number of clients you are serving, you may want to
increase or decrease the number of keyblocks that are kept in memory.

Note that the ini file is only read once (as the proxy starts up).
Modifications made to the ini file will not take effect until you
terminate and restart the proxy.

None of the settings in the ini file are actually required to be
specified.  All of the settings have default values that should work
for most people.  However, it is still recommended that you verify and
explictly set all of the options.


CONFIGURATION: Settings
-----------------------

[KeyServer]/ipaddress: the IP address or DNS of the keyserver from
which the proxy will retrieve and send keyblocks from.

[KeyServer]/port: the port on the keyserver to communicate to.

[KeyServer]/workperiod: determines the minimum delay (in seconds)
between sequential attempted network connections to the keyserver.
This value should typically *not* be adjusted to more than a couple of
minutes.  Doing so may cause your proxy to run out of keyblocks if
you are serving a lot of fast machines!

If you are behind a firewall and must use a proxy to make a connection
on either a telnet or http port, the following options will be useful.

[KeyServer]/uuehttpmode: 0=no special encoding, 1=uue encoding (telnet
proxies), 2=http encoding, 3=uue+http encoding

[KeyServer]/httpproxy: The name of your site's http or telnet proxy.

[KeyServer]/httpport: The port to connect to the above proxy on.

[KeyServer]/httpid: User and password authentication needed to connect
to the above proxy.  This field must be set to the *encrypted* value
of the username and password information.  In order to get this value,
use the client configuration option to specify the username and password,
then cut and paste that field from the client .ini to your proxy .ini.
Remember to restore the client configuration when you are all done with
this.

-----
[ports]

[ports]/listenaddress: The IP address of the machine this personal proxy
is running on.  This is optional and only needed if the machine has
multiple IP addresses.  If you use one ip address for local connections,
and you have a dialup account that you use to fetch and flush blocks,
you do *not* need to set this.

[ports]/port: the port on *your* machine to listen for incoming
clients on.

[ports]/port2, port3, port4: these allow you to specify additional
listening ports on *your* machine to listen simultaneously for
incoming clients on.  Typically these additional ports aren't needed,
but this ability is here if you need it.

[ports]/testport: the port on *your* machine to listen for incoming
clients on and distributed test blocks to.  This value can be
unspecified, or set to 0 to disable this functionality.

[ports]/timeout: maximum idle timeout on a client connection before
it is dropped, in seconds.

-----
[console]

[console]/detached: 0=don't detach, 1=detach from controlling terminal
and run as a daemon process.  If not specified, defaults to 0.

[console]/logfileconsole: name of console log file

[console]/logfileconsolerotation: interval to rotate console log at,
options are none, hourly, daily, monthly, or yearly

[console]/consoleverbosity: control verbosity of the console log output.
This option is a bitmask, choose which logging options you want and add
them together to specify logverbosity.  0 gives no logging, 255 full
logging.
1   : Keyblock info (downstream client communications)
2   : Upstream keyserver communications
4   : GMT time display
8   : keybuffer status (Flushing messages, etc.)
16  : general logging (Status: Slot X LISTENING, and others)
32  : statistics (ready=X/X, done=X, Xd XX:XX:XX, X.X Mkeys/sec)
64  : reserved for future use
128 : reserved for future use

-----
[rc564]

[rc564]/logfilekeyblock: name of log file of all completed keyblocks

[rc564]/logfilekeyblockrotation: interval to rotate keyblock log at,
options are none, hourly, daily, monthly, or yearly


[rc564]/maxkeysready: approximate maximum number of keys to keep
ready for serving clients.

[rc564]/minkeysready: minimum number of keys to keep ready for
serving clients.  This differs from the maxkeysready in that once the
available keys drops below this value, the proxy will "try harder" to
fetch additional keys from the server.

[rc564]/maxkeysdone: number of completed key blocks that must be done
before an outgoing connection to the keyserver is made to flush the
completed blocks.

[rc564]/timeaverage: number of 5-minute chunks to use for the sliding-average
window.  The default is 12, the valid range is 6-840 (30 min - 1 week).
Beware that setting this to a high value will consume additional
memory, for tracking the stats.

----
[desII]

see the rc564 section for the entries that you can put here, and
what they do....


----
[misc]

[misc]/logfilecompressor: the name of a script or program to run
once per log file rotation with one parameter, the name of the just
completed log file.

[misc]/proxymessage: an optional text message displayed to all
connecting clients.  If you leave this value blank or unspecified, a
default message including the build number will be displayed to
clients.

[misc]/pidfile: if specified, this is the filename that will have
the process id (pid) of the proxy when it is started up.  This is
only for Unix perproxies.

[misc]/showcumulativestats: if this is set to 1, then a line will be
displayed every workperiod interval showing the total number of
rc5 and desII blocks submitted to the proxy, and the average rate
over the entire uptime of the proxy.

----
[ignoredip]

[ignoredip]: if your perproxy is ever attacked by a malicious person,
you can use this option to prevent them from spamming blocks to your
proxy.  After the section header, ignored ips are listed in the form:
1.2.3.4=1
one line for each ip you want to ignore.

Note that the forcemail option is no longer valid.

OPERATIONS
----------
Sending a TERM or INT signal will cause the personal proxy to shut
down nicely, resaving all keyblocks that are still in memory to disk,
and closing all open network connections.

Sending a HUP signal will cause the personal proxy to open a network
connection to the keyserver and send any completed blocks and retrieve
more, if necessary.

When running the proxy in a window on Win95/NT, you can press
Ctrl-Break at any time to perform the equivalent of a HUP signal on
UNIX.  To actually close the proxy, press Ctrl-C or close window.

On WindowsNT only, you can install the proxy as a service by first
running it with the -install option to register it as a service.  You
can then start and stop the proxy from the standard WindowsNT serivces
Control Panel.  You can use the -uninstall option to remove it from
the services registry.


QUESTIONS?
----------

Q. Hey, why isn't there a new win32gui personal proxy?

A. The win32gui personal proxy is no longer being developed.  The
win32 proxy will be console based like the unix proxies from here
on out.


Q. When upgrading my personal proxy (esp. win32gui to win32 console),
it crashes on startup!

A. Be sure you have your proxy flush all outgoing blocks before upgrading.
If the new proxy crashes on startup, delete the ppbuf*.rc5 files, and
restart the proxy.


Q. What is stored in the dump files (ppbuffin.rc5 and ppbuffout.rc5)?

A. The dump files contain a mirror of the keyfiles stored in the memory
by the personal proxy.  ppbuffin.rc5 contains blocks ready to be
dispatched to clients, and ppbuffout.rc5 contains blocks completed
by clients and waiting to be sent back to the main server.  If for
some reason, your computer or the personal proxy should crash, the
dump files should ensure that no blocks are lost.



Q. How many clients can a personal proxy handle concurrently?

A. The personal proxy can have active and open connections to 32 clients
at any one time.  Since clients connect infrequently, a personal proxy
can serve several hundred clients.


Q. Can my clients or another personal proxy share my personal proxies
dump files?

A. No.  The ppbuf*.rc5 files are not compatible with the client keybuffer
files, so clients cannot share the keyproxy's dump files.  Also, since
the dump files are actual mirrors of the key blocks held in memory by
your personal proxy, they cannot be shared with another personal proxy.



Q. How does the personal proxy report IP, platform, OS, and client version
information to the master keyserver?

A. The proxy passes the platform, OS, and client version information
supplied to it by the client.  The IP address reported to the server
will be that of the personal proxy, not the client.


Q. Where can I get more help or ask other questions about the personal
proxy?

If you have any options questions or difficulties using this proxy,
you should address your messages to "rc5-proxyper@llamas.net" or to
"rc5help@slacker.com"

Note that the first address is a mailing list, and it is recommended
that you join it before sending a message to it, or you may not see
the responses to your original message.

To subscribe to the rc5-proxyper mailing list, send a message
containing the text "subscribe rc5-proxyper" to "majordomo@llamas.net"

You may also be able to obtain help on the EFNet channel #rc5.  This
is not an official support mechanism, but there are frequently other
experienced rc5'ers who are often able to answer questions and help
solve problems.

Portions of this README.TXT were lifted from the Personal Proxy FAQ,
authored by TwinTowers and Jeff Lawson.  The original README.TXT was
authored by Jeff Lawson, and this updated version was prepared
by Trif.

January 15, 1998

