Eelco Lempsink Original version Daryl Anderman Major revision A document to guide you through the process of installing (and starting to use) giFT and OpenFT. A small notice to begin with. If you have read these instructions completely and still need help go to http://gift.sourceforge.net/contact.php. These instructions are for installing giFT on a *nix platform. For Mac OS X, please use fink. If you wish to install on Windows you are on your own. First you will need to download the latest giFT tarball from http://gift.sourceforge.net/download.php. You may also want to download the latest OpenFT plugin while you're at it. Go to the directory you downloaded the tarballs to and type (the $ is used to indicate this is a shell command): $ tar -xzvf gift-x.xx.x.tar.gz Please note that if you have downloaded the bzipped tarball, you will need to use a slightly different command line to extract. This will create a directory gift-x.xx.x/ with the giFT source. There are a few third party libraries which giFT/OpenFT can use. A few are more or less mandatory, all are recommend. OpenFT uses zlib to compress your shares list before sending it to your PARENT nodes. This will reduces the amount of data sent over the OpenFT network significantly. To enable compression you must have zlib 1.1.[34] installed. zlib is required. If you are using Debian, install zlib1g and zlib1g-dev. RPM-based distributions should use the zlib-1.1.4 and zlib-devel-1.1.4 packages. giFT uses libltdl to load the OpenFT plugin (and any other plugins you install). Libltdl is currently required. This may be installed along with libtool on OS X and other BSD-like platforms, or it may be in libltdl-dev. You can get it from www.gnu.org. TODO: add package names and a better description. OpenFT uses libdb for efficient data storage and access. If you want to function as a SEARCH node (a node that handles searches for other nodes) you'll need libdb. A version >= 3.1.x is preferred. Version 4.1.x is used by the developers for most of the testing. On Debian install libdb3-dev or libdb4.1-dev will get you the necessary files. RPM based distribution need the libdb3.3 and libdb3.3-devel or the libdb4.1 and libdb4.1-devel packages. The source is available at SleepyCat. giFT uses libmagic to guess file types. On Debian install libmagic1 and libmagic-dev. RPM-based distributions can use libmagic and libmagic-devel. Meta data from Ogg Vorbis files is extracted using libvorbis. On Debian install libvorbis and libvorbis-dev. RPM-based distributions can use libvorbis and libvorbis-devel. For image meta data ImageMagick is used. On Debian install libmagick and libmagick-dev. RPM-based distributions can use libMagick5 and libMagick5-devel. This step is pretty straight forward. Just do: $ cd gift-x.xx.x/ $ ./configure At the end of the run you'll be presented a small list with information about the extensions and meta data tools that will be used to build giFT. Check that list to see if all the stuff you wish to include is listed. If not, install it (and the related devel package!) or check if you've installed the right version. Don't forget to remove config.cache before retrying ./configure. If you need more help, try looking at the information ./configure --help gives you. This is even easier then the previous action. Type: $ make And press enter. If you get fatal errors during make, read the instructions about configuring again, and check your system setup before complaining to us. Some of our configure checks are incomplete and will appear to have found packages which are not fully installed (devel packages again). If all went well, you can now install giFT with: $ su -c 'make install' Now that giFT is installed you will need to get at least one plugin (ie OpenFT) and a frontend before you can actually use it for anything. After you have installed giFT you will need to build and install OpenFT. This is done as above: Download the latest OpenFT tarball from http://gift.sourceforge.net/download.php. If you have already done this skip to the next step. Go to the directory you downloaded the tarballs to and type: $ tar -xzvf gift-openft-x.x.x.x.tar.gz Again note that this command line will be slightly different for the bzipped tarball. Then run: $ gift-openft-x.x.x.x/ $ ./configure Finally: $ make and $ su -c 'make install' Now that you've installed OpenFT plugin, you will need to configure giFT and OpenFT. Read on MacDuff! After installing giFT and OpenFT you'll need to set them up. Be sure that you completely install any plugins you wish to use before this step. If you decide that you later wish to add a new plugin, you will need to re-run gift-setup after installation. Invocation of the setup tool is something like this: $ gift-setup Note that giFT and OpenFT will not work with the default setup, so make sure you read and understand all questions before answering or just pressing enter. To reconfigure giFT and OpenFT later, just run gift-setup again. You may choose to configure giFT/OpenFT by hand (if you don't want to run through all options again, for example. The config file for giFT is ~/.giFT/giftd.conf. Plugin configuration can be found in ~/.giFT/PLUGIN/PLUGIN.conf. Both files should include enough comments to understand the options. Normal invocation of giftd is as follows: $ giftd or $ giftd -d This will start the daemon and load all protocols that are installed and referenced in ~/.giFT/giftd.conf. The -d switch will cause giFT to fork to the background, as a daemon would be expected to do. This switch should only be used after you are certain that giftd is able to start successfully. Once giftd has been started, it will silence output to the terminal and "just sit there", waiting for user input over the interface protocol (this is where you need a GUI or frontend to attach to it). If you really want to know what it's doing (if you think it doesn't work for example), invoke with giftd -v to print debugging info to stdout or read ~/.giFT/giftd.log. Both will have the same output. When you run giFT for the first time, it will most likely hog your CPU and drive your harddrive crazy. This is because giFT will need to calculate the md5sum (this process is called 'hashing') of all your shared files to create a database. The next time you run giFT only files that were added or changed will be hashed. You can gracefully kill giFT by either delivering SIGINT or SIGTERM to giftd (killall -TERM giftd or kill <PID>), or by sending the "quit;" interface command, which usually can be done with echo "QUIT;" | nc <gift-host> <gift-port>, if you have netcat (nc). Of course, at this point you may want to actually use giFT. Search OpenFT, download files, stuff like that. For this you'll need to download a client. A list with 'good' clients is available at our website. Alternativly you can use Google's or SourceForge's search to find other clients. giFT/OpenFT keeps a logfile ~/.giFT/giftd.log which contains information about both giFT and OpenFT (and any other plugins). This file is created on startup, so don't restart giFT immediately when it crashes, but check the log and report the problem. Ah yes, the ever popular nodes file... Since many questions in our IRC channel were asked related to this file, it gets a special section here. Upon startup OpenFT reads the nodes file. Nodes are sorted by last-seen packet, and OpenFT attempts up to 15 outgoing connections every 2 minutes. When the network devides, because of a newer protocol, your nodes file will be filled with mostly old nodes. This makes it difficult to find a connection to an up-to-date node. Upon (every) install a global nodes file is installed (most likely at /usr/local/share/giFT/OpenFT/nodes). When you have problems connecting (most of the time you just need to be a little more patient), try removing your local nodes file (~/.giFT/OpenFT/nodes), and giFT will automagically read the global nodes file, and make a new local nodes file. Note that you don't have to stop giFT while doing this. More information about the giFT project and giFT/OpenFT can be found in the other documentation at our website. If you want to learn about the interface protocol (that clients use to connect to giFT) read the Interface Protocol documentation. Please check other client projects first before starting your own. See the contact page for more information about the preferable ways to ask for help and/or contact us.