Folding@Home Linux server installation (64bit Debian/Ubuntu)

01_install.md

Quick install of FAHClient for 64bit Debian/Ubuntu servers

1. Download the installer

Pick a version:

v7.5 (latest when this guide was written):

$ wget -P /tmp/fahclient/ https://download.foldingathome.org/releases/public/release/fahclient/debian-stable-64bit/v7.5/latest.deb

v7.6 (more recent and might still work with this guide):

$ wget -P /tmp/fahclient/ https://download.foldingathome.org/releases/public/release/fahclient/debian-stable-64bit/v7.6/latest.deb

2. Install the .deb

$ sudo apt install /tmp/fahclient/latest.deb

If you dont have apt you can try:

$ sudo dpkg -i /tmp/fahclient/latest.deb \
&& sudo apt-get install -f

3. Follow the intstructions in the terminal

The installer will prompt you for username, team id, passkey and similar settings. You can generate a passkey here.

If you want to run FAHClient as a service make sure to use the default setting when propted about running it automatically.

And you are done! FAHClient should now be up and running successfully! :)

Troubleshooting

Note: This was written for v7.5, but may still be relevant for later versions.

Service fails with "(error_code)" instantly after install

I've dug around forums and done some investigating of my own and came to this conclusion:

The included init.d script doesn't seem to fare so well on newer systemd systems and sometimes incorrectly states that it failed starting the service. Run sudo /etc/init.d FAHClient status or ps aux | grep FAHClient to double check if the start-up in fact has failed.

If the service is running distpite the init.d script outputted a failure

Feel free to ignore this error as it's due to a falty check in the init.d script and has nothing to do with the health of the actual FAHClient process.

If it still annoys you feel free to check out my steps below that will fix the fault in the init.d script and turn it into a proper systemd service.

If the service actually failed to start

There could be an issue with your config. There's a few steps you can take in order to attempt a fix:

1. Start the service with verbose output:

$ sudo /etc/init.d/FAHClient -v start

In most cases you will have an output at the very start of the log explaining any incorrect config settings.

2. Compare the config in /etc/fahclient/ to the generated backups in /var/lib/fahclient/configs/

Sometimes the config in /etc/fahclient/ seems to get corrupted after initial install (happened to me).

To fix this you should copy one of the configs from /var/lib/fahclient/configs/ and replace the one in /etc/fahclient/.

It might be a good idea to do a backup copy of the initial config.xml in case you want to merge some of it's settings with the generated backup config you're replacing it with.

Read further in this forum thread: https://foldingforum.org/viewtopic.php?f=96&t=30427

3. Purge and start over

Sometimes reinstalling may solve the issue.

$ sudo apt purge fahclient

Then follow the install steps again.

Read further in this forum thread: https://foldingforum.org/viewtopic.php?f=96&t=30427

I'm not happy about how much of my cores FAHClient is using

The default settings was using a tad to much of my server's capabilities than I initually liked. I thought I'd share the changes I applied in case someone would like to use them themselves.

My server is an 8-core, GPU-less little thing meant for developing web applications (and my cooling is set up thereafter) and I noticed the default settings left my rig a tad overheated. At the default setting of a folding power of "medium", FAHClient was using 7/8 of my cores at 100%. Needless to say, I wanted to throttle this a bit. These are the settings I ended up using:

<power v='LIGHT' />
<cpu-usage v='50'/>

This far it seems like these changes are sufficient for my rig to stay at a level I'm confortable with. :)

02_enable-remote-access.md

[OPTIONAL] Enable remote access from your local network

1. [OPTIONAL] Do a backup of your current config

$ sudo cp /etc/fahclient/config.xml /etc/fahclient/config.xml.bak

2. Update your config to allow remote access

Then use your favorite editor to open /etc/fahclient/config.xml and add these lines just above the closing </config> tag.

  <!-- Remote Access -->
  <allow>127.0.0.1 192.168.0.0/24</allow>
  <web-allow>127.0.0.1 192.168.0.0/24</web-allow>
  <password>PASS</password>

Replace '192.168.0.0/24' if necessary with the accurate address and subnet your local network. Or, if you prefer, with the specific machine you want to add access to.

And don't forget to change "PASS" to the actual password you want to use (if any).

Remember to open port 7396 (for the web view) and 36330 (for FAHControl) in your firewall if needed.

3. Restart the service(?)

TBH I'm not sure if FAHCLient reloads the config automatically when we manually edit the file, so let's restart our client just to be sure:

$ sudo /etc/init.d/FAHClient restart

Or, if you've converted it to a systemd service:

$ sudo service fahclient restart

4. Access your server through your browser or FAHControl

You should now be able to visit http://your-server-ip:7396 in order to look at your FAHClient web interface or add your server as a client in FAHControl.

03_convert-to-systemd-service.md

[OPTIONAL] Convert init.d script to a systemd service.

Based on: http://pedroivanlopez.com/install-fahclient-linux-systemd-service-unit/

1. Stop init.d script

$ sudo /etc/init.d/FAHClient stop

2. Either move the existing script or download my modified version

The difference between option 1 and 2 is currently purely cosmetic. Systemd will still recognize the FAHClient process' actual status regardless if the service init script log exited with "FAIL" or "OK".

What my version (option 2) does is to add an extra step to check if the process in fact failed to start to avoid the false positives.

[OPTION 1] Use existing script:

(Note: I'm renaming the script to FAHDaemon so it won't override the original FAHClient bin in PATH)

$ sudo mv /etc/init.d/FAHClient /usr/local/bin/FAHDaemon

[OPTION 2] Download and use my modified version:

(The file is included in this gist so feel free to read it through and compare it with the original)

$ sudo mkdir /var/lib/fahclient/old-service && mv /etc/init.d/FAHClient /var/lib/fahclient/old-service \
&& wget -P /tmp/fahdaemon/ https://gist.githubusercontent.com/vonEdfa/27c68018dad5a6ba4acc40b81dabd805/raw/FAHDaemon \
&& sudo cp /tmp/fahdaemon/FAHDaemon /etc/local/bin/FAHDaemon \
&& sudo chown root:root /etc/local/bin/FAHDaemon \
&& sudo chmod +x /etc/local/bin/FAHDaemon

3. Download and set up the systemd service

Note: The service file included here is a copy of Systemd service unit for FAHClient // Folding@Home Client, so the credit goes to lopezpdvn. I have simply changed the name of the service executeable to fit my modifications.

$ wget -P /tmp/fahclient-service/ https://gist.githubusercontent.com/vonEdfa/27c68018dad5a6ba4acc40b81dabd805/raw/fahclient.service \
&& sudo mv /tmp/fahclient-service/fahclient.service /etc/systemd/system/fahclient.service \
&& sudo chmod root:root /etc/systemd/system/fahclient.service \
&& sudo chmod u=rw,go=r /etc/systemd/system/fahclient.service

4. Reload systemd

$ sudo systemctl daemon-reload

5. Start service

$ sudo service fahclient start

You should now be able to manage the FAHClient service through systemd. :)

fahclient.service

# Credit: https://gist.github.com/lopezpdvn/81c8bb867c51292045c6#file-fahclient-service

[Unit]
Description=Folding@Home V7 Client
Documentation=https://folding.stanford.edu/home/the-software/

[Service]
Type=simple
PIDFile=/var/run/fahclient.pid
ExecStart=/usr/local/bin/FAHDaemon -v start
ExecReload=/usr/local/bin/FAHDaemon -v restart
ExecStop=/usr/local/bin/FAHDaemon -v stop
KillMode=process

[Install]
WantedBy=multi-user.target

FAHDaemon

#!/bin/bash
# chkconfig: 2345 95 20
# description: Folding@home Client
# Starts FAHClient
# processname: FAHClient

### BEGIN INIT INFO
# Provides:          FAHClient
# Required-Start:    $remote_fs $syslog $network
# Required-Stop:     $remote_fs $syslog $network
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Folding@home Client
# Description:       Start and stop Folding@home Client daemon
### END INIT INFO

USER=fahclient
NAME=fahclient
CONFIG=/etc/$NAME/config.xml
DEFAULT=/etc/default/$NAME
HOME=/var/lib/$NAME
EXEC=/usr/bin/FAHClient
LOG=$HOME/log.txt
PID=/var/run/$NAME.pid
EXTRA_OPTS=
QUIET=true
ENABLE=true


if [ -s $DEFAULT ]; then
    . $DEFAULT

    case "x$ENABLE" in
        xtrue|xfalse) ;;
        *)
            echo "Value of ENABLE in $DEFAULT must be either 'true' or 'false';"
            echo "not starting FAHClient."
            ENABLE=false
            ;;
    esac
fi


get_pid() {
    cat $PID
}


is_running() {
    if [ -e $PID ]; then
        ps -hp $(get_pid) 2>/dev/null >/dev/null
        return $?
    else
        return 1
    fi
}


log_status() {
    stat -c "%X" $LOG 2>/dev/null
}


wait_for_log_change() {
    if [ "$2" != "" ]; then
        pid=$2
    else
        pid=$(get_pid)
    fi

    while [ "$(log_status)" == "$1" ]; do
        if ps -hp $pid 2>/dev/null >/dev/null; then
            sleep 1
        elif [ -e $PID ]; then
            if ps -hp $(get_pid) 2>/dev/null >/dev/null; then
                sleep 1
            fi
        else
            return 1
        fi
    done

    return 0
}


start() {
    if ! $ENABLE; then
        echo "ENABLE set to false in $DEFAULT, not starting FAHClient"
        echo "Use 'force-start' to override."
        return;
    fi

    echo -n "Starting $NAME ... "

    OPTS=
    if [ -e $CONFIG ]; then
        OPTS+="$CONFIG "
    fi
    OPTS+="$EXTRA_OPTS "
    OPTS+="--run-as $USER "
    OPTS+="--pid-file=$PID "
    OPTS+="--daemon "

    if is_running; then
        echo "FAILED"
        echo "$NAME seems to be already running with PID $(get_pid)"
        exit 1
    else
        rm -f $PID
    fi

    if [ ! -d $HOME ]; then
        mkdir -p $HOME
        chown $USER $HOME
    fi

    cd $HOME
    LOG_STATUS=$(log_status)

    if $QUIET; then
        $EXEC $OPTS >/dev/null 2>/dev/null &
    else
        $EXEC $OPTS &
    fi

    pid=$!
    if wait_for_log_change "$LOG_STATUS" $pid; then
        echo "OK"
    else
        echo "FAIL"
        exit 1
    fi
}


stop() {
    if [ -e $PID ]; then
        echo -n "Stopping $NAME ... "

        if kill $(get_pid) 2>/dev/null; then
            while is_running; do
                sleep 1
            done
            rm -rf $PID

            echo "OK"
        else
            echo "FAILED"
        fi
    fi
}


reload() {
    echo -n "Reloading $NAME ... "
    LOG_STATUS=$(log_status)
    pid=$(get_pid)
    if is_running && kill -SIGUSR1 $pid 2>/dev/null &&
        wait_for_log_change "$LOG_STATUS" $pid; then
        echo "OK"
    else
        echo "FAIL"
        exit 1
    fi
}


status() {
    if is_running; then
        echo "$NAME is running with PID $(get_pid)"
    else
        echo "$NAME is not running"
    fi
}


log() {
    if [ -e $LOG ]; then
        tail -f $LOG
    fi
}


usage() {
    echo -e "Syntax: $0 [OPTIONS] <COMMAND> [-- [OPTIONS]]"
    echo -e "COMMANDS:"
    echo -e "\tstart          Start client"
    echo -e "\tstop           Stop client"
    echo -e "\trestart        Full stop then restart client"
    echo -e "\treload         Respawn client process"
    echo -e "\tstatus         Print client status"
    echo -e "\tlog            Tail the client log"
    echo -e "OPTIONS:"
    echo -e "\t-u <user>      Run as this user."
    echo -e "\t-h <home>      Run in this directory."
    echo -e "\t-v             Be verbose.  Show WS output"
    echo -e
    echo -e "Any options after a '--' will be passed on to the client."
}

if [ $# -eq 0 ]; then
    usage
    exit 0
fi

EXTRA=false
COMMANDS=
while [ "$1" != "" ]; do
    case "$1" in
        -h) HOME=$2; shift ;;
        -u) USER=$2; shift ;;
        -v) QUIET=false ;;
        --help) usage ;;
        --) EXTRA=true ;;
        -*)
            if $EXTRA; then
                EXTRA_OPTS+="$1 "
            else
                usage
                echo "Invalid argument '$1'"
                exit 1
            fi
            ;;
        *)
            if $EXTRA; then
                EXTRA_OPTS+="$1 "
            else
                COMMANDS+="$1 "
            fi
    esac
    shift
done

for c in $COMMANDS; do
    case $c in
        force-start) ENABLE=true; start ;;
        start) start ;;
        stop) stop ;;
        restart) stop; start ;;
        force-reload|reload) reload ;;
        status) status ;;
        log) log ;;
        *)
            usage
            echo "Invalid command '$1'"
            exit 1
            ;;
    esac
done