FAH Monitor Help Page

FAH Monitor Help

Introduction
- How It Works
- Security
Getting Started
Operations
Troubleshooting

Introduction

How It Works

The FAH Monitor (name not trademarked, and probably temporary) is designed to give a quick snapshot view of all machines currently folding for a given user. It will show the user the progress of each machine along a given project, and indicate if problems are being encountered. It will also give a rough estimate of when the project will be completed.
The monitor consists of three parts:

Upload script    This is the only portion that resides on the user machine. It is a VisualBasic Script (.VBS file) that is scheduled to be run periodically to send folding status information to the monitor server.

Upload Page    This page is called in the background by the upload script and receives the status information. That information is placed in a database for use by the monitor page.

Monitor Page    This is the page that the user browses to that allows the machines to be viewed. Here is my page as an example.

The FAH Monitor assumes that you have Folding@Home running successfully (either the GUI or the console) and that a permanent connection exists between the folding machine and the internet.

Security

I've designed the monitor system in such a way that there is absolutely no recognizable data collected from the uploading machine at all. I'm not recording IP addresses. User identification is limited to your FAH handle and, optionally, your EOC number. Machine names need not have any basis in reality aside from what you deem suitable for unique identification. You can view the raw data feed here. (Well, almost raw-- it's formatted into my standard logging structure, and doesn't include the snapshots I take of you in your underwear through your webcam.)
I'm using a cookie in the Help Page to remember whether you were viewing the Linux flavored or Windows flavored version. Additionally, I'm considering using a cookie to keep track of expanded/collapsed section views on the user page, but that hasn't been implemented yet. The Help page will function even if you are disallowing cookies, and the monitor will be written to function without cookie support as well.

Getting Started

Step 1: Download the Script

The first thing you need to do is to download the correct script for your operating system...

Operating System Script Comments
Windows (9x/NT/2000/XP/2003) FAHUpload-Win.zip version 1.6
Linux FAHUpload-Lnx.zip version 1.6
Mac Use Linux version The Linux version and the associated help here will work for Mac
PlayStation Not available Don't own one, and not sure how I'd get the script on there

Extract the small script and place it in any convenient folder (Linux may require a designated folder). As with any script or application you download, it is advisable to look through the script and get an understanding of what it's doing. I've commented the script reasonably well, and it should be apparent to even novice users what information is actually being gathered and sent.

Operating System	Script	Comments
Windows (9x/NT/2000/XP/2003)	FAHUpload-Win.zip	version 1.6
Linux	FAHUpload-Lnx.zip	version 1.6
Mac	Use Linux version	The Linux version and the associated help here will work for Mac
PlayStation	Not available	Don't own one, and not sure how I'd get the script on there

Step 2: Edit the script

Displaying the Windows version. (Display Linux version)

The script is set up so that only minor editing need take place. The first section of the script contains a set of user constants. These need to be modified to personalize the data to your user information. If you are planning to deploy this script on several folding machines, I'd advise that you set your personal information in one first, and use that one as a template to propogate to your other machines, only needing to change specific machine information after that.
The script file is in ASCII format, and can be opened with any text editor. Other than the user constants section below, please refrain from changing any other sections of the script unless you're dang sure of what you are doing!
The section in question looks like this (in the Windows version):
   'user constants (CHANGE THESE TO MATCH YOUR CONFIGURATION)
    Const m_szUSER_NAME                = "UserName"  ' your user name registered to F@H
    Const m_szUSER_TEAM                = "36120"     ' your team number
    Const m_szUSER_PASSWORD            = ""          ' your user password
    Const m_szUSER_EOC_NUMBER          = "172805"    ' your ExtremeOverclock.com user ID (optional)
    Const m_szUSER_MACHINE             = "Test1"     ' unique name for this machine    Const m_szUSER_MACHINE_LINK        = ""          ' link to machine Log file (optional)
    Const m_szUSER_MACHINE_SECTION     = ""          ' grouping for this machine (optional)
    Const m_szUSER_MACHINE_RAM         = ""          ' amount of ram available (optional)
    Const m_szUSER_MACHINE_PROC        = ""          ' processor information (optional)
    Const m_szUSER_MACHINE_NOTES       = ""          ' machine notes (optional)
    Const m_iUSER_TIME_ADJUST          = -6          ' number of hours to adjust from Zulu time (for user)
    Const m_iUSER_TIME_ADJUST_SERVER   = -6          ' number of hours to adjust from Zulu time (for this server)
    Const m_iUSER_TIME_UPLOAD          = 30          ' number of minutes between uploads (should match your task scheduler)    
    Const m_iUSER_TIME_MISSED          = 2           ' allowed number of missed uploads before showing yellow
    Const m_iUSER_TIME_STEPS           = 180         ' number of minutes allowed on the log file before showing red
    Const m_szUSER_PATH_SOURCE         = "C:\Program Files\Folding@Home\unitinfo.txt"  ' location of your FAH unitinfo.txt file
Although they are relatively self-explanatory, a description of the constants follows:
USER_NAME This is your Folding@Home user name. This should be the same for all machines you have folding.

USER_TEAM This is the team ID for Folding@Home. In the case of Freepers, it should be 36120.

USER_EOC_NUMBER This is your ExtremeOverclocking.com user ID (numeric 6-digit). This is used to generate the EOC user status block at the top of the page, and as a link to your EOC page. This is an optional parameter.

USER_MACHINE This is the unique name of your machine. As well as being the display name for each machine you are tracking, it is also used by the monitor to upload data for that specific machine. If you change this name after running the script the first time, you will end up with two machine entries (for awhile): one for the old and one for the new.

USER_PASSWORD This is your user password. If used, this will need to be the same (case sensitive) password for all your machines. This is an optional parameter-- but once invoked, it needs to be identical for all machines.

USER_MACHINE_LINK This is a URL that will be displayed if the machine name is clicked on. I expose my folding log file via HTTP, and therefore use this link field to allow me to browse to that log. This is an optional parameter.

USER_MACHINE_SECTION For users with a lot of machines to track, this is a way to organize them into groups. The display will be sorted by group, and then by machine name within the group. This is optional, leaving the group blank will keep all machines displayed together.

USER_MACHINE_RAM The amount of RAM the machine has available to folding goes here. This is to help in performance comparisons between machines. This is strictly anecdotal in nature, and optional.

USER_MACHINE_PROCESSOR Processor speed and type information goes here. This is to help in performance comparisons between machines. This is strictly anecdotal in nature, and optional.

USER_MACHINE_NOTES Additional information about the machine goes here. This could include how much uninterrupted folding time this machine has, etc. It's used for explaining less-than-expected performance in a machine that would otherwise compare more favorable against machines in its class. This is strictly anecdotal in nature, and optional.

USER_TIME_ADJUST This is your offset from zulu time (Greenwich Mean Time). This value is used to convert all times into your local setting. (Just a note: when/if other people look at your page, they will see the times in your timezone.

USER_TIME_ADJUST_SERVER This is your machine's offset from zulu time (Greenwich Mean Time). The project begin date and date due are stored in this time frame. In order to do calculations, I convert all other relevant times (file time, upload time) to zulu time as well for later calculations. I keep this separately for each machine because some people have commandeered machines that aren't necessarily in their timezone.

USER_TIME_UPLOAD This is the number of minutes between uploads. This value should be set to match the task scheduler setting you will set up in Step 3. PLEASE, avoid anything more often than 15 minutes! I have no idea how many people are going to use this script and, besides, you know how slow these processes fold anyway!

USER_TIME_MISSED This is the number of times a scheduled upload can be missed before you're notified that communication has been lost. Basically, if the USER_TIME_UPLOAD is 30, and the USER_TIME_MISSED is 2, you'll have about 60 minutes leeway before the machine is flagged in yellow.

USER_TIME_STEPS This is the number of minutes old that the unitinfo.txt file is allowed to be, before you're notified that Folding@Home is likely hung.

USER_PATH_SOURCE This is the path to the physical file containing the status data. It is generally (probably always) in the unitinfo.txt file in the Folding@Home application folder. Note: This isn't just the path to the file, but the actual path with the file name included.
After you've edited the script, it's a good idea to test it. To do this, double-click on the script (in File Explorer). This will execute the script. At this point, your Windows Firewall will pop up a confirmation window prompting you for permission to allow the script to send data out through the internet. You'll want to click OK-- otherwise, this entire process is pretty much moot!
There will be no feedback-- unless you've made a mistake and accidentally left off a quote or something. Go to the monitor page and see if your user name is listed, and your machine shows up on your page.

Step 3: Schedule the script

Displaying the Windows version. (Display Linux version)

Under Start / Settings / Control Panel, bring up Scheduled Tasks.
Choose Add Scheduled Task
Choose the Next button, and wait for the system to populate the list of applications, none of which you are interested in.
Choose the Browse button, and find the location of your edited FAHUpload.vbs file. Click Open once you've selected the file.
Name the task- the default is the file name of the task. If you're running multiple copies of the upload script file (for a multi-processor machine, for instance) you'll want to pick unique names for each task. Choose the Daily option, when prompted how often you want the script to run, and choose Next.
Enter a time to start the task. Please consider leaving this time as the time that it defaults to (the current time). In this way, my server will be hit on a relatively random basis-- as opposed to everyone setting their task to kick off at the top of the hour. Once you're done, click Next.
If prompted, enter your user information for your machine that will give you the permissions necessary to kick off the task. Click Next to continue.
Check the Open Advanced Properties option, and click Finish.
On the Schedule tab, click the Advanced button.
Check the Repeat Task option, set the time that you want the task completed. Please refrain from updating more often than every 15 minutes. In the Until section, use the Time option, and enter 5 minutes prior to the scheduled start time of the task. This will ensure that the task is repeated slightly under 24 hours in duration-- and then the next scheduled kick off will occur. Also check the Stop task if it's still running option. Click OK when you're finished.
On the Settings tab, change the Stop the task if it's been running time limit to 5 minutes. Any other settings on this tab are at your discretion. Click OK when finished.
At this point, it would probably be a good idea to manually kick off the process (by right-clicking the task, and choosing Run) just to make sure that it works.
You're done! Your machine should have registered itself with the FAH Monitor, and you can simply bring up the FAH Monitor and click on your user name. Happy monitoring!

Operations

The User Page

The user screen of the FAH Monitor displays the current progress of multiple machines. Machines can be split into Sections, allowing users with a multitude of machines to separate them into logical groups for organizational purposes.
The progress of each machine toward its current project is uploaded periodically from the unitinfo.txt file. The following pieces of data are tracked and displayed:

Server This is the unique name of the machine. Under normal conditions, it is displayed black on white. Certain conditions, however, will cause the machine name to be highlighted. The background color schema is as follows:

    Machine appears to have stopped folding
    Machine hasn't transmitted an update in awhile
    Script is out of date

Everything's great!

Progress Progress is displayed directly from the unitinfo.txt file as a percentage of 100.

Date Started This is the date that the status file reports the current project was downloaded, and work was begun.

Minutes This is a simple difference in minutes between the current time and the date the project was started.

Estimated Completion    I'm still refining this algorithm. Currently it's simply a matter of taking the percentage complete, figuring out based on the elapsed time how long it took to complete each percentage, and projecting that onto the remaining percentage to be complete. While simple, there are downsides to this approach. First, the completion time tends to move further out as time elapses with no progress reported, and contracts back as soon as progress is reported. Second, it doesn't take into account either slow-downs of the folding process, or complete stops (especially in the case of laptops). I'm working on an alternative method of figuring out estimated completion.
Normally, this field will be bolded-black on a white background. However, if the current project has a due date, and it has passed or is in danger of passing, the following background color schema will be used:

    Deadline for this project has already passed.
    Estimated completion goes past the due date

Everything's great!

Current Project This is the current project, as reported by the status file. You may notice that when a project has first begun, this name may be incomplete. This is a "feature" with the Folding@Home process, not a problem with the FAH Monitor.

Adding a Machine

A machine is added simply by running the upload script for the first time on a uniquely named machine. Thereafter, machine information is simply updated any time that script is edited. The exceptions to this are the identification fields (team number, user name, machine name). If these are edited, it will look to FAH Monitor as a new machine and, therefore, a new database entry will be started. After a week of no updates, the old machine will be removed from the database.

Removing a Machine

Machines are automatically removed after a week of no updates. Likewise, a user with no machines will be removed. If a machine or a user absolutely has to be removed prior to this, Freepmail me.

Troubleshooting

I'll be adding to this section as we start experiencing problems. ...not that it's a foregone conclusion... oh, never mind.

Symptom Possible Cause
Dates are incorrect, and the estimated completion date is WAY off. - or - machine stays red, even though the progress seems to be reporting correctly. It's likely that your USER_TIME_ADJUST_SERVER, and possibly your USER_TIME_ADJUST, settings are off. By default, the script is set to -6 (CST, six hours back from GMT). You'll need to change this to match your timezone. All date values are converted to GMT based on this setting, are operated on in GMT, and only converted back to your user time zone for display purposes.
Another thing to check: Make sure that your system clock is set correctly (time and date).

The estimated completion date always ends up being off by as much as an hour when the project finishes. Yeah, that's because my algorithm sucks. I'm working on the idea of a moving average based on the time it takes to see progress gains, but I'm far from figuring out the logistics. Bear with me.

I've scheduled the task, but my user name/machine isn't showing up It could be that the Windows Firewall isn't allowing the script to execute. Try finding the script in File Explorer, and double-clicking it. If Windows Firewall pops up a confirmation box asking you for permission for the script to send out data, you've probably found the problem. Click OK, and your scheduler will probably work from this point forward.
Another thing we've discovered: in order to successfully execute the script from Windows Scheduler, there needs to be a user account set up for the machine, complete with a password. That user account needs to have sufficient privileges to run scripts (i.e. administrator rights).
If these weren't your issues, bring back up the scheduler, and look at the return code from the last run. It should be 0x0. Try right-clicking on the task, and choosing Run. If this still doesn't work, Freepmail me, and we'll debug it further.

Last updated: 4 January 2008

Upload script	This is the only portion that resides on the user machine. It is a VisualBasic Script (.VBS file) that is scheduled to be run periodically to send folding status information to the monitor server.

Upload Page	This page is called in the background by the upload script and receives the status information. That information is placed in a database for use by the monitor page.

Monitor Page	This is the page that the user browses to that allows the machines to be viewed. Here is my page as an example.

USER_NAME	This is your Folding@Home user name. This should be the same for all machines you have folding.

USER_TEAM	This is the team ID for Folding@Home. In the case of Freepers, it should be 36120.

USER_EOC_NUMBER	This is your ExtremeOverclocking.com user ID (numeric 6-digit). This is used to generate the EOC user status block at the top of the page, and as a link to your EOC page. This is an optional parameter.

USER_MACHINE	This is the unique name of your machine. As well as being the display name for each machine you are tracking, it is also used by the monitor to upload data for that specific machine. If you change this name after running the script the first time, you will end up with two machine entries (for awhile): one for the old and one for the new.

USER_PASSWORD	This is your user password. If used, this will need to be the same (case sensitive) password for all your machines. This is an optional parameter-- but once invoked, it needs to be identical for all machines.

USER_MACHINE_LINK	This is a URL that will be displayed if the machine name is clicked on. I expose my folding log file via HTTP, and therefore use this link field to allow me to browse to that log. This is an optional parameter.

USER_MACHINE_SECTION	For users with a lot of machines to track, this is a way to organize them into groups. The display will be sorted by group, and then by machine name within the group. This is optional, leaving the group blank will keep all machines displayed together.

USER_MACHINE_RAM	The amount of RAM the machine has available to folding goes here. This is to help in performance comparisons between machines. This is strictly anecdotal in nature, and optional.

USER_MACHINE_PROCESSOR	Processor speed and type information goes here. This is to help in performance comparisons between machines. This is strictly anecdotal in nature, and optional.

USER_MACHINE_NOTES	Additional information about the machine goes here. This could include how much uninterrupted folding time this machine has, etc. It's used for explaining less-than-expected performance in a machine that would otherwise compare more favorable against machines in its class. This is strictly anecdotal in nature, and optional.

USER_TIME_ADJUST	This is your offset from zulu time (Greenwich Mean Time). This value is used to convert all times into your local setting. (Just a note: when/if other people look at your page, they will see the times in your timezone.

USER_TIME_ADJUST_SERVER	This is your machine's offset from zulu time (Greenwich Mean Time). The project begin date and date due are stored in this time frame. In order to do calculations, I convert all other relevant times (file time, upload time) to zulu time as well for later calculations. I keep this separately for each machine because some people have commandeered machines that aren't necessarily in their timezone.

USER_TIME_UPLOAD	This is the number of minutes between uploads. This value should be set to match the task scheduler setting you will set up in Step 3. PLEASE, avoid anything more often than 15 minutes! I have no idea how many people are going to use this script and, besides, you know how slow these processes fold anyway!

USER_TIME_MISSED	This is the number of times a scheduled upload can be missed before you're notified that communication has been lost. Basically, if the USER_TIME_UPLOAD is 30, and the USER_TIME_MISSED is 2, you'll have about 60 minutes leeway before the machine is flagged in yellow.

USER_TIME_STEPS	This is the number of minutes old that the unitinfo.txt file is allowed to be, before you're notified that Folding@Home is likely hung.

USER_PATH_SOURCE	This is the path to the physical file containing the status data. It is generally (probably always) in the unitinfo.txt file in the Folding@Home application folder. Note: This isn't just the path to the file, but the actual path with the file name included.

Symptom		Possible Cause
Dates are incorrect, and the estimated completion date is WAY off. - or - machine stays red, even though the progress seems to be reporting correctly.		It's likely that your USER_TIME_ADJUST_SERVER, and possibly your USER_TIME_ADJUST, settings are off. By default, the script is set to -6 (CST, six hours back from GMT). You'll need to change this to match your timezone. All date values are converted to GMT based on this setting, are operated on in GMT, and only converted back to your user time zone for display purposes. Another thing to check: Make sure that your system clock is set correctly (time and date).

The estimated completion date always ends up being off by as much as an hour when the project finishes.		Yeah, that's because my algorithm sucks. I'm working on the idea of a moving average based on the time it takes to see progress gains, but I'm far from figuring out the logistics. Bear with me.

I've scheduled the task, but my user name/machine isn't showing up		It could be that the Windows Firewall isn't allowing the script to execute. Try finding the script in File Explorer, and double-clicking it. If Windows Firewall pops up a confirmation box asking you for permission for the script to send out data, you've probably found the problem. Click OK, and your scheduler will probably work from this point forward. Another thing we've discovered: in order to successfully execute the script from Windows Scheduler, there needs to be a user account set up for the machine, complete with a password. That user account needs to have sufficient privileges to run scripts (i.e. administrator rights). If these weren't your issues, bring back up the scheduler, and look at the return code from the last run. It should be 0x0. Try right-clicking on the task, and choosing Run. If this still doesn't work, Freepmail me, and we'll debug it further.