1: Basic Setup

1.1: Configuring the Distributed.net Client

To configure the client, use dpkg-reconfigure distributed-net.  This will
create the client's configuration and store it in /etc/distributed-net.conf.

By default the client runs with the input and output buffers stored in
/var/lib/distributed-net/ and the log is /var/log/distributed-net.  While
it is possible to override the location of the buffers during the
configuration of the client, it is strongly recommended that you leave
them at the default location.

If necessary, you may pass  additional command line options to the client
on start-up by adding them to the "dnetc_opts" variable in
/etc/default/distributed-net. The available options are documented in the
distributed-net man page.

1.2: Running the Distributed.net Client

By default the distributed.net client will be started on boot and will
run in the background with low priority.  Usually there is no reason to
interact with it directly.  In the case that it is necessary, you may
start, stop and restart the client as usual through the initscript
/etc/init.d/distributed-net.  The initscript provides the following
extra targets to ease interaction with the client:

reload:  This will reload the configuration and reopen the log files
         without the overhead of a restart.

flush:   This will send all completed stats units to the distributed.net
         servers

fetch:   This will top up the incoming buffers.

update:  This will perform both a flush and a fetch.

If necessary you can execute the distributed.net client directly.  It
should be noted that in version 2.9012.497-2 of this package the binary
was renamed from /usr/bin/distributed-net to /usr/bin/dnetc in order to
comply with the upstream developers naming conventions.  If you decide to
start the client manually, you should use the following options:

/usr/bin/dnetc -ini /etc/distributed-net.conf \
		       -inbase /var/lib/distributed-net/ \
		       -outbase /var/lib/distributed-net/

If you wish you may add additional options to change the behaviour of the
client.  All of the available options are documented in the
distributed-net man page.

1.3: Checking your statistics and voting

Be sure to visit http://stats.distributed.net/. There, you may follow the
links to the project you are working on, look up your email address, and
add your efforts to the LinuxNet team or the Linux Internet Support
Cooperative team, or another worthy team! Please notice that your e-mail
address will only be available one day after you send your first packet
back to a server.

Also, on the same web pages, you will find links to the Non-Profit voting
system. When you log in using the password mailed to you, you can vote on
a non-profit corporation that will get a cut of the prize money. There
are lots of worthy organizations there, but let me take the opportunity
to plug Software in the Public Interest, Debian's parent company.

2: Special Considerations

2.1: PPP (Dial-up) Internet Connections

Every time that the computer running the distributed.net client connects
to the internet via PPP the script /etc/ppp/ip-up.d/distributed.net will
be run to update the client's buffers.  If you connect to the internet
frequently then this behaviour will have the, possibly undesired, side
effect of not allowing the client to work on lower priority projects as
the input buffer for the higher priority projects will never be exhausted.

To work around this behaviour you can disable the update to the clients
buffers upon connection to the internet and have the client monitor for
an active connection directly.  To do this, edit the
/etc/default/distributed-net file and set the "syncppp" option to "NO"
then add either "-lurk" or "-lurkonly" to the "dnetc_opts" variable.  You
may also wish to specify the interface that the client is to monitor.
Consult the man page for the details on these options.

2.2: Laptops

If you are running distributed.net on a Laptop computer, then you will
want to make sure that the apm package is installed.  With an active apm
installation the distributed.net client will only run while the laptop is
on AC power.  When the laptop switches to battery power the client will
be stopped.

It should be noted that as of version 2.9012.497-4 of this package the
behaviour of the apm script has changed slightly.  In previous versions
if it was unable to determine if AC power was active or not, the client
would be shutdown.  As of 2.9012.497-4 if the state of the AC power can
not be determined then the apm script will do nothing.

2.3: Scheduling priority and Distributed.net

By default the distributed.net client runs at the lowest possible
priority (nice 20).  When the CPU is loaded with higher priority
processes, the kernel will choose to run these other processes instead of
distributed.net.  While nice 20 is the lowest possible priority, it does
not specify that the process is only to be run when the CPU is otherwise
idle.  Under these circumstances you can expect to see the
distributed.net client consuming up to 5% of the CPU time when the system
is loaded with higher priority processes.

In the situations where this behaviour is undesirable the distributed.net
client should be either stopped or suspended while the CPU is "busy."  If
you wish to suspend the client then you have a few options:

1.  Send the client SIGSTOP (kill -19) to suspend it, then send it
    SIGCONT (kill -18) to have it resume once the CPU becomes "free".

2.  Use the clients built-in suspend and resume commands.  Run
    "/usr/bin/dnetc -pause" to suspend the client, then run
	"/usr/bin/dnetc -unpause" to resume the client.

3.  Use a pause file.  Add the option "-pausefile path/to/file" to
    "dnetc_opts" in /etc/default/distributed-net.  When you wish to
	suspend the client create the previously mentioned file, then delete the
	file to resume the client.

Each approach has advantages and disadvantages over the others.  You
will need to choose the approach that best fits your needs.
