Package: GKrellFah2 Version 1.1.0-0 10/30/2005
GKRELLFAH2
A GKrellM Client/Server and Standalone plugin which allows you
to monitor and control Folding@Home clients on a remote or local machine. Derived
from the base gkrellfah2 package, this upgrade has been re-tooled to provide
a similar function using the gkrellmd client server model, as well as the original
standalone function. Adding Team Status, Workunit logging, CPU Utilization Controls.
When compiled the package produces five files;
* gkrellfah2C.so - The Client plugin for Gkrellm[D].
* gkrellfah2S.so - The Server plugin for GkrellmD.
* gkrellfah2.so - The Standalone plugin for Gkrellm.
* gfahLogview - The logviewer utility.
* gfahStats - The User/Team Statistics viewer utility.
* Note: They come pre-compiled for i686 machines, and the latest gkrellm[D]
gkrellfah2 monitors an active Folding@home linux client and collects
information regarding the progress, point value, molecule description, runtimes
and estimated runtime remaining, percentage of cpu utilization used, the dates
the work unit started or ended, and the machine calculation speed and rate.
gkrellfah2 also actively control the amount of CPU utilization an active
Folding@home linux client can use. Thereby limiting the heat produced by the CPU
and inversely the total time it takes to complete a unit of work. You can choose
from 10% to 100% as the value of cpu to use. This value stated differently "How
much of time to use of the time allocated!".
The rewrite drops support for dialup networking, and adds the ability
to capture key data points about completed work-units into a local logfile and
a central logfile. A logviewer has been added to the configuration panel and
mouse-button-2 as a popup; so you can see the log of all completed work from
your local and remote machines in one place.
syntax: gfahLogview [null] | -logfile rmt_filename | --help
syntax: gfahStats [null] | --dir /path/to/fah | --help
This file is also available via a manpage. '$ man gkrellfah2'
DESCRIPTION: General Usage
GKRELLM StandAlone and Client
Copy the pre-compiled plugins into the correct plugin dir for gkrellm or gkrellmd.
Via gkrellm's configuration panel, select the stand alone plugin gkrellfah2.so
titled "gkrellfah2.SA" on the config panel's "Plugins" list item. Then choose gkrellm's
Plugin list on the left and select this plugin's name again. This brings up its
configuration panel for the plugin itself. At a minimum set the number of
monitors/panels to start and the correct directory paths to those F@H clients represented
by monitors/panels.
Now stop gkrellm and restart it. You should find this plugin's panels located
near the CPU krells of gkrellm. Your now ready to use the plugin as the active
monitor for all Folding@home clients on your machine.
Note: I run two to three F@H clients on my dual processor machine. Which I have
installed into directories named "Grids_00" "Grids_01" "Grids_02", so you
will see that I choose 3 monitors - to represent the 3 F@H clients, and I
configured three directories as noted.
GKRELLMD
Via gkrellmd you run the server plugin (gkrellfah2S.so) on a remote
machine(or local). Via gkrellm you run the client plugin (gkrellfah2C.so) on your
local machine. The client has the normal GUI configuration panel with
some monitor settings you can change. However, the server is the work horse
without fancy GUI screens. Edit its configuration file to point to the correct
directories where F@H runs. Start GKrellmD on the remote machine, then go start a GKrellM
client and configure the client plugin. Wait up to 5 minutes for the client to get
populated with data from the server plugin.
FEATURES
This plugin features (see also 'Info' in plugin config.)
- Auto start F@H Clients from gkrellmd on IPL or gkrellmd startup.
- Auto start F@H Clients from gkrellm on startup of gkrellm.
- Auto RE-start F@H Clients if they end quick or fail.
- Client/Server model supports 1 local client per remote server.
- Maximum of eight panels/monitors per local client.
- Multiple local clients supported via Gkrellm
- Completed work log file viewer, as a popup window.
- Automatic download of Stanford point table.
- Displays F@H work unit values; Machine#, Project#, Protein Description,
Queue Version, FAHCore version, Benchmarks, Runtimes, ETA Times,
% Progress, % Cpu Utilization, Download, Start, End Dates,
Computational Rates and speed, Performance Fraction, and more...
USER INTERFACE...
Stand Alone plugin Only;
Mouse Button Actions:
(1)Left click
(2)Middle click
Starts the Control Panel.
(3)Right click
Opens GKrellFah2CS plugin config window.
No click, just mouse over
Pops up a message box showing FAH work status.
Client plugin Only;
Mouse Button Actions:
(1)Left click
Toggles the display or visibility of the cpu/progress krells
(2)Middle click
Completed work unit log file viewer - popup
(3)Right click
Opens GKrellFah2CS plugin config window.
No click, just mouse over
Pops up a message box showing FAH work status.
Configuration Panel - Setup Tab: - Stand Alone only...
Paths to Folding@home
Number of monitors to activate #
Select the number of F@H clients you plan to run on this machine.
Individual Paths
Full directory path to each F@H client. ex: /usr/local/Grids_00
Commands
Start command: The executable name of the F@H client. ex: ./FAH502-Linux.exe
Start arguments: Arguments to use when starting the F@H client.
Configuration Panel - Options Tab:
Running F@H
Start on Startup: Starts the F@H Clients when gkrellm starts
Restart if Fails: Restarts the F@H client if it fails...
Display format string
The text output is controlled by this string. You can put
anything you want here.
(default: "$n id#$i state$a $c $g $v $u $r eta:$e tm#$i").
(pango markup supported=yes; bold=..., italic=...)
$f "F@H"
$c is the wu codename (like TINKER, GROMACS)
$m is the current molecule
$s is the start time
$d is the due time if there is one
$g is the percent complete of the current work unit
$u is the average CPU utilization used by the work unit
$P is the pid of the parent F@H client.
$r is the current running time
$x is the current rate in points per hour
$e is the estimated time remaining on the current unit
$v is the point value of the current work unit
$n is the node name of the computer running this work
$i is the Folding@home machine id
$b is the computed fahcore benchmark
$t is the Folding@home Team number
$S is the monitors view of wu current state;
20-running when started, 21-normal,
10-starting, 12-finishing,
2-killed, 1-normal stop
Data update interval
Number of seconds to wait between F@H info updates
(default: 300)
Show cpu usage on panel
CPU usage will be display on a separate, smaller krell
CPU update interval
Seconds between krell updates for cpu usage.
Debugging Support:
Debug: Enable internal debugging message to console. (caution...)
Show_Sends: Shows startup config info and a few other items...
Configuration Panel - Server/Plugin Status Tab:
Displays the current configuration state of the gkrellm[d] based F@H work_units
Displays the current functioning state of all F@H clients (the main output)
Configuration Panel - Info Tab:
This text again...
Configuration Panel - Log Viewer Tab:
A window that lists the contents of the central completed work file,
Configuration Panel - About Tab:
Program version and copyright information.
REQUIREMENTS
* a Linux system with installed development environment. This
includes the GTK+-2.0 and the GkrellM2 developmental libraries.
* GKrellM multi-monitor app (http://gkrellm.net/). Version 2.2.5+
* Folding@home linux client (http://folding.stanford.edu/) version 5.0+
* A version of UNIX that supports the '/proc' filesystem. This program
collects all execution data by using features of the '/proc' filesystem.
INSTALLATION
INSTALLING FROM RPM
0. Get current binary rpm
1. switch user id to root, for installation
2. from a command line issue the following command
"$ rpm -ivh gkrellfah2-1.x.x-x.rpm "
or if upgrading do
"$ rpm -Uvh gkrellfah2-1.x.x-x.rpm "
3. switch back to your regular userid
4. Done...
INSTALL FROM SOURCE
Overview of steps needed...
0. Copy 'gfahLogview' to a directory in your path.
1. Compile the plugins
2. Edit the gkrellmd.conf file for this plugin
3. Start gkrellmd in local mode to test its function.
4. Workout any file permission issues for running gkrellmd as a system
service. (i.e. set FAH dir files to SUID)
------------------------------------------------------------------------------------
NOTE ** If you don't see the data being updated in the client program, you may need
to assign permissions to the Folding@home directory for gkrellmd. The commands
to considered are: Ownership -- or -- StickyBit
'[root@localhost] $ chown -R gkrellmd:gkrellmd /fah_directory/*'
'[root@localhost] $ chmod -R u+s /fah_directory/*' <-- try this one first
------------------------------------------------------------------------------------
NOTE ** You WILL need to be root to install this package.
The plugins come pre-compiled and ready to use. 'make install' will
put them in the right place.
You may want to change or remove the -march=i686 flag in the makefile first.
look for the 'FLAGS' param at the top of the make file.
1. Compile the plugins: (as a regular user)
$ tar jxvf gkrellfah2-x.x.x.tar.bz2
$ cd gkrellfahCS
$ make help
$ make clean all install
or try...
$ make clean all
$ sudo make install
The Makefile installs;
gkrellfah2C.so in /usr/local/lib/gkrellm2/plugins
gkrellfah2.so in /usr/local/lib/gkrellm2/plugins
* or the alternate ~/.gkrellm2/plugins
gkrellfah2S.so in /usr/local/lib/gkrellm2/plugins-gkrellmd
* or the alternate ~/.gkrellm2/plugins-gkrellmd
Edit the makefile if you want to use the alternate paths:
look for CLI_PLUG_DIR or SVR_PLUG_DIR near the top of the makefile
2. Configure the plugin: Client/Server Versions Only
NOTE: For the standalone version, your done install just
start gkrellm and select the new plugin...
Add the following (edited) lines to your gkrellmd config file.
filename: /etc/gkrellmd.conf
-- or alternate filename: /usr/local/etc/gkrellmd.conf
edit the path_string and start_cmd as needed.
...
plugin-enable gkrellfah2S.so
[gfah2CS]
update_timer 300
pcpu_timer 10
mp_count 1
auto_start 0
auto_restart 0
ignore_cfg_error 1
path_string /usr/local/Grids_00
start_cmd ./FAH502-Linux.exe
start_arg -advmethods
idebug 0
show_sends 0
fahlimit_percent 100
[/gfah2CS]
3. Start gkrellmd in local mode to test its function.
GKRELLM in client mode: see '$ man gkrellm ', if you need more info
A. local mode
$ gkrellm -s localhost
B. Normal (remote server) mode
$ gkrellm -s remote.ip.address
C. For local trouble shooting mode: echos all received traffic
to the console (look for gfah2CS marker).
$ gkrellm -s localhost -d 0x1000
GKRELLMD in server mode: see '$ man gkrellmd ', if you need more info
A. local mode
$ gkrellmd -plog
B. Normal (remote server) mode
$ gkrellmd
or via normal services function.
C. For local trouble shooting mode: echos all sent traffic
to the console.
** Edit gkrelld.conf to change 'show_sends' to 1
this causes the gkrellfah2S.so plugin to echo every send data to
the console; it also forces the gkrellfah2C.so client to echo
received data to the console.
** Start them both in normal local mode, and wait/watch at least 2 minutes.
$ gkrellmd -p gkrellfah2S.so -plog
$ gkrellm -p gkrellfah2C.so -s localhost
4. Trouble shooting.
A. Before digging into the code to find a bug... run both programs in local mode.
any error they encounter will be output the console. The most likely reason
for the plugins to not perform as designed is file permissions.
B. With two exceptions, all files are accessed in read-only mode and should be
accessible to the program.
The three exception are:
1. The points table 'psummary.html' download to FAH directory
via this command 'wget -N http://vspx27.stanford.edu/psummary.html'
2. The completed work file 'gfah2CS.log' written to the same FAH directory.
3. The central completed work file 'gfah2CS-central.log' written to your HOME directory.
C. Write permission to the FAH directory(s) is required by the
gkrellmd effective user_id or group_id. Again the plugins complain to
the console with the exact filenames they have issues with. The impact
of not having these permissions correct is, the displayed point value is zero
and the completed work log is always empty.
** the default user/group of gkrellmd is 'gkrellmd/gkrellmd'
D. Most of the system values, like cpu time used and finding the right proc-ids,
involve reading the contents of various '/proc/pid#/status' files. Its rare
that there is a permission problem encountered accessing these system files.
If you know the FAH502-Linux.exe and FahCore_78.exe are running, via a
'$ps -ef | grep -e FAH -e Fah' command. Then the most likely cause is how
you started the FAH programs. The FULL DIRECTORY PATH must be used if you
start these things any other way (than letting gfah2CS start them).
Example: '/usr/local/Grids_00/FAH502-Linux.exe -advmethods'.
Since FAH creates multiple executables during it normal running cycle, these
plugins determine who's who by comparing the started paths to the configured
paths - to know which group of pids belong together.
E. Lastly, built into each plugin is a debug switch. the gkrellmd module gkrellfah2S.so
gets it debug flag from the gkrellmd.conf setting of 'idebug 1'. The gkrellm module
gets its debug flag from the command line 'gkrellm -s localhost -debug97' where 97
is the number its looking for. The client and standalone plugins have a configuration
panel checkbox that can toggle this feature on and off.
When in debug mode, each internal routine will output the fact that it was entered
or exited, and several of its key control values. This is a ton of output - but its
also the quickest way for me to help find and fix your problem - WHICH I WILL DO if
you tell me you have an issue.
** Note: Normally these plugin will not even start if they are not configured correctly or
started in stand-alone mode( without '-s hostname'). But they do send console
messages.
BUGS
I freely admit that I may have made mistakes and bad assumptions, so if you have
any suggestions, clarifications, or need some additional info feel free to contact
me at the email address given below.
The core function of monitoring the F@H execution directory causes its own problems,
without the burden of client/server adding to it. Most of the issues encountered will
relate to having the right file permissions. Without debugging turned on via the
config, the plugin will output to the console any serious file access errors it
encounters. So running from a console window is suggested if you have any
trouble - error messages will likely guide your next step.
SERVER CONFIGURATION INFO:
Plugin Configuration Description: Client/Server Versions Only
filename: /usr/local/etc/gkrellmd.conf
'plugin-enable gkrellfah2S.so'
Tells gkrellmd which plugin to enable. Gkrellmd assumes
the plugin is located in the
"/usr/local/lib/gkrellm2/plugins-gkrellmd" directory.
[gfah2CS]
TOP OF CONFIG SECTION ( DO NOT CHANGE THESE KEYS )
This key marks the START of our config.
start_cmd ./FAH502-Linux.exe
Name of the current FAH client executable
start_args -advmethods
Command line arguments for FAH client executable
mp_count [1-8]
Number of FAH Monitor Panels to create and watch
path_string ex:/usr/local/Grids_00
filepath to FAH work directory
path_string
filepath to FAH work directory for n monitors...
n monitor path, maximum repeat of 7 times allowed
auto_start : [0|1]
Automatically start Fah Client if qwork.istate = 0, on startup
auto_restart : [0|1]
Automatically Restart Fah Client if qwork.istate = 2 (cancelled)
pcpu_timer : [10]
Percent CPU interval defaults to 10 seconds
update_timer : [300]
Full update interval defaults to 5 minutes
idebug : [0|1]
Causes server to output formatted debugging info (helpful to me)
show_sends : [0|1]
Send transmitted output to local console (at both ends)
fahlimit_percent : 10 - 100
Amount of allocated time for F@H clients to use.
[/gfah2CS]
BOTTOM OF CONFIG SECTION ( DO NOT CHANGE THESE KEYS )
This key marks the END of our config format [/xx],
where xx=STYLE_NAME, and COMM_KEY to gkrellmd
example config section...
...
plugin-enable gkrellfah2S.so
[gfah2CS]
update_timer 300
pcpu_timer 10
mp_count 2
auto_start 0
auto_restart 0
ignore_cfg_error 1
path_string /usr/local/Grids_00
path_string /usr/local/Grids_01
start_cmd ./FAH502-Linux.exe
start_arg -advmethods
idebug 0
show_sends 0
fahlimit_percent 100
[/gfah2CS]
...
EXAMPLE OUTPUT: ALL :from tool_tips(i.e. mouse over), or config panel
-----------------------------------------------
Server Configuration Settings
-----------------------------------------------
skoona.scottfamily.net
2
10
300
0
0
1
./FAH502-Linux.exe
-advmethods -oneunit
0
0
/usr/local/Grids_00
/usr/local/Grids_01
100%
-----------------------------------------------
Active Monitor [0]
-----------------------------------------------
skoona.scottfamily.net
gkrellfah2-1.0.3
0
/usr/local/Grids_00
jscott15
1
237
37988
5
881
0.934251 avg of 4 units.
23573
724
Folding@Home
p724_Abeta21-43-amberGS
GROMACS
78
Sun Jan 30 10:30:45 2005
Sun Jan 30 10:30:54 2005
Sat Feb 12 10:30:54 2005