A Complete Guide to Using FINSTALL for NEWbies

From FaHWiki

Finstall is a BASH-based script created by IvoShiee to be used in conjunction with the FAH program.

With Finstall, the FAH client can run without you doing anything except running your computer!

Applications for Finstall

This guide is for NEWbies, geared towards the NEWEST of newbies. If you have just obtained or installed a Linux distribution (or a MAC OSX) on your computer, and have no exposure to anything similar (such as any Unix-based system or command line interface), then this guide will help you through. If you already know some Linux, please bear that in mind.

Finstall will integrate with most Unix/Linux-based distributions and with MAC OSX.
The utility will not work with Windows operating systems.
The Finstall utilty also contains the optional fpd and qd utilities created by Dick Howell(rph_iv).

There are many distributions (distros) of GNU/Linux and many ways to accomplish similar processes, even within each distro.
This guide is written from a Suse 9.2 Pro user's perspective.

Features of this Guide

Installation, Automatic Start Up, Minor Configurations, Progress Monitoring
The goal of this document is to provide the newbie with very basic information, written as simply as possible. Because some minimal knowledge of Linux is needed to install and use Finstall, that will also be covered.

More advanced features of FAH/FINSTALL will not be included because then it would no longer be a NEWbie guide. The basics for installing and using Finstall, doing simple configurations and viewing progress are the core components. However, there is one small semi-advanced level section at the end of this guide.

Terminology

argument
Same thing as a flag. Commands typed after the executable file which provide additional instructions for that file.

BASH
Bourne Again Shell. An acronym for a shell, of which there are several. The shell prompts you to type in a command.

client
A client is a computer application that requires a server to function. The FAH program is a client.

command line
A command line is found in a shell. Also known as command line prompt, terminal window, terminal emulator, BASH prompt and may also be referred to as the console. In Suse (probably all Linux) you can open up to 6 terminals at one time.

console
Also known as the shell or terminal window.

dedicated user
Ususally a virtual user with no actual user of the account, where the user account is being used for limited uses only. Example: A dedicated FAH user.

DC
Distributed Computing. The Folding@Home project is a distributed computing system. Concept where a computationally intensive problem will be broken down into smaller parallelly solvable pieces.

directory
Directories are like folders on a Windows system and they can have multiple subdirectories within them, called a tree. Every Linux file is in a directory. It starts at a root directory and is divided into subdirectories (the path) with slash marks (/). /home/mainfolder/subfolder/subfolder

flag
A flag is part of a command and is indicated with a dash mark.
More accurately, they are called arguments. Example: -oneunit -config

GNU
A vast collection of free software that makes up the majority of Linux programs. GNU is not Unix.

GNU/Linux
The preferred term by free software advocates for the entire quantity of Linux kernel systems available within the GNU Project.

gui
Pronounced "goo ee". Graphical user interface, as opposed to a command line system, such as MSDOS. Gui is software with a graphical display. Windows operating systems are gui systems.

midnight commander (MC)
A program within Linux with a command line, help menu, list of files, and visible list of commands, accessible from any terminal window by typing mc .

*nix
Abbreviation for Unix, and inclusive of all Unix-based or Unix-like operating systems.

os
Operating System (ok, most of you know this already)

permissions
There are 3 sets of permissions for every file in Linux. More to follow..

queue

root user
Root is the username for the superuser(su) on a Linux system. Also known as the Administrator. On the command line (shell prompt), the root prompt will be a hash mark (#).
Root can create, modify, delete and run any file or program on the system. An ordinary user has restricted access. It is important to use root as briefly as possible when needed, and return to a user status for most computing work. Your risk to important system files is lower that way.

service, run as Operating a function of the operating system automatically in the background. Once a program is set up as a service, you can verify it is actually running with the command top entered in a shell.

shell
Another word for terminal. A window with a command line (non-graphical) that usually has > or C:

script
A list of commands in a file. Can be one line or hundreds. The FINSTALL utility is a script.

wget
A console-based (with no GUI) HTTP file download utility. There are other similar utilities, such as curl.

WU
Folding@Home runs various projects, called work units, on your computer. They are commonly referred to as WUs.

Navigation and The File System

Knowing How To Get Around Will Get You Everywhere
It can be a bit nerve-wracking to have a whole bunch of files that you can't find. Not to mention the apprehension that goes with having typed a command that appears to not be working, while in actuality, it is. This, you find out later!

THE TYPICAL LINUX FILE SYSTEM

/ - root filesystem.

/home - all users have their home directory under that directory.

/root - root user home directory.

WHERE TO PUT FINSTALL

The best place is your home directory. By default, opening a terminal (console) starts there.

HOW TO GET AROUND

CHANGE DIRECTORY

Use the cd command in a terminal window to find files and folders and their locations.

MIDNIGHT COMMANDER (MC)

This is a program within Linux. Type mc into any terminal to get there. It has a command line, help menu, list of files, and visible list of commands.

TOP

This screen will show every service and program currently running on your system.

Access it by typing top into any terminal window.

Quit out by typing the letter q . This will bring you back to the command line and you can then simply close the window with the X box.

ROOT vs. USER

The Root user (also known as the administrator) has access to the entire system and could delete and change settings of programs and files. It is important to know what you are doing while logged in as Root.

BE VERY CAREFUL! You won't want to be reinstalling your system, or losing important files.

All users, including the system owner(Root user) should normally log in under a regular User password. Use Root only when absolutely necessary.

Commands

cd - Change Directory. Used without arguments will take you to the home directory.
[CTRL C] - Stop all programs that are running from an active console, including those running as a service (not visible) Can also be used to stop the FAH client.
curl - Command used to download a file using HTTP. Similar to wget.
chmod - Change the permissions of a file, including execution rights.
/etc/init.d/folding start - Start the FAH client.
/etc/init.d/folding stop - Stop the FAH client.
./finstall - Install the FAH client.
./folding start - Start the FAH client via FINSTALL.
./folding stop - Stop the FAH client.
ls - Directory listing. Lists contents of the CURRENT directory (folder) only.
mkdir - Make Directory. Same as creating a folder in a Windows system.
./installService - Install the FAH client as a service. This does NOT start the FAH program. The installService script is set up during the FINSTALL installation process.
kill - Used to send various signals to a running program (process). Can also be used to stop a running program.
killall - Same as kill, except that a specific program name must be included as an argument.
locate queue.dat - Find "queue.dat" in the filesystem. WHAT IS QUEUE.DAT??
rm - Remove file/directory. Be VERY careful using this command!
./serviceInstall - Install the FAH client to be run automatically in the background. The script folding is copied to the directory /etc/init.d/ with this command.
su - Super User. Can be used to gain ROOT user permissions.
top - Shows all running programs (processes).

Flags

  -config      Configure user information.  FAH will start up after you type in your configurations.
  -configonly  Configure user information, then exit without starting the FAH.
  -queueinfo   Get information on queued work units
  -delete x    Delete item #x from work queue
  -send x      Send result #x to server then exit. Use x=all to send all results
  -verbosity x Sets the output level, from 1 to 9 (max). The default is 3
  -pause       Pause after finishing & trying to send current unit
  -oneunit     Exit after completing one work unit (WU).  The FAH program will not start another WU.
  -forceasm    Force core assembly optimizations to be used if available
  -advmethods  Use new advanced scientific cores and/or work units if available
  -freeBSD     Make brandelf system call on downloaded cores.
  -openBSD     Make elf2olf system call on downloaded cores.

The FAH client flags are also covered here: The FAH client on Linux.

Installation and Set Up

Pre-Installation
1. Decide where you will be putting the FAH and FINSTALL programs in your system. They should be located in a User directory, NOT in the Root directory.

2. Create a folder (directory) called foldingathome in your home directory.

3. Decide if you want to install qd and fpd (optional visual monitoring utilities) For more information about these utilities go here.
Up to date versions of qd and its data file qdinfo.dat are now being maintained here.

4. Decide on a user name and FAH Team to join, if you don't already have these established.
You need to know the team number before you start the installation.
There are many fine teams you can join. It is a useful way to acquire help if you need it for maintaining the FAH client, and it is also a lot of fun! You can get more information about teams in the Folding-Community forums. You can also google folding teams.

5. Make sure you are logged on as an User, NOT as Root.

6. Get in a terminal window (command line). At this point, you may find it easiest to use Midnight Commander to set everything up. It shows a list of files and has a help menu. To access it, simply type mc on the command line.

Installation
7. Download the FINSTALL script into the foldingathome directory (folder)

 curl -O http://ra.vendomar.ee/~ivo/finstall 

8. Make FINSTALL executable (this is NOT starting the program)

 chmod +x finstall 

9. Install FINSTALL

 ./finstall 

After you do this, a long bunch of stuff will run out on the screen.
It will start by saying:

This is FAH (Folding at Home) installation script (ver 4.4)
To get to know more about FAH, go to http://folding.stanford.edu
Testing availability of external utilities...

etc.

When it stops running out, there will be some questions for you to answer.

10. QUESTIONS

Is this the correct MD5SUM value for FAH502-Linux.exe (y/n)?

You should check the number shown here at the Stanford Folding@Home download link

Some third party FAH utilities can be used by folding script:
Dick Howell's qd  and fpd.  Do you want to use these scripts?

If you say yes, the FINSTALL program will install and set up these utilities on your computer.
They are very nice utilities to have for viewing the Folding@Home program.

Configure the Program
11. It then sets up the FAH files and ends at the configuration menu. For more information on answering these 12 or so questions go here.
After everything is completely set up and running, you will have the option to make changes and set up additional configurations as well.

12. Next you can either start the program manually, or you can go to step 13 and set it up to run on automatic.
To start the program manually, type

./folding start

more to follow...

Set It, Forget It and Watch It!

Running on Automatic
13. Next you will be installing FAH as a Service
Do this only if you want to run FAH automatically, which is the easiest and really the best way to do it.

 ~/foldingathome/installService 

Monitor and Enjoy!
14. Using the fpd and qd utilities.

If you let finstall download qd then:

 /etc/init.d/folding status dirs 

If you let finstall download fpd then:

 /etc/init.d/folding status dirs fpd

top view status of a service in the shell Konsole.
q stop the top command. Status information will still remain on the screen. However, you can simply close the window at this point if you are finished entering commands.

more to follow...

List of Files and Folders

It is helpful to know exactly what is initially installed on your computer with the Finstall utility. Below is a list of each file or folder. Once FAH begins to fold on your computer, it will set up additional files on its own. You don't need to worry about any of that, except that all your FAH/Finstall files should be located in your main folder called foldingathome

This information is simply a resource to refer to for purposes of navigation and understanding what should be in those folders. As you gain experience, you may want to do more with some of them. For example, FAHlog.txt is useful for checking that your user name has been tied to the FAH you are running so that you will get your points credited. A few of the many other things it shows include which core of the FAH you are running, the project number, the number of frames it will be completing and how far along it is in the process. It is a very useful monitoring tool.

Once the FAH is installed, your foldingathome folder will contain one Folder, four Text Files and eight Executable Files. (includes the choice to include fpd and qd)

The CPU1 Folder will contain three Text Files, two Executable Files and five ShortCuts to Executable files from the foldingathome folder.

foldingathome
FOLDER: CPU1
TEXT FILES: fah_config; FAHLinux.txt; finstallFAQ.txt; qdinfo.dat
EXECUTABLES: FAH502-Linux.exe; fahback; finstall; folding; .fpd; installService; qd; uninstallservice

[user@machine foldingathome]$ ls
CPU1              FAHLinux.txt     fpd             qdinfo.dat
FAH502-Linux.exe  finstallFAQ.txt  installService  uninstallService
fah_config        folding          qd
[user@machine foldingathome]$

CPU1
TEXT FILES: FAHlog.txt; machinedependent.dat; MyFolding.html
EXECUTABLES: client.cfg; FaH
SHORTCUTS: FAH502-Console.exe; FAH502-Linux.exe; fpq; qd; qdinfo.dat

[user@machine foldingathome]$ cd CPU1
[user@machine CPU1]$ ls
client.cfg  FAH502-Console.exe  FAHlog.txt  machinedependent.dat  qd
FaH         FAH502-Linux.exe    fpd         MyFolding.html        qdinfo.dat
[user@machine CPU1]$

Questions and Answers

How do I type into a shell?

What if I open another shell window? What happens to the running program? Will FAH be stopped?

Where am I? Where are the files? How do I see what is where?

Where can I get more information about the folding program and the contributions of me and my team?

How do I check on the status of the current WU?

What happens if I turn off my computer?

I want to install FAH on more than one computer. How do I do that with Finstall?

I keep getting the message in the FAHlog "previous termination of core was improper." What should I do?

Can I use the EMII utility to monitor FAH?

What are permissions and how do I set them up correctly?

How can I make changes later after FAH is set up and running?

I already have FAH on my computer. How do I do the install?

It is so messed up, what do I do now?

More of What Finstall Can Do ~ Beyond Basic

More about flags
All possible FAH flags are listed and commented at The_FAH_client_on_Linux
The finstall will add "-verbosity 9" to the client by default.

FAH_flags=""

Just add your desired flags between these "" marks and restart the FAH client with the folding script.

Installing FAH on a dual CPU computer
Nothing special - if you install fresh then the finstall will detect amount of the CPUs and will install as much FAH clients as there is CPUs.

Installing with Existing FAH client

more to come

Advanced Tweaks
Look at The_finstall_script for more information.

Resources and More Information

Download the Finstall script from: http://ra.vendomar.ee/~ivo/finstall
Folding at Home Forum, Finstall Information: http://folding-community.org/viewtopic.php?t=2283
Finstall Installation Advanced Version: http://ra.vendomar.ee/%7Eivo/finstallFAQ.txt
How to add flags: The_finstall_script#folding_-_FAH_client_flags
Statistics From Stanford: http://folding.stanford.edu/stats.html
Statistics from Extreme Overclocking: (very detailed) http://folding.extremeoverclocking.com/
Google Compute (Linux): http://toolbar.google.com/dc/
Linux Directory Structure: http://www.linuxforums.org/tutorials/1/tutorial-5220.html
Linux Newbies: http://linuxnewbies.editthispage.com/
The Linux Tutorial: http://www.linux-tutorial.info/index.php
Low Fat Linux: http://www.lowfatlinux.com/

Credits and Author Statement

The writing of this guide stemmed from a nine-day ordeal in which half a dozen folks contributed many lengthy posts to assist the newbie of all newbies with installing the Finstall/FAH502-Linux program. That newbie was me. Those grueling days ended in the success of FAH running on my system so that it could fold for a cure for cancer and other diseases. It is with great pleasure that I write this guide, out of respect and thanks for the incredible amount of expertise and hand holding these people provided. And, because I believe that somebody who knows absolutely nothing about Linux does not have to wait out a lengthy learning process before their computer starts folding for a cure.

If this guide has helped you to install the program with minimal challenges, if any, then it has served its purpose. Best to you in your folding experiences and with any connections you choose to make that are available in the folding at home community. There are many resources. Do check them out. A small listing is provided in the resources section of this guide. Happy Folding!

User:Zin