The finstall script

This page is based on finstallFAQ.txt.

Finstall Script Overview
If any Distributed Computing (DC) client wants to be successful, it should be possible to install it, start it and then forget about it - no babysitting nor manual tinkering.

Since the Folding@home (FAH) console client does not fill those requirements itself, there is a need for 3rd party utilities to fill the void. One of these is the finstall script.

In the basic setup, finstall will download the FAH client and set up as many FAH clients as there are CPUs. The whole process is simple and can be made automatic ("./finstall auto") - the only input needed from the user is the initial, one-time configuration.

The finstall script will generate all needed directories, files and additional scripts that will make it possible to check the status of any running FAH client ("./folding status"), install FAH as a service to be started on machine bootup ("./installService"), run the FAH clients manually ("./folding start", "./folding stop") or even run the FAH client(s) the "official way" inside the terminal window ("./FaH").

The finstall generated FAH service script have no graphical hooks to KDE, Gnome or whatever desktop environment you run, and all standard service management tools should be able to communicate with it as with any other service on your machine.

The finstall supports (almost) any sort of Unix out there (including MacOSX) and can even install the FAH Win32 console client for running in Wine.

finstall - installation
NOTE: All commands should be typed in to console. Either use the text only console or run xterm, konsole or other console emulation programs under graphical environment. The commands to be typed in are after the "$" sign.

Note2: Some illustrations about the finstall installation procedure are available at http://ra.vendomar.ee/%7Eivo/finstall_in_action.html

It should be easy. Just download the finstall script and start it.

Short version
 

Long version
1. Download the finstall http://ra.vendomar.ee/~ivo/finstall either with a browser or with wget/curl/...:   At least MacOSX has no wget, but has curl:   Note: This will place the finstall into the current directory you are in.

2. Make the script runnable:   Note: The finstall script will install FAH client(s) with "runners" permissions. Running anything non-essential under ROOT account is bad practice by itself, make a dedicated user for FAH and start finstall over there.

3. Start it (with switches):   or   or   or   ...

Note1: The ./finstall default behaviour is to set the FAH client up in "passive mode" so user will not have direct access to running FAH instance (for viewing the output or answering possible questions). To override this, use "./finstall screen" option. ( Example: http://folding-community.org/viewtopic.php?t=9537 )

Note2: On platforms (MACOSX & OpenBSD) where default shell is not BASH, You may need to start the ./finstall with:  </tt> Attention: If the FAH is already running or You have installed the FAH "long time ago" and performing a FAH upgrade - You are not required to delete previous copy of ~/folding@home/..., only thing to do is to stop the running FAH and rename ~/folding@home/ to ~/foldingathome/, before You run ./finstall:  </tt>

4. and follow the instructions...

5. To get FAH client(s) going there are couple of ways - either use ./foldingathome/CPUx/FaH script(s) directly, use "/home/xxxxx/foldingathome/folding start" to start FAH by hand or set up it as a (bootup) service (FAH as a service).

Upgrading existing FAH clients to "finstall format"
To move any existing FAH client setups over to "finstall format": 1. Stop all running FAH clients; 2. Make a "foldingathome" directory to Your homedirectory; 3. Make as many CPU# subdirectories (ex. if You have 1 FAH client then subdirectory CPU1 if just fine, but if there are 4 FAH clients then make CPU1, CPU2, CPU3 and CPU4 named subdirectories) into this foldingathome directory as the FAH clients are You running on this system; 4. Move the old FAH clients directory contents one by one over to these CPU1...CPUn directories; 5. Change the ownership of the files to avoid permission errors; 6. Download finstall, add execution rights to it and fire it up; 7. After answering some questions, You can install FAH as service ("./foldingathome/installService") or start it manually ("./foldingathome/folding start") or ...;

Example from http://folding-community.org/viewtopic.php?p=93096#93096:  </tt> Note: Be careful with the "rm". If You type it wrong then it may delete something different You intended. All this moving and copying is easily done with the Midnigh Commander (mc).

Finstall - folding start/stop
After the client is installed You can start/stop/... it with ~/foldingathome/folding script

EG...  </tt> Typical use:  </tt>  </tt>

You can skip the phase #1 of the "stopping" if to add "force" option, but it is not advicable as it will kill FAH without giving it any time to finish its job normal way.

Note: If Your box (computer) has multiple CPUs or You somehow want to specify some particular instance of FAH clients - You can add a CPU-named subdirectory number or "dirs"/"cpus" ("cpus" & "dirs") to folding "start"/"stop" option:  </tt>

There is also a "restart" option. It is "stop" and "start" combined:  </tt> To start the FAH client(s) during system startup or more automatic way then read "[folding as a service]" paragraph below.

folding status options
./folding status - will show status of proccesses named "FaH", "fahclient*", and "*Core_*.exe". Note: "*" of "fahclient*" is numbered by "dirs" ("cpus" & "dirs") and Core file names are from these CPU-named subdirectories. If you use plain "status", there will be no process identification per CPU-named subdirectories and no FAH WU status will be reported. To get the status of FAH WUs, you must add a CPU-named subdirectory number or ("cpus" & "dirs") option. ./folding status dirs - will show the status of all CPU-named subdirectories. ./folding status 1 - will show the status of CPU1. ./folding status 2 - will show the status of CPU2. ./folding status 3 - will show the status of CPU3. ./folding status 4 - will show the status of CPU4. etc... Typical use:  </tt>

The "Index 1:..." will only be there if you allowed finstall to install the "qd" third party app (3rd party tools). If you did not allow the qd to install, it will show you the unitinfo.txt output instead.

 </tt>

To get last 10 lines of FAHlog.txt, add "viewlog":  </tt>

folding as a service
Add to the bottom of Your distro bootup file (under Mandrake - rc.boot; SuSe - boot.local; RedHat - rc.local; ...) following lines:  </tt>

Note: "Where_I_installed_the_FAH" is usually under foldingathome subdirectory of Your homedirectory. Example: Under one of my box I installed the FAH as user xxxxx, so folding script is under /home/xxxxx/foldingathome/ directory:  </tt> and lines at the end of /etc/rc.d/rc.local are:  </tt>

If You distribution support SysV startup scripts (at least RedHat does it) then there is another way to run FAH as a service: 1. Copy /home/xxxxx/foldingathome/folding to /etc/init.d/ (only root user can carry out this operation); 2. Run "chkconfig --add folding" or enable "folding" with some service manager;  </tt> No additional /etc/rc.d/rc.* file modification should be needed. Note1: There is ~/foldingathome/installService script what will implement the "service install" procedure. The script is different for platforms, verify and run it if You want to use the "service adding" procedures. Note2: To upgrade only the folding script You even haven't stop the FAH clients. Just download newer finstall and start it. Even if it will stop and complain as FAH already running, it has extracted new folding script. It is easy to start ./foldingathome/installService and reinstall the new folding script over old one. Methods described earlier required a ROOT permissions, but if to use CRONTAB, You need not be ROOT. "@reboot" method is described over: http://teammacosx.homeunix.com/forum/cgi-bin/ikonboard.pl?s=630986ed363be3092a8737a56af58b87;act=ST;f=10;t=173 Short "crontab" howto: Start "crontab -e", press "i", add "@reboot /home/xxxxx/foldingathome/folding start >/dev/null" to the end of file, press [Esc] key, type ":x" and press [Enter]. Note: You may need to add some other parameters to the crontab as well. Fore more information look at http://folding-community.org/viewtopic.php?p=77898#77898 Attention: You should NEVER run FAH or any (resident) program on computer You have no permissions to do so. If nothing else then this is unethical and at worst case You will get fined/jailed for stealing (computing) time and resources.

folding - usage of "cpus" and "dirs" options
Options "cpus" and "dirs" are functions of folding script what will specify to what ./foldingathome/ CPU-named subdirectories to carry out the main function ("start", "stop", "restart" or "status"). "cpus" option will count detected CPUs. If Your box has 4 CPUs then it will force finstall/folding to use directories CPU1, CPU2, CPU3 and CPU4. "dirs" option will detect ./foldingathome/ CPU-named subdirectory numbers. You can make unlimited number of CPU subdirectories:  </tt> In this setup "dirs" will force finstall/folding to use directories CPU1, CPU100, CPU3 and CPU4. "dirs" option will relay to "cpus" functionality when no CPU-named subdirectories are found. Note: finstall script will always relay on "dirs" and by "dirs" definition, finstall will always carry out an update, not a fresh install (unless it is a first install of the FAH).

3rd party FAH tools
Starting with "finstall" version 1.9 it is possible to let "finstall" download and use Dick Howell's "qd" and "fpd" (qd/fpd at http://linuxminded.xs4all.nl/mirror/www.boston.quik.com/rph/fah.html).

"qd" is for showing the status of the WUs and "fpd" is X11 util for showing the protein itself (requires a X server at viewers side and one great thing - it is working over ssh session just fine).

There is no special flags needed to get "qd" printout from "folding" - if there is "qd" executable/symlink to "qd" executable in CPU-named directory then it will be used: <tt> </tt>

Note: To not to use "qd", even if it is available, use "noqd": <tt> </tt>

To get "fpd" going: <tt> </tt> Note: It will work only if there is "fpd" executable/symlink to "fpd" executable in CPU-named directory.

If You want to force downloading 3rd party FAH tools then use "get3rd": <tt> </tt> If You do not want to be asked about nor download (but still use if already downloaded) any 3rd party FAH tools then use "skip3rd": <tt> </tt> If You do not want to use any 3rd party FAH tools then use "no3rd": <tt> </tt>

finstall - automation (finstall options)
It is possible to use "finstall" without human intervention (*).

(*) At current state the only truly needed input from user is the "first-time-run-for-config-typing" of FAH client.

Available "finstall" options for automation:

1) "nofetch" - will deny all download operations by ./finstall. "FAH3Console" and any 3rd party tool You want to use must be in "foldingathome" directory.

2) "nomd5" - no "FAH3Console" MD5 checkings (MD5 values are at FAH Client Download Page), the FAH client will be deleted and forced to be downloaded again (except when used with "nofetch" or there is no wget available on that system).

3) "norun" - "FAH3Console" will not be runned even there is a need for "first-time-run-for-config-typing". Despite user choices, there must be client.cfg file for a FAH client and it will ask for it...

4) "keepcfg" - no attempts will be made to run FAH client if there is client.cfg file already present.

5) "copycfg" - "finstall" will copy first suitable client.cfg file to remaining FAH client directories.

6) "no3rd" - no 3rd party tools will be downloaded nor used by "folding" script and all symlinks to "qd"/"fpd" (3rd party tools) will be removed from FAH client (CPUx) directories.

7) "freebsd" - use it if You want to use the FAH client under FreeBSD.

8) "wine" - will download and install Win32 version of the FAH client.

9) "skip3rd" - use it if You have 3rd party tools (3rd party tools) already downloaded and do not want to or can't update these.

10) "fcliA" and "fcliB" - These options are obsolete as there is now only one version of FAH Linux client.

11) "nodocs" - Use "nodocs" if You already have read finstallFAQ.txt ro do not want to be asked about it.

12) "get3rd" - Use "get3rd" to force downloading of 3rd party FAH utilities.

13) "setid" - Use "setid" to set client.cfg "machineid" to unique value. It is not possible to have more than 4 FAH clients in one foldingathome directory or (when using Wine) under the same user.

14) "keepid" - Use "keepid" to prevent MachineID changing even it may be needed (useful when upgrading).

15) "auto" - Use "auto" to run ./finstall in "no questions asked" mode. Note: Until there is no implemention of automatic generating of client.cfg file, use it only when upgrading previous FAH installation(s).

16) "screen" and "noscreen" - Use "screen" if You would like to check FAH client console output and need interactive access to it.

Note: When using 'screen' use "screen -r" to get output of some running FAH client(s) and use CRTL+A+D to rehide it again.

"noscreen" will disable the usage of 'screen' utility (used by default).

17) "samba" - Use "samba" if You would like to use "SAMBA share adding script" ./finstallSamba.

Note: ./finstallSamba can be run only by root user as other users do not have access to /etc/samba/smb.conf.

18) "macosx" - Target platform is MACOSX.

19) "linux" - Target platform is Linux. If the platform detection is unable to detect MACOSX nor OpenBSD then the target will be set as Linux.

20) "setcfg" - Will force the reconfiguration of the client(s).

21) "openbsd" - This option will extract the brandelf script and will set the Linux FAH client up for OpenBSD. Read more at http://www.schnarff.com/fah.html

22) "gentoo" - As Gentoo has somewhat different ways to service install, use this when running finstall on Gentoo.

23) "debug" - Turn on BASH debug trace.

Kranki2 wrote: The "debug" turns on the bash trace mechanism when it is executed. So, if I input "./finstall macosx no3rd smp debug dirs 4", bash shows me every statement and result of that statement for processing the 'dirs 4' and beyond. In the old days of IBM's CICS, you only had a trace table as a debugging guide and I just learned to use tracing for debugging. It is pretty handy for you because a user can specify "debug" and send you the output so that you can see what happened.

24) "smp" - This option will get you a SMP FAH client.

25) "dirs" - This option will let you specify how many FAH clients you want to install.

folding - FAH client flags
Because the "stock" FAH client behaviour without any flags MUST be adequate enough for any "beginner" FAH donator, the finstall script itself will set no additional FAH flags (only exception is "-verbosity 9"). To more knowledged FAH donators there is a ~/foldingathome/fah_config file where You can add all required FAH flags (ex. FAH_flags="-advmethods -forceasm -forceSSE"). Btw: the bfinstall script does set "-advmethods -forceasm -forceSSE" by itself, but as it is a BETA FAH installation script and FAH donator MUST be somewhat more involved to FAH before she/he starts using any beta FAH clients. The "FaH" script is the one what will run the FAH console, if there is a need to add/remove some FAH console flags then You either modify FAH_default_flags variable or act according to instructions contained inside "FaH" script: <tt> </tt>

"wine" version of the last line: <tt> </tt> "freebsd" version of the last line: <tt> </tt>

Note1: The "FaH" script is in the CPU# directories. Note2: "$add_pref" is there for "screen" util. If to use "screen" option of ./finstall, the $add_pref will be set to "screen -dmS FAHx".

Also, You can run the ./FaH script directly with additional flags and without a need to modify it: <tt> </tt>

finstall internationalization
With finstall ver. 3.2 (all text output functions were put to their dedicated functions) it became "relatively" easy to translate the finstall screen output to other languages. Minimally the http://ra.vendomar.ee/~ivo/finstall.lang file should be translated to get the finstall to "communicate" in any new language, but there are also two template scripts for the same purpose: http://ra.vendomar.ee/~ivo/finstall.uk http://ra.vendomar.ee/~ivo/bfinstall.uk

If nothing more then I've made a Estonian translation: http://ra.vendomar.ee/~ivo/finstall.ee http://ra.vendomar.ee/~ivo/bfinstall.ee

Developers guide to finstall & folding scripts
Under this section I will try to explain the design and buildup of finstall and folding script so it should be possible to use functions of these in other scripts.

Easiest way to use finstall by "outside" scripts is to call it: <tt> </tt> and You'll get the finstall to install FAH client for You, but there is lot more what can be done with it...

The buildup of simplest external script should follow these steps:

1. Verify there is a finstall script around; <tt> </tt> 2. "Import" finstall; <tt> </tt> Note: The same "import" instructions will work with ./folding as well.

3. Redefine finstall functions and change parameters; <tt> </tt> 4. Verify the version of finstall; <tt> </tt> Note: My_version is the version of finstall You have verified to work with Your script.

5. Use finstall functions; <tt> </tt> There is a bfinstall script what is using the very same pattern to download and set up the FAH beta client.

bfinstall 2.9: <tt> </tt>

The actual finstall function arsenal is larger than just a FAH_Install and CheckArg used by bfinstall. These functions are mainly FAH_Install subfunctions, check the finstall script itself for detailed instructions.

Ubuntu
http://folding-community.org/viewtopic.php?p=143406#143406 By smoking2000:

With the first account created on my Kubuntu system and using the below procedure, works just fine. This account is in the admin group.

Installation Procedure:

<tt> </tt>

This works as expected, just like for the other Linux distros.

When you want to install the folding script as a service, usage of sudo is required. If the user running installService is not root, the command `su - -c "$(ServiceInstall)"` is not allowed. You'll be propted for a password, but whatever you enter will be invalid, because the password of the root user is disabled. (See `man sudo_root` on any Ubuntu system` or https://help.ubuntu.com/community/RootSudo) The correct way to use installService on Ubuntu systems is with sudo, like below.

Installation Procedure - Installing As Service:

<tt> </tt>

This works as expected. Because installService is run with root priviledges, the usage of su is allowed. The usage of sudo to run the init script could be skipped, because sudo caches the password for 15 minutes so subsequent invokations of sudo don't require you to re-enter your password each time.

When trying to use installService in one way or the other, under a useraccount which is not in the admin group, you can forget about installing as a service. Only the user himself can run the folding script in ~/foldingathome/, either by hand or through crontab.

Since finstall version 4.9, sudo is automatically envoked when it is run on an Ubuntu system. The above caveat with installService and its usage of su only applies to finstall versions before 4.9.