$Id: QUICKSTART,v 1.6 2003/07/21 22:29:39 jasta Exp $

FOREWORD
========

Thank you for taking the time to try out giFT!  Please note that this software
is in alpha stage and has not been thoroughly stress tested (that's what
you're here for, actually *grin*).  If you experience any problems
(specifically if the problems are related to fatal software bugs), please take
a look at one of the following sources to learn how you can help the
developers track down the bug:

  http://wand.cs.waikato.ac.nz/~dhtrl1/pl5/gdb.html
  http://users.actcom.co.il/~choo/lupg/tutorials/debugging/debugging-with-gdb.html

Please try to save the state of the crash until a developer (or someone else
with knowledge of the project's development) can check it out and make sure
the bug has either been fixed after your crash or determine what it is related
to.  Obviously it's very difficult to fix bugs we don't know about...


SETUP
=====

First you should download and install the plugins you wish to load through
giftd.  No plugins come default (this is changed behaviour from pre-0.11.2),
so you will need to be sure to download at least one independent of this
distribution.

Now you will need to create a local configuration for your current user.  This
can be done using the gift-setup tool which acts as a very basic interface to
the default config files.  If you would like to edit these files by hand you
can copy the relevant documentation from the etc/ distribution directory to
$HOME/.giFT.  giftd will refuse to start unless you edit the configuration
files properly, so please read carefully!

Please make sure to select the plugins you wish to load in the configuration
unless you plan to override on the command line using the --protocol (or -p)
switch.  For a list of available plugins you can use the --version (or -V)
switch, although this cannot be used until after a basic functioning
giftd.conf is in place (whacky internal design, sorry).  Be sure to run
gift-setup again after you install each additional plugin so that you can be
certain it is properly configured!

If you are wondering where the FastTrack plugin is, it is not a part of our
standard distribution and is in fact a separately maintained project that
works with giFT.  See http://developer.berlios.de/projects/gift-fasttrack for
more information on how to obtain the plugin.  Be sure to submit any bugs
specific to the FastTrack plugin to the appropriate developers.


RUNNING
=======

Remember that the giftd binary you are likely interacting with is just a
simple daemon intended to be used through the interface protocol over TCP/IP
sockets.  By default only machines within your local network can access the
interface port, however additional security may be defined and may even be
turned on by default in the future.

The most basic invocation will look something like:

  # giftd -d

Which will then fork to the background and detach from your controlling
terminal.  This does not necessarily mean the daemon is ready to accept
interface connections yet, simply that it has begun initialization.  You can
consult the log file found in $HOME/.giFT/giftd.log by default for more
information on what's going on.

To test your daemon run the giFTcurs program (available at
http://www.nongnu.org/giftcurs), which will attempt to connect to the daemon
on the host and port you configured in $HOME/.giFT/ui/ui.conf.

WARNING: Invocation of giftd will automatically try to regenerate your local
shares database which may cause your system to become unresponsive and
maintain a much higher-than-normal load.  This is because each protocol loaded
must read and generate an appropriate hash (MD5 or SHA-1 are the most common
algorithms used) for the shares.  Remember that giFT will only create hashes
for files that have changed since the last hash or if its shares database has
been removed or truncated.  Renaming (no inode tracking, sorry) or adding new
files will also cause those to be rehashed.

It is sometimes common for certain files to give giFT trouble with its hashing
and meta data extraction routines (lots of untested code folks).  If you
suspect a problem with your share hashing you can examine the operation more
closely using the following command:

  # giftd -xv

See the manual entry for more information on what these command options
actually do.


MAINTENANCE
===========

Remember that most peer-to-peer networks are not perfect and may often need a
little nudge from users to keep them operational.  Specifically, you need to
make sure the protocol plugins have the necessary caches of nodes which they
will use to make their initial entry into the network.  If this file is
largely out of date (especially if you haven't used giFT in a while) then it
is likely you will not be able to find a new node to connect to and thus it
will seem that giFT is doing "nothing".

To correct this problem you may need to examine the contents of your
$HOME/.giFT/{plugin} directories and replace the nodes or cache files that are
appropriate.  For example, you can replace OpenFT's local nodes cache with the
global default provided by us by simply removing the $HOME/.giFT/OpenFT/nodes
and starting the daemon (do not remove while it is running).  This may or may
not provide a higher quality nodes file depending on the age of your OpenFT
version and other factors.  I wish I could be more helpful than that, sigh.


PROBLEMS
========

Surely no, giFT is perfect!  Err, I mean if you have any problems with this
process you can usually find support by following the appropriate channels
defined in:

  http://www.giftproject.org/contact.php

Do not assume that the IRC channel is an appropriate place to ask for support,
because it isn't.  Asking questions there would be quite rude without reading
the contact page first.
