INSTALLATION MANUAL: Slackware
==============================
The fci-client runs on Linux, FreeBSD, OpenBSD, Mac OS X and Windows,
the fci-server runs on Linux, and on FreeBSD & OpenBSD using Linux emulation.
The fci-client sends data from a client to the fci-server, among which are the
output of Dick Howells qd, Operating System and Hardware information and the
most interesting files in the Folding@Home client directory.
The server does almost all processing, and uses various tools to do it.
The tools uses by the FCI server are:
- xyz2pdb
- rasmol
- convert (from media-gfx/imagemagick)
- htpasswd (from Apache)
convert and htpasswd should be installed before FCI is.
xyz2pdb is shipped with FCI, just like Dick Howells qd is. xyz2pdb is used to
convert the current.xyz to a .pdb which is fed to rasmol.
A 32 bit Linux binary of rasmol is also shipped, but many Linux distros and
FreeBSD have native packages of rasmol. Slackware does not have a rasmol
package, so the rasmol binary shipped with FCI will be installed. Rasmol is
used to generate an image and/or animation of the projects in the current.xyz
which the clients upload.
convert is part of imagemagick, it's used to compile animations out of multiple
rasmol generated images.
Installing on Linux: Slackware
------------------------------
The installation process described in this document assumes that you're running
a Slackware 13.37 system, on which it has also been tested.
The fci-client has very few dependencies, the fci-server has a bit more:
Perl Module | Slackware Package
------------------------+--------------------------
Installer: |
- XML::Simple | perl
- Getopt::Mixed | CPAN
- Date::Calc | CPAN
|
Client: |
- LWP::UserAgent | libwww-perl (SlackBuilds)
- HTTP::Request::Common | libwww-perl (SlackBuilds)
- Date::Calc | CPAN
- XML::Simple | perl
- Getopt::Mixed | CPAN
Application | Slackware Package
------------------------+--------------------------
Client: |
- lsb_release | n/a
- lspci | pciutils
|
Server: |
- convert | imagemagick
- rasmol | n/a
- bunzip2 | bzip2
|
- Apache 2.x webserver | httpd
- Apache2 mod_perl | http://slackbuilds.org/repository/12.2/network/mod_perl/
Perl Module | Slackware Package
------------------------+--------------------------
Server: |
- LWP::UserAgent | libwww-perl (SlackBuilds)
- Date::Calc | CPAN
- Date::Manip | CPAN
- Date::Format | CPAN
- XML::Simple | perl
- Data::Dumper | perl
- Apache::Htpasswd | CPAN
- Getopt::Mixed | CPAN
- MIME::Lite | CPAN
- GD::Graph | CPAN
- Image::Magick | imagemagick
- Mail::RFC822::Address | CPAN
- HTML::Entities | CPAN
- RRDs | rrdtool (SlackBuilds)
- Math::Round | CPAN
|
Server with Apache 2.x: |
- Apache2::Request | libapreq2 (SlackBuilds)
- Apache2::Upload | libapreq2 (SlackBuilds)
Before you can use install.pl to install the FCI client and/or server, first
install the dependencies that you haven't installed already (e.g. when using a
full install of Slackware):
# FCI Installer only:
slackpkg install gdbm perl make gcc binutils mpfr
cpan Date::Calc
cpan Getopt::Mixed
# FCI Client only:
slackpkg install gdbm perl make gcc binutils mpfr
cpan Date::Calc
cpan Getopt::Mixed
## libwww-perl and its dependencies
for f in perl-html-tagset perl-html-parser libwww-perl
do
wget http://slackbuilds.org/slackbuilds/13.37/perl/$f.tar.gz
tar xzvf $f.tar.gz
done
cd perl-html-tagset
wget http://cpan.org/modules/by-module/HTML/HTML-Tagset-3.20.tar.gz
./perl-html-tagset.SlackBuild
installpkg /tmp/perl-html-tagset-3.20-i486-1_SBo.tgz
cd ../perl-html-parser
slackpkg install mpfr kernel-headers
wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/HTML-Parser-3.68.tar.gz
./perl-html-parser.SlackBuild
installpkg /tmp/perl-html-parser-3.68-i486-1_SBo.tgz
cd ../libwww-perl
wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-5.837.tar.gz
./libwww-perl.SlackBuild
installpkg /tmp/libwww-perl-5.837-i486-1_SBo.tgz
cd ../
# FCI Server only:
slackpkg install gdbm perl make gcc binutils mpfr bzip2
## convert (imagemagick) and its dependencies
slackpkg install libXext libXt libSM libICE libXrender librsvg libgsf libxml2 \
cairo djvulibre gtk+2 glib2 ilmbase jasper lcms openexr pango pixman \
imagemagick fftw libwmf
## mod_perl and its dependencies
slackpkg install openssl-solibs openssl httpd apr apr-util cyrus-sasl expat \
openldap-client db4 db44
cpan ExtUtils::XSBuilder
wget http://slackbuilds.org/slackbuilds/13.37/network/mod_perl.tar.gz
tar xzvf mod_perl.tar.gz
cd mod_perl
wget http://cpan.org/modules/by-module/Apache2/mod_perl-2.0.4.tar.gz
./mod_perl.SlackBuild
installpkg /tmp/mod_perl-2.0.4-i486-2_SBo.tgz
echo "Include /etc/httpd/mod_perl.conf" >> /etc/httpd/httpd.conf
sh /etc/rc.d/rc.httpd restart
cd ../
## libapreq2 (Apache2::Request & Apache2::Upload)
wget http://slackbuilds.org/slackbuilds/13.37/libraries/libapreq2.tar.gz
tar xzvf libapreq2.tar.gz
cd libapreq2
wget http://cpan.org/modules/by-module/Apache2/libapreq2-2.12.tar.gz
./libapreq2.SlackBuild
installpkg /tmp/libapreq2-2.12-i486-1_SBo.tgz
echo "LoadModule apreq_module lib/httpd/modules/mod_apreq2.so" >> /etc/httpd/httpd.conf
sh /etc/rc.d/rc.httpd restart
cd ../
## libwww-perl and its dependencies
for f in perl-html-tagset perl-html-parser libwww-perl
do
wget http://slackbuilds.org/slackbuilds/13.37/libraries/$f.tar.gz
tar xzvf $f.tar.gz
done
cd perl-html-tagset
wget http://cpan.org/modules/by-module/HTML/HTML-Tagset-3.20.tar.gz
./perl-html-tagset.SlackBuild
installpkg /tmp/perl-html-tagset-3.20-i486-1_SBo.tgz
cd ../perl-html-parser
slackpkg install mpfr kernel-headers
wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/HTML-Parser-3.64.tar.gz
./perl-html-parser.SlackBuild
installpkg /tmp/perl-html-parser-3.64-i486-1_SBo.tgz
cd ../libwww-perl
wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-5.834.tar.gz
./libwww-perl.SlackBuild
installpkg /tmp/libwww-perl-5.834-i486-1_SBo.tgz
cd ../
## rrdtool and its dependencies
slackpkg install libart_lgpl python pycairo gcc-g++ freetype libpng zlib \
libpthread-stubs libXinerama libXft libXi libXrandr libXcursor \
libXcomposite libXdamage libXfixes atk xproto renderproto kbproto \
libxml2
wget http://slackbuilds.org/slackbuilds/13.37/libraries/rrdtool.tar.gz
tar xzvf rrdtool.tar.gz
cd rrdtool
wget http://oss.oetiker.ch/rrdtool/pub/rrdtool-1.4.5.tar.gz
./rrdtool.SlackBuild
installpkg /tmp/rrdtool-1.4.5-i486-1_SBo.tgz
cd ../
## GD::Graph and its dependencies
slackpkg install libXpm libX11 fontconfig libxcb libXau libXdmcp libjpeg gd
cpan -f GD::Graph
## other modules from CPAN
cpan Date::Calc
cpan Date::Manip
cpan Date::Format
cpan Getopt::Mixed
cpan Apache::Htpasswd
cpan MIME::Lite
cpan Mail::RFC822::Address
cpan Math::Round
After the dependencies have been installed, run the installer to install the
FCI client and/or server:
# FCI client only
./install.pl --client
# FCI server only
./install.pl --server --owner <user> --group apache
# FCI client & server:
./install.pl --client --server --owner <user> --group apache
The owner of the FCI server files should be your regular user account, you
being the FCI server administrator. You shouldn't need root privileges to
run the FCI server scripts, it's enough to have your regular user account
be a member of the apache group.
The installer does require root privileges, and has several options which
you can use to customize the installation, overriding the built-in defaults:
./install.pl --help
Folding@Home Client Info Installer v1.0
Usage: install.pl [--client|--server] [OPTIONS]
Options:
-c, --client Install the client component
-s, --server Install the server component (Linux only)
-b, --bin-dir <PATH> Path of executable files (/usr/local/bin/)
-n, --conf-dir <PATH> Path of configuration files (/usr/local/etc/fci/)
-d, --data-dir <PATH> Path of the data files (/usr/local/share/fci/)
-w, --www-dir <PATH> Path of the website files (/var/www/fci/)
-o, --owner <NAME> Username to own the website files (root)
-g, --group <NAME> Username to own the website files (www-data)
-f, --force Install files & directories even if they already exist
-v, --verbose Enable verbose output
-h, --help Print this usage information
Installing the FCI client using ./install --client comes down to the following:
copy client/qd -> /usr/local/bin/qd
copy client/qdinfo.dat -> /usr/local/share/fci/qdinfo.dat
copy client/fci-client.pl -> /usr/local/bin/fci-client.pl
It installs the fci-client Perl script, and a copy of qd and its data file
qdinfo.dat for inital use by fci-client.pl. The FCI client will automatically
download the latest qdinfo.dat from the FCI server before every upload, it's
stored in its own per-user cache: ~/.fci/. A more recent revision of the qd
binary is only downloaded if the client is run with --update-qd. New revisions
of qd may contain bugfixes or new features you may want to have available to
your FCI client, but automatic download of the most recent qd binary from the
FCI server might overwrite a custom compiled binary in ~/.fci/, which is not
desirable.
The FCI client should now be ready to perform uploads to the server. It is
recommended to use the --verbose argument to fci-client.pl the first time the
FCI client command is tested for use. By default fci-client.pl doesn't display
any output unless it encounters an error, but the verbose output contains all
the information you need to verify its correct operation.
The fci-client.pl script needs to be scheduled to run periodically. To spread
the load on the server, it's recommended to use slightly different times for
the client uploads if there are many clients on a single server and/or the
server doesn't have many resources in terms of bandwidth, RAM or CPU power.
Add a rule like the one below to the crontab of the user who also runs the
Folding@Home client:
### crontab rules for FCI client ###
10 * * * * /usr/local/bin/fci-client.pl --dir /home/folding/ --url http://example.com/fci/index.pl
### crontab rules for FCI client ###
Installing the FCI server using ./install --server comes down to the following:
mkdir /var/www/fci
copy www/* -> /var/www/fci/
copy scripts/* -> /usr/local/bin/
copy bin/* -> /usr/local/bin/
chmod -R <user>:apache /var/www/fci/
It creates a directory where the server files are stored, this includes the
mod_perl scripts, XML and qd files, etc. The scripts and programs which comprise
the FCI server are installed, and the paths of these tools are updated in the
FCI server configuration: /var/www/fci/settings/site-data/config.xml
The xyz2pdb binary shipped with FCI will be copied to /usr/local/bin/ only if
it doens't exist yet (unless --force is used).
The installer will look for the convert and htpasswd binaries in /usr/bin/ and
/usr/local/bin. If convert of htpasswd are not found the installer will quit.
You can create a symlink to the convert or htpasswd binary in another location
and rerun the installer, or you can create empty file instead of a symlink.
It's recommended to set the path to the real convert or htpasswd binary using
the Settings web interface after the install has completed.
The Apache webserver still needs to be configured for FCI, before it can accept
uploads from an FCI client.
You can create the file /etc/httpd/extra/fci.conf using the below
configuration:
### /etc/httpd/extra/fci.conf ###
# FCI apache configuration
Alias /fci /var/www/fci
<Directory /var/www/fci/>
DirectoryIndex index.pl
<FilesMatch "^index\.pl$">
SetHandler perl-script
PerlHandler ModPerl::Registry
Options +ExecCGI
PerlOptions +GlobalRequest
</FilesMatch>
AllowOverride AuthConfig
# Disallow access to the Perl components
<FilesMatch "\.plc$">
deny from all
</FilesMatch>
Options -Indexes +FollowSymLinks
Order allow,deny
Allow from all
</Directory>
### /etc/httpd/extra/fci.conf ###
Before restarting apache, make sure that the mod_perl and apreq2 modules are
added to its configuration. Edit /etc/httpd/httpd.conf to include:
Include /etc/httpd/mod_perl.conf
LoadModule apreq_module lib/httpd/modules/mod_apreq2.so
Include /etc/httpd/extra/fci.conf
Restart apache to load the FCI configuration:
sh /etc/rc.d/httpd restart
It is strongly advised to use the Settings webinterface to configure HTTP
authentication for: client uploads, the client data files and the Settings
webinterface itself.
Now the FCI server should be readly to accept uploads from FCI clients.
The collection of scripts which were installed as part of the FCI server,
need to be scheduled to run periodically. And the order in which they run is
significant. Each script acquires and/or processes a specific subset of the
Folding@Home data, this data is processed into the XML files used by the FCI
server.
Add rules like the ones below to the crontab of the user who owns the FCI
server files:
### crontab rules for FCI server ###
0 * * * * /usr/local/bin/fci-update-stanford-files.pl --dir /var/www/fci/
5 * * * * /usr/local/bin/fci-update-qd-files.pl --dir /var/www/fci/
15 * * * * /usr/local/bin/fci-update-fahstats.pl --dir /var/www/fci/
#15 * * * * /usr/local/bin/fci-jmol-missing-projects.pl --dir /var/www/fci/
30 * * * * /usr/local/bin/fci-update-xml-files.pl --dir /var/www/fci/
35 * * * * /usr/local/bin/fci-generate-queue-graphs.pl --dir /var/www/fci/
35 * * * * /usr/local/bin/fci-update-jmol-projects.pl --dir /var/www/fci/
40 2,5,8,11,14,17,20,23 * * * /usr/local/bin/fci-update-eoc-stats.pl --dir /var/www/fci/
45 * * * * /usr/local/bin/fci-update-project-images.pl --dir /var/www/fci/
### crontab rules for FCI server ###
What each individual script does and how it relates to the other scripts is
described in more dept below:
fci-update-stanford-files.pl
It can be run independently, it doesn't share files with other scripts which
need to be considered. It downloads the HTML and text files from Stanfords
webserver, which are parsed by fci-update-xml-files.pl. Empty copies of these
files (except the team<N>.txt files) are shipped with FCI, but these need to
be updated with the lastest copy from Stanford first.
fci-update-qd-files.pl
It can be run independently, it doesn't share files with other scripts which
need to be considered. It download the latest qd binaries and qdinfo.dat
which the server will make available to the clients.
fci-update-fahstats.pl
It needs to run after fci-update-xml-files.pl has run, because it uses the
username-list.xml file which fci-update-xml-files.pl updates. It retrieves
the UserID for each username listed in the fahstats.com database.
fci-jmol-missing-projects.pl
It needs to run after fci-update-xml-files.pl has run, because it uses the
known-projects.xml file which fci-update-xml-files.pl updates. It checks for
projects Jmol is missing the current.xyz file for, the file is emailed if a
missing project is found in the known-projects.xml file.
fci-update-xml-files.pl
It's the main update script. It processes the uploaded data of the clients,
the downloaded data from Stanford, EXTREME Overclocking, fahstats.com and
Jmol. It updates the XML files which are used by the web interface and some
of the other FCI scripts.
fci-generate-queue-graphs.pl
It needs to be run closely after fci-update-xml-files.pl is finished. It
generates graphs of the average PPD of the Work Units in the queue. It uses
the client-list.xml file which fci-update-xml-files.pl updates.
fci-update-jmol-projects.pl
It needs to run after fci-update-stanford-files.pl has run, because it uses
the project-summary.xml which fci-update-stanford-files.pl updates. It
downloads the latest fah-projects.xml from Jmol, its data is used to link
to the Jmol webpage from a project page and to add projects which Jmol knows
about to the project-summary.xml if we don't known about it from
fci-update-stanford-file.pl yet (which uses Stanfords psummary.html to update
project-summary.xml).
fci-update-eoc-stats.pl
It needs to run after fci-update-xml-files.pl has run, because it uses the
username-list.xml file which fci-update-xml-files.pl updates. It downloads
the XML stats for each username listed.
fci-update-project-images.pl
It needs to run after fci-update-xml-files.pl has run, because it uses the
known-projects.xml file which fci-update-xml-files.pl updates. It generates
the missing image types for each known project.
|