distributed.net client documentation document revision $Id: dnetc.txt,v 1.1.2.4 2000/04/21 13:26:33 cyp Exp $ Copyright distributed.net 1997-2000 - All Rights Reserved For use in distributed.net projects only. Any other distribution violates copyright. Use of the distributed.net client implies agreement with the prize terms listed on http://www.distributed.net/ Index --------------------------------------------------------------- 1.0 Introduction 2.0 General system requirements refer to platform specific readme.s for details 3.0 Getting and starting the client refer to platform specific readme.s for details 4.0 Upgrading from a client older than the 2.7xxx 5.0 Fetching and flushing work 5.1 over a TCP/IP network connection (and/or through a firewall) 5.2 via e-mail 5.3 to/from "remote" buffers that are serviced by another client 6.0 Help! 1.0 Introduction --------------------------------------------------- Congratulations! This distributed.net client will make your computer a part of the world's largest computer, distributed.net. The client you have downloaded is capable of working on two of distributed.net's ongoing projects: The brute-force decryption of a RC5-64 message, and the brute force decryption of a DES message. The RC5-64 contest is a long-term contest, which may take a couple of years to solve. The DES contests, run twice a year, are short (refer to the DES contest documentation for details). As a result, this client will work on DES during DES contests, and switch back to RC5-64 when no DES contest is running. No user intervention is required for this switchover. 2.0 General system requirements ------------------------------------ The system requirements for the client vary from platform to platform and are detailed in the readme.* you should have received when you downloaded the client. In general, all that is required is: - a 32-bit processor - one megabyte of free memory - a method to update local buffers (fetch/flush work). See section 5. - less than a megabyte of disk space (optional) The most important requirement for running the distributed.net client, of course, is authorization to run the client on the computer that it is installed on. This is not an issue with your home computer, but many companies and schools have policies against running outside programs on their computers. In cases where such a policy exists, ask your system administrator BEFORE attempting to install the client. It is very possible that he/she will like the idea, and choose to install the client on all computers at that site. However, if the answer is a 'no', do not push the issue. RSA's contest rules stipulate that all clients must be run on authorized systems. The only support we will give to unauthorized installations is help in uninstalling them. Although there are a number of platforms that meet these requirements, distributed.net cannot create or maintain clients for them all. The prerequisites for creating a client for a platform are: - a C++ compiler is available for that platform - the compiler 'understands' 64bit quanta ('long long', 'wide' etc) - distributed.net must have access to such a machine If you know of a platform that fulfills these requirements, and would like to have a client for the platform, you can request it at http://www.distributed.net/porting/ 3.0 Getting and starting the client -------------------------------- Clients are (barring a few exceptions) *only* available from http://www.distributed.net/download/ or from ftp servers linked from that page. They are occasionally available directly from distributed.net coders in the #distributed channel on EFNet IRC. FreeBSD clients are also available on FreeBSD distribution CDs. Once you have downloaded the client, it is a simple matter of getting going. Simply unpack/unzip/unarc the archive you downloaded and fire it up. If you have never run the client before, it will initiate the menu-driven configuration. Save and quit when done, the configuration file will be saved in the same directory as the client. Then, simply restart the client. From that point on it will use the saved configuration. Each configuration option is accompanied by a description that will assist you in making the right decisions. Most default values can be accepted as-is. Refer to the Help! section at the end of this document for sources of assistance. A "Complete Step-by-Step Guide to Running Your First Client" is available from http://distributed.net/faq/ The client's configuration may be adjusted at any time by starting the client with the -config switch. A list of other command line options can be obtained by starting the client with -help. 4.0 Upgrading from a client older than the 2.7xxx ------------------ If you are upgrading from a version of the client older than the 2.7xxx series, please stop the existing client, flush its buffers, delete all of its files before installing the new client. Buffer files formats have changed, and this will help prevent compatibility problems. If you are sharing buffer files between multiple clients, please make sure that the clients have compatible buffer formats. 5.0 Fetching and flushing work ------------------------------------- The distributed.net client can fetch/flush work using 3 methods: 1) over a TCP/IP network connection 2) via e-mail 3) to/from "remote" buffers that are serviced by another client In addition, it can share buffers with another client. 5.1 Fetching and flushing work over a TCP/IP connection --- The client uses normal TCP/IP to communicate with keyservers. It connects to port TCP port 2064 by default. distributed.net keyserver hostnames follow the following naming convention: [port].v27.distributed.net . The "port" is an optional field and may be either "80" or "23". All other numbers cause the client to ignore it and automatically select a hostname (see next para). It is generally not necessary to set a specific distributed.net keyserver hostname. The client can automatically pick one in your approximate vicinity if you leave it blank. If you do not connect through a firewall, or access to port 2064 is permitted, you can leave all network-related options at their default values. If you are connected through a strict firewall, port 2064 may be blocked by default. There are a number of methods to allow your client to fetch/flush... Configuring for firewall support is easy. a) Enter the configuration b) Select "Buffer and Buffer Update Options" menu If "Disable buffer updates to/from a keyserver" is "on", turn it off. c) Select in the "Keyserver<->client connectivity" submenu. Read on... If you have administrative access to the firewall machine, it is probably easiest to use a "data pipe" or if you are using WinGate or Internet Gate, using "direct port mapping". Both describe essentially the same thing: A piece of software, either internal to or separate from the firewall software itself, map ports on one side of the firewall to ports on the other side. That is, the "data pipe" listens for connections on a particular port on the inside of the firewall, and forwards these to a predefined host/port on the other side. Set the client's "keyserver host" and "keyserver port" to point to the datapipe, and configure the datapipe to connect to a distributed.net host (refer to the beginning of this section for information on distributed.net host names). Another method requiring administrative access, but with great advantages if you have a number of clients running inside the firewall, is to use a distributed.net personal proxy on the firewall machine. Personal proxies may be downloaded from http://www.distributed.net/download/. Configuration guides for setting up a personal proxy are beyond the scope of this document, but for the client, configuration is the same as that for a "datapipe" (in the section above). If your firewall permits access to telnet ports (port 23), or to HTTP ports (port 80), simply set the "Keyserver port" to that port. If it doesn't work, and you are sure that access to telnet ports is permitted, it is possible that your firewall does not cleanly handle 8bit data. Try again after enabling "Always use UUEncoding". UUE converts the 8bit data that that the client tries to send into 7bit data, permitting buffer updates to work even when 8bit data is not handled cleanly. This situation does not happen very often, but it does occur now and then. In addition to these "native" connectivity methods, the client also has HTTP and SOCKS proxy support: Select the "Firewall/proxy protocol" option from the menu and... For SOCKS support: Both SOCKS[4] and SOCKSv5 are supported. If you are unsure about which to use, try SOCKS4 first. Now, edit the "HTTP/SOCKS host" and "HTTP/SOCKS proxy port" and ensure that they point to the SOCKS proxy you will be communicating through. If you must use a SOCKS userid/password, enter it in the appropriate field as well. (Note: only SOCKS5 uses passwords, so that field is invisible if you select SOCKS4). For HTTP proxy support: The most compatible firewall communications method is to select "HTTP proxy" support. Next, enter the name/address of the HTTP proxy in the "HTTP/SOCKS proxy host" field and the port number of the HTTP proxy in the "HTTP/SOCKS proxy port" field. If you cannot connect to a host without explicitely specifying one, select one based on the naming conventions described in the beginning of this section. Firewall software Known to work with the distributed.net client. Software Platform Method Download from --------------------- ----------- ------------ ------------------- Squid Unix HTTP Proxy http://squid.nlanr.net Internet Gate OS/2 Port Mapping MS Proxy Server WinNT HTTP Proxy Novell BorderManager NetWare HTTP Proxy Purveyor HTTP Proxy VMS/NetWare HTTP Proxy Wingate 2.x Win32 HTTP Proxy http://www.wingate.com Port Mapping AltaVista 97 proxy Unix/Win32 HTTP 5.2 Flushing and fetching via e-mail ---- If you can not get your client to flush/fetch directly (due to a very stringent firewall), or are running a networkless client, such as the MS-DOS client, there is one last way for your client to fetch and flush: e-mail. 1. Send a message to fetch@distributed.net; an auto-responder will reply with information on the proper options to use. 2. Once you know the correct format, send a correctly formatted message in. You should quickly receive a message back with the specified amount of work attached as "buff-in.rc5". 3. Stop the client. 4. Save the file to the directory from which you are running the client. 5. Restart the client. Once your client has completed the work provided to it, you may send in back via e-mail as follows: 1. Create a message to flush@distributed.net with the file "buff-out.rc5" attached as a MIME/base64 or UUencoded (UUE) file. You will be send a "receipt" of the proper flushing within a few minutes. 2. Delete the buff-out.rc5 file so that you do not accidently send part of its contents twice. 5.3 Flushing and fetching using remote buffers ---- "Remote buffers" are simply buffers that are serviced by another client. When fetching/flushing from/to remote buffers, the client opens the remote files and moves what it needs from/to its "local" buffer files. The difference betwees "remote buffers" and "shared buffers" is of course the fact that with "remote buffers" each client has its own files. Lock contention is thus minimized and they can work without the user having to worry about the network (if one exists) between them failing. 6.0 Help! ---------------------------------------------------------- If you've having a problem with the client, the first place you should visit is http://www.distributed.net/download/ to see if a newer version is available. It is likely that a given bug you have been experiencing will be fixed by the new version. If you are still having problems, here are a few places you can find help (in order of responsiveness). - The quickest way to get question(s) answered about the operation and setup of the client is to connect to an EFNet IRC server and join the channel #distributed. Although there are dozens of EFNet servers world-wide, the following should give you a starting point: In the U.S: irc.cs.cmu.edu:6667, ingenue.eecs.berkeley.edu:6667, piglet.cc.utexas.edu:6667. In Europe: irc.homelien.no:6667, irc.df.lth.se:6667, or efnet.demon.co.uk:6667 - If you need further assistance with client use or operation, refer to the the list of "Frequently asked Questions" (FAQs) available online at http://www.distributed.net/faq/ Documents cover every aspect of running a client including "The Complete Step by Step Guide to Running Your First Client", "How To Join A Team", and the popular "Statistics Server FAQ". - If you don't mind your mailbox receiving a few messages a day, you may consider subscribing to the general client mailing list at (To subscribe to the mailing list, send a message to with "subscribe rc5" as the message text). - More user support is available from as well as from our regional support representatives listed at http://www.distributed.net/regional/index.html - If you believe you have found a bug in the client or would like to make a suggestion, please use the bug tracking pages at http://www.distributed.net/bugs/ DO NOT FORGET TO PROVIDE THE **FULL** VERSION NUMBER OF YOUR CLIENT Don't fret if you don't get a response right away - porters are usually very busy and it may take weeks before they get around to answering your message.