$Id: readme.txt,v 1.11 1999/01/25 02:58:49 jlawson Exp $

		       distributed.net RC5DES Personal Proxy


**** Pay attention!   Configuration options 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.  Proxy buffer files created by
versions less than 300 are not compatible with any newer releases.

It is recommended that you run the proxy's -repair option on any old
buffer files from a previous 300/301 build before running upgrading to
this new version. It is also recommended that you periodically run
-repair (every day or so) on a very active proxy, to ensure that there
has not been any damage to your file buffers.

If you wish to use 2.7100 rc5des clients, you must be running personal
proxy 278 or greater.  If you do not do this, then your email credit
and platform statistics may be discarded. 


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
servers" (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
intermittent 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/dcti/proxyper-rc5des/ 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
explicitly 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]/connectperiod: 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, but it should also not be made too short, or else your proxy
might attempt to make a connection as frequently as this amount, which
may prevent it from handling incoming client connections if your proxy
is unable to successfully make outgoing server connections.

[KeyServer]/connectivity: very much like the client normal/offline/lurk/
lurkonly modes. (lurk/lurkonly only available on win32).
normal   : The proxy will attempt to connect to a server as needed.
offline  : The proxy will not attempt to make a connection to a server as
           needed.
lurk     : The proxy will automaticly send/recieve blocks when it detects
           a network connection.
lurkonly : Same as lurk, only the proxy will not trigger auto-dial.

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, 4=socks4 encoding,
5=socks5 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.  For socks4 httpid is the "username" in plaintext.  For socks5 httpid
is the "username:password" in plaintext.

-----
[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.

-----
[console]

[console]/logfileconsole: name of console log file

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

[console]/consoleverbosity: control verbosity of the console log output.
This option used to be a bitmask (combination of values OR'ed together),
but now it can be specified with a list of space-separated keywords:

all        : display all message types (default)
none       : no console output at all
general    : General logging (Status: Slot X LISTENING, and others)
stats      : Periodic statistics reports
keyblock   : Block numbers
server     : Upstream keyserver communications
client     : Downstream client communications
buffers    : statistics (ready=X/X, done=X, Xd XX:XX:XX, X.X Mkeys/sec)
timestamp  : Include UTC timestamps on each line
attention  : Keyspace change, time change, dialup events
errwarn    : Unrecognized opcodes/version
errlow     : Invalid settings
errsevere  : Operation inhibiting problems

-----
[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, yearly, or startup


[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]/minkeysdone: number of completed key blocks that will always
be kept resident and not transmitted.  There is probably no reason
for this to be anything other than 1.

[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]/statusperiod: this is the number of seconds between the status
reports from each of the current contests are printed out to the console
log. The contest status reports indicate the number of current ready and
done blocks, their set values, and also the sliding window average
keyrate, and total number of completed blocks since startup.

[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.

----
[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:

	anything=1.2.3.4,maskbits

one line for each block of IP addresses you want to ignore.  
To ignore a class C subnet (255 addresses, x.x.x.*, /24), maskbits
will be 24.  For an entire B network (65536 addresses, x.x.*.*, /16)
you will want to use a maskbits of 16.  Note that this format is
different from the format that was used in build 280 and prior of
the personal proxy.

Additionally, you can enter masks using any of these forms:

	anything=1.2.3.*
	anything=1.2.*.*
	anything=1.*.*.*



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 reload its ini
configuration file and reread most of the settings specified within it.

Sending an ALRM signal will trigger the personal proxy to create an
outgoing server connection. This is done even if your connectivity mode
is set to offline. This behavior is intentional, and permits clever
scripters to automate periodic dialups and forced server flushes.

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+ALRM signal on UNIX. To
actually close the proxy, press Ctrl-C or close window.



COMMAND LINE OPTIONS
--------------------

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.

If your buffers are indicated as being locked, you can unlock them by
running the proxy one time with the '-unlock' option. However, please be
sure that there are no other instances of the proxy still running before
doing this. This locking mechanism was intentionally added to prevent
multiple instances from accidentally being started at the same time.

Occasionally, you may find that your proxy's buffers may become
corrupted (either by block totals no longer seeming accurate, or by
seeing warning messages printed by the proxy indicating that a buffer
structure error exists). When this is the case, run the proxy one time
with the '-repair' command line option. This will force it to analyze
its buffer files and attempt to do a repair operation upon it.

Previously a "detached" mode option existed in the ini file to allow the
proxy to be started as a daemon-like service on your UNIX machine. This
has now been made available only as a command-line option, and must be
invoked by starting the proxy with '-detach' on the command line.




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

Q. My proxy says that my buffers are locked and will not start up. What
do I do?

A. Start the proxy with the command line option "-unlock" and it should
force the buffers to be marked available for use again. You should then
be able to restart the proxy normally. Please be careful when using this
option and verify that there actually are no other instances of the
proxy still running. This locking feature was intentionally added to
prevent multiple instances from running at the same time. Please note
that if you shut down the proxy properly (by sending a TERM/INT signal
on UNIX, or pressing Ctrl-C within Win95/98/NT, or shutting down the
service on WinNT), then the proxy should automatically unlock the
buffers before exiting.



Q. My proxy reports messages like "Error, block count does not make
sense" or "Error, lastnonempty pointer is x, totalunits is x" or other
similar errors that sound rather serious.

A. They are indeed serious. Try shutting down the proxy and invoke the
proxy with the -repair option. This will allow the proxy to rebuild its
buffer files, keeping any good blocks and discarding bad ones. Buffer
corruption is currently still a problem that may occur periodically, so
you should try to periodically run -repair to ensure that your buffers
are still valid.



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 buffer files (ppbuffin.rc5 and ppbuffout.rc5)?

A. The 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. My proxy's connection is frequently disconnected from the Internet
and is always too busy trying to make outgoing server connection to
handle connections from my clients. Why is it ignoring my clients?

A. Your connectperiod is so short that by the time the last server
connection attempt times out, another connectperiod has already passed
and the proxy decides that it needs to attempt to make another one.
Increase your connectperiod to at least several minutes, or (preferably)
set your connectivity mode to offline (or lurkonly on win32).



Q. How does offline mode work?

A. In offline mode, the proxy will never attempt to initiate an outgoing
server connection by itself, so it will eventually run out of blocks if
it is never given an opportunity to make a connection. You can
explicitly force the proxy to make a server connection at any time by
sending it a SIGALRM signal on UNIX, or pressing Ctrl-Break while its
window is in focus on Win32 (there is currently no equivalent for doing
this while the proxy is running as an NT service).




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 "proxyper@lists.distributed.net" or to
"rc5help@distributed.net"

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 proxyper mailing list, send a message containing
the text "subscribe proxyper" to "majordomo@lists.distributed.net"

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


---

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

January 24, 1999

