A Complete Guide to Using FINSTALL for NEWbies

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!

THIS GUIDE IS WORK IN PROGRESS

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
 

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)

 

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

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

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

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

  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  </tt>

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.  </tt>

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

If you let finstall download qd then:  </tt> If you let finstall download fpd then:  </tt>

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  </tt>

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

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. Flags can be put into the fah_config file in ~/foldingathome directory. The flag command format in that file: </tt> 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 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