This is a step-by-step installation guide for the fah_install script.

  • Laptop users are encouraged to see the main article for special information.

  • Those with HyperThreading CPUs should read this note.

  • This HowTo is up to date for Ubuntu 8.04 (Hardy Heron).

These instructions are terminal-based. This is for consistency, because a terminal must be used for part of the procedure.

Prerequisites

If you have a 64-bit machine, you need the ia32-libs package.

sudo aptitude install ia32-libs

If you want, you can have a user ID that you can use track your contributions. Make sure you have an unused one by searching for it.

Although the Folding@Home project benefits from any donated CPU time, it is best if you leave your computer on all the time. If you want to turn your computer off at night, that's fine, but it should be on for several hours a day (e.g. 6) on average. Faster results are the best for the science.

Get the script

Open a terminal. The default directory is your home directory, hereafter refered to as $HOME, which is a variable that will expand to the actual path to your home directory.

Download the tarball.

wget -O fah.tar.gz --no-check-certificate "https://help.ubuntu.com/community/FoldingAtHome/fah_install?action=AttachFile&do=get&target=fah_install-2008-10-16.tar.gz"

Alternatively, you can download it with this link:

Extract the tarball.

tar xvf fah.tar.gz

Go to the directory with the scripts.

cd fah_install

Read the Documentation

Many questions will be answered in it. It is not strictly necessary to read it.

less README

Press q to quit the viewer.

Install

At this point, you have two choices: install for your user only, or for the entire system. It is highly recommended that you install to the system if possible, because then the client will start as soon as the machine is turned on. You need administrative privileges to install to the system.

If you wish to install to the system, simply run the script as root.

sudo ./install.sh install

Otherwise, run it as your user.

./install.sh install

The script will then ask which client you want. Choose one that matches your architecture (e.g. 64-bit or 32-bit).

If you chose a 32-bit client, you need to choose the number of CPUs in your machine. The installer tries to guess, but it does a poor job. If you have a dual core machine, choose 2. If you have a single core (even with hyperthreading), choose 1. If you have two single core processors, choose 2. In general, run a client for each physical CPU.

The script will download your chosen client from Stanford's servers. It must be downloaded from there; it can't be packaged with the installer script. The script will try really hard to get the client, but if it fails for some reason, get the client yourself and copy it to the fah_install directory.

Next the script will display a license agreement. Using the software means you agree to it's terms. Basically it says that Stanford is not responsible for damages caused by the client, you must have permission from the owner of the machine to run the client, and that you cannot modify the client.

Configuration

At this point the script will simply run the client in its initial configuration mode. The defaults are usually good enough. You can just hit Enter to use the default. What follows comes from the version 6 beta client.

  • User name [Anonymous]?

    • Use the search form to find an unused name. Being anonymous is perfectly OK if you don't want to bother with a name.

  • Team Number [0]?

    • If you want to be a part of the unstoppable juggernaut that is TeamUbuntu, enter 45104.

  • Passkey []?

    • If you want to make sure that you are the only one that can contribute under your user ID, you need a passkey. If you don't care, you don't need one.
  • Ask before fetching/sending work (no/yes) [no]?

    • Unless you know what you are doing, say "no".
  • Use proxy (yes/no) [no]?

    • Unless you need a proxy to connect to the internet, say no.
  • Acceptable size of work assignment and work result packets (bigger units may have large memory demands) -- 'small' is <5MB, 'normal' is <10MB, and 'big' is >10MB (small/normal/big) [normal]?

    • If you have less than 512 MB RAM, choose 'small'. If you have at least 512 MB RAM, say 'normal' or 'big'. If you have 1 GB or more, say 'big'. You can change this later with the reconfiguration script if you notice the client interfering with other applications.
  • Change advanced options (yes/no) [no]?

    • Type "no" and you're done.
  • Core Priority (idle/low) [idle]?

    • Choose 'idle' unless you know what you are doing.
  • Disable highly optimized assembly code (no/yes) [no]?

    • Choose 'no' unless you know what you are doing.
  • Interval, in minutes, between checkpoints (3-30) [15]?

    • This is the amount of work you lose if the computer is shutdown abruptly.
  • Memory, in MB, to indicate (1005 available) [1005]?

    • This is the amount of memory available, not how much the client will use. You get bigger assignments if you have more RAM. This will usually be slightly less than the physical amount of RAM on your system, because the kernel takes up a few MBs. Hit Enter unless you know what you're doing.

  • Set -advmethods flag always, requesting new advanced scientific cores and/or work units if available (no/yes) [no]?

    • If you can monitor the computer regularly, say 'yes'. You get more points for advanced work units, but there is a higher probability that they will break, in which case you may need to restart or even reinstall the client. Broken advanced work units are still rare.
  • Ignore any deadline information (mainly useful if system clock frequently has errors) (no/yes) [no]?

    • Usually you will not need to worry about clock errors unless they are several days off, so say 'no'.
  • Machine ID (1-16) [1]?

    • Answer "1" here. Installer will automatically set up as many clients as you asked it to. The SMP client should only have one instance running. Otherwise, there should be one for each physical CPU.

Automatic start up

If you installed to the system, the installer will automatically make an init script and make it so the client starts at boot time.

If you installed as a regular user, there is an option to make a cronjob that tries to start the client every hour. A cronjob is simply a way to run a program at specific times without user intervention. If you say 'yes', you won't have to worry about starting up the client when you log in.

Starting immediately

The installer will not immediately start the client.

If you installed to the system, run

sudo /etc/init.d/foldingathome start

If you installed as a regular user, run

~/opt/foldingathome/foldingathome start

Monitoring

You can check that the client is running by using top, or your favorite system monitor.

top

Press q to quit. The client may take several minutes to start.

You can check your progress by checking the FAHlog.txt file, MyFolding.html, and unitinfo.txt. Each client will have all three, and they are independent for each client.

If you installed to the system, they will be in /opt/foldingathome/?/; if you installed as a regular user, they are in ~/opt/foldingathome/?/, where '?' is a digit. To do a simple monitor of all clients at once, run

for i in /opt/foldingathome/?/ ; do
    tail -f $i/FAHlog.txt &
done

You can also monitor your progress using the output screenlet. Simply put

tail -n 5 /opt/foldingathome/?/FAHlog.txt

in the command to run box, where '?' is the number of the client you want to monitor. (You can get to the command to run box by right clicking on the screenlet, Properties -> Options (Tab) -> Options (Sub tab)).

You can point a web browser to the MyFolding.html file and bookmark it: file://localhost/opt/foldingathome/1/MyFolding.html.

There are other more sophisticated monitor programs. An Ubuntu user WelterPelter has created Prothink.

Tweaking

You can change options for all clients by running the reconfigure script.

If you installed to the system, run

sudo /opt/foldingathome/reconfigure.sh

If you installed as a regular user, run

~/opt/foldingathome/reconfigure.sh

With the reconfigure script, you can change any of the options that were set during the installation.

There are also configuration files. These allow you to give clients commandline options. Lines beginning with '#' are ignored.

If you installed to the system, you can set options for all clients by modifying /etc/default/foldingathome. This file will override all others. If you have a 64-bit multicore machine, this file must have an "-smp" option.

CLIENT_OPTS='-smp'

In addition you can have per-client options. If you installed to the system, these will be in /opt/foldingathome/config/client?.options; if you installed as a regular user, these will be in ~/opt/foldingathome/config/client?.options, where '?' is a digit. After editing these per-client files, run the reconfigure script.

Creating a Backup

It's a good idea to stop folding before making your backup, though it isn't absolutely necessary. Then make a tarball of foldingathome directory.

sudo tar zcvf fahbck.tar.gz /opt/foldingathome/ /etc/default/foldingathome

If you haven't modified the file /etc/default/foldingathome, then you don't need to add it. Clearly, /opt/foldingathome would become /home/$USER/opt/foldingathome if you installed it in your home directory.

Restoring a Backup

cd /
sudo tar zxvf /path/to/fahbck.tar.gz

If you somehow destroyed the /etc directory (e.g. you reinstalled the operating system), then use the installer with the "update" option to replace the init symlinks, so it can start automatically at boot time

Updating

There are two distinct things that may be updated: the client and the startup scripts. When you run the installer script with the "update" option, it will update the startup scripts, not the client.

If you need to update the client, e.g. if your beta client has expired, you should first let the current work unit finish so you don't lose any work. You should get the latest installer script from this page. Use the installer script to uninstall the client, and then use the installer script to install. The rational behind uninstalling and reinstalling instead of just updating is that I assumed that client updates would possibly break the old work units, so we might as well just throw all the old stuff away rather than risk corrupting things.

Uninstalling

Rerun the installation script with the "uninstall" option. The README file has a detailed description of what the uninstall command does.

FoldingAtHome/fah_install (last edited 2009-09-30 23:12:56 by swoody)