freebsd/ports
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

biology/linux-foldingathome: Add manual page fahclient(8) and clean up

Browse Source 
Move all documentation to fahclient.8.

Reference the new manual page from pkg-message and the rc script.

Remove outdated --chdir handling. The flag is gone from fah-client and
rc(8) handles that automatically.

Remove an incorrect description of what fahclient_flags does.

Allow fahclient_team and fahclient_donor to be empty. This way we avoid
warnings when the configuration file overrides the command-line flags,
e.g.:

    14:25:24:W :Option 'user' already set to 'Anonymous' reseting to '0mp'.
    14:25:24:W :Option 'team' already set to '11743' reseting to '11743'.

Pass --log-to-screen=true to showconfig's flags. This way we can
see again the configuration.

Improve quoting of variables in fahclient.

Update to the v8.5 branch is currently blocked by some missing
libraries. It seems that we would need to add a Rocky Linux 9.7 version
of bzip2 to proceed.
This commit is contained in:
Mateusz Piotrowski
2026-06-09 15:54:13 +02:00
parent bfa8e20ada
commit 0de6f87f3f
5 changed files with 198 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
biology/linux-foldingathome/Makefile
+3 -1
View File
@@ -1,5 +1,6 @@
PORTNAME= foldingathome
DISTVERSION= 8.4.9
PORTREVISION= 1
CATEGORIES= biology linux
MASTER_SITES= https://download.foldingathome.org/releases/public/fah-client/
PKGNAMEPREFIX= linux-
@@ -27,7 +28,7 @@ ETCDIR= ${PREFIX}/etc/fahclient
DOCSDIR= ${PREFIX}/share/doc/fahclient
NO_BUILD= yes
SUB_FILES= pkg-message
SUB_FILES= fahclient.8 pkg-message
SUB_LIST= FAHCLIENT_CONFIG_XML=${_FAHCLIENT_CONFIG_XML} \
FAHCLIENT_PROGRAM=${_FAHCLIENT_PROGRAM} \
FAHCLIENT_WORK_DIR=${_FAHCLIENT_WORK_DIR}
@@ -60,6 +61,7 @@ do-install:
${INSTALL_DATA} ${FILESDIR}/config.xml.sample \
${STAGEDIR}${_FAHCLIENT_CONFIG_XML}.sample
@${MKDIR} ${STAGEDIR}${_FAHCLIENT_WORK_DIR}
${INSTALL_MAN} ${WRKDIR}/fahclient.8 ${STAGEDIR}${PREFIX}/share/man/man8
post-install-DOCS-on:
@${MKDIR} ${STAGEDIR}${DOCSDIR}
biology/linux-foldingathome/files/fahclient.8.in
+181
View File
@@ -0,0 +1,181 @@
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2020-2026 Mateusz Piotrowski <0mp@FreeBSD.org>
.\"
.Dd June 9, 2026
.Dt FAHCLIENT 8
.Os
.Sh NAME
.Nm fahclient
.Nd service daemon for the Folding@home Client
.Sh SYNOPSIS
.Nm
.Ar command Op Ar args ...
.Nm
.Cm log
.Nm
.Cm showconfig
.Sh DESCRIPTION
.Nm
is an
.Xr rc 8
daemon for the Folding@home Client.
.Pp
Configure
.Nm
with the following
.Xr rc.conf 5
variables:
.Bl -tag -width fahclient_extra_flags -offset 2n
.It Va fahclient_enable
Toggle to enable
.Nm .
Default:
.Dq NO .
.It Va fahclient_chdir
Working directory of
.Nm .
Default:
.Dq Pa %%FAHCLIENT_WORK_DIR%% .
.It Va fahclient_config
Configuration file.
Default:
.Dq Pa %%ETCDIR%%/config.xml .
.It Va fahclient_donor
Donor to attribute work units to.
Settings in the configuration file take precedence.
Default:
.Dq Anonymous .
.It Va fahclient_extra_flags
Extra flags passed to the Folding@home Client after other flags.
Default: empty.
.It Va fahclient_flags
Extra flags passed to
.Xr daemon 8
before any other flags.
Default: empty.
.It Va fahclient_logfile
Log file.
Takes precedence over settings in the configuration file.
Default:
.Dq Pa %%FAHCLIENT_WORK_DIR%%/log.txt .
.It Va fahclient_team
Folding@home team to join and attribute work units to.
Settings in the configuration file take precedence.
Default:
.Ql 11743 ,
Team
.Fx .
.It Va fahclient_pidfile
PID file.
Default:
.Dq Pa %%FAHCLIENT_WORK_DIR%%/fahclient.pid .
.It Va fahclient_user
System user to run
.Nm fahclient
as.
Default:
.Ql fahclient .
.El
.Pp
.Nm
supports the following extra commands:
.Bl -tag -width showconfig -offset 2n
.It Cm log
View
.Nm Ap s
folding logs.
.It Cm showconfig
Show the final configuration of
.Nm
after all configuration files and command-line flags are processed.
.El
.Pp
The Web Dashboard is available at
.Lk https://v8-4.foldingathome.org/
and
.Lk http://localhost:7396/
when
.Nm
is running.
Visit the Web Dashboard to connect
.Nm
to a Folding@home Account and manage folding work.
.Pp
Link
.Nm
to an existing account with an Account Token.
Generate it on the Web Dashboard.
Add the Account Token to either the configuration file
or specify it a command-line argument to
.Nm :
.Dl sysrc fahclient_extra_flags+=" --account-token=<Account-Token>"
.Pp
Refer to the Folding@home Client's help message for more usage
information:
.Dl %%FAHCLIENT_PROGRAM%% --help
.Sh FILES
.Bl -tag -width "%%FAHCLIENT_PROGRAM%%"
.It Pa %%FAHCLIENT_PROGRAM%%
Folding@home Client program invoked by the
.Nm
daemon.
.Sh EXAMPLES
.Ss Example 1: Quick Start
Start
.Nm
by executing the following steps:
.Bd -literal -offset indent
# Mount linprocfs(5) at /compat/linux/proc:
mount -t linprocfs linprocfs /compat/linux/proc
# Mount linsysfs(5) at /compat/linux/proc:
mount -t linsysfs linsysfs /compat/linux/sys
# Enable fahclient:
service fahclient enable
# Optionally, set the desired donor name:
sysrc fahclient_donor="Anonymous"
# Start fahclient:
service fahclient start
.Ed
.Pp
Open the Folding@home Web Dashboard to finish the setup.
.Pp
Add
.Xr linprocfs 5
and
.Xr linsysfs 5
entries to
.Xr fstab 5
to make the setup persistent across reboots.
.Sh SEE ALSO
.Lk https://foldingathome.org/guides/v8-4-client-guide/ "Folding@home v8.4 Client Guide"
.Pp
.Lk https://foldingathome.org/faq/ "Folding@home FAQ"
.Pp
.Lk https://foldingforum.org/ "Folding Forum"
.Pp
.Lk https://stats.foldingathome.org/team/11743 "Team FreeBSD Statistics"
.Sh HISTORY
Team
.Fx
was founded by
.An Frank Mayhar .
.Sh AUTHORS
The
.Nm
manual page was written by
.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
.Sh CAVEATS
The working directory of
.Nm
must have the execute permissions enabled to function properly.
For example, on a
.Xr zfs 4
dataset where
.Pa %%FAHCLIENT_WORK_DIR%%
is located the
.Ql exec
property
must be set to
.Ql on .
biology/linux-foldingathome/files/fahclient.in
+11 -60
View File
@@ -2,59 +2,15 @@
# SPDX-License-Identifier: BSD-2-Clause
#
# Copyright (c) 2020 Mateusz Piotrowski <0mp@FreeBSD.org>
# Copyright (c) 2020-2026 Mateusz Piotrowski <0mp@FreeBSD.org>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# PROVIDE: fahclient
# REQUIRE: DAEMON LOGIN NETWORKING linux
#
# Add the following lines to /etc/rc.conf to enable nginx:
# fahclient_enable (bool): Set to "NO" by default.
# Set it to "YES" to enable fahclient.
# fahclient_user (str): Default: "fahclient"
# User to run fahclient as.
# fahclient_chdir (str): Default: "%%FAHCLIENT_WORK_DIR%%"
# Directory to chdir before starting fahclient.
# fahclient_config (str): Default: "%%ETCDIR%%/config.xml"
# Path to fahclient configuration file.
# fahclient_donor (str): Default: "Anonymous"
# Donor to attribute work units to.
# Settings in fahclient_config take precedence.
# fahclient_team (str): Default: "11743" (FreeBSD Team)
# Team to attribute work units to.
# Settings in fahclient_config take precedence.
# fahclient_pidfile (str): Default: "%%FAHCLIENT_WORK_DIR%%/fahclient.pid"
# Path to PID file.
# fahclient_logfile (str): Default: "%%FAHCLIENT_WORK_DIR%%/log.txt"
# Path to log file. Takes precedence over
# settings in fahclient_config.
# fahclient_flags (str): Default: ""
# Extra flags passed to start command *before*
# other options.
# fahclient_extra_flags (str): Defaults to ""
# Extra flags passed to start command *after*
# other options.
# Refer to to the fahclient(8) manual page for the configuration instructions.
#
. /etc/rc.subr
@@ -66,11 +22,13 @@ load_rc_config 'fahclient'
# Default settings.
: "${fahclient_enable:=NO}"
: "${fahclient_user:=fahclient}"
# The program is going to create a lot of files in its working directory,
# so make sure that they all land in a sensible place.
: "${fahclient_chdir:=%%FAHCLIENT_WORK_DIR%%}"
: "${fahclient_svcj_options:=net_basic}"
: "${fahclient_donor:=Anonymous}"
: "${fahclient_team:=11743}"
: "${fahclient_donor=Anonymous}"
: "${fahclient_team=11743}"
: "${fahclient_pidfile:=%%FAHCLIENT_WORK_DIR%%/fahclient.pid}"
: "${fahclient_config:=%%ETCDIR%%/config.xml}"
@@ -81,35 +39,28 @@ procname="%%FAHCLIENT_PROGRAM%%"
command="/usr/sbin/daemon"
command_args="-p ${pidfile} -- ${procname}"
# Some notes on the specified options:
# - fahclient_flags are passed in before other options by the rc
# framework.
# - --user sets the donor work units are attributed to (config file takes
# precedence).
# - --team sets the team work units are attributed to (cfg file takes
# precedence).
# - --config is necessary to point the program to the correct configuration
# file.
# - --chdir is used to switch to a desired work directory. The program is going
# to create a lot of files in its current working directory so should not be
# just any directory on the system.
# - fahclient_extra_flags are passed in after all other options.
_fahclient_command_args=
_fahclient_command_args="${_fahclient_command_args} --user=${fahclient_donor}"
_fahclient_command_args="${_fahclient_command_args} --team=${fahclient_team}"
_fahclient_command_args="${_fahclient_command_args} ${fahclient_donor:+--user=${fahclient_donor}}"
_fahclient_command_args="${_fahclient_command_args} ${fahclient_team:+--team=${fahclient_team}}"
_fahclient_command_args="${_fahclient_command_args} --config=${fahclient_config}"
#_fahclient_command_args="${_fahclient_command_args} --chdir=${fahclient_chdir}"
_fahclient_command_args="${_fahclient_command_args} --log=${fahclient_logfile}"
_fahclient_command_args="${_fahclient_command_args} --log-rotate-dir=$(dirname ${fahclient_logfile})"
_fahclient_command_args="${_fahclient_command_args} --log-rotate-dir=$(dirname "${fahclient_logfile}")"
_fahclient_command_args="${_fahclient_command_args} --log-to-screen=false"
_fahclient_command_args="${_fahclient_command_args} ${fahclient_extra_flags}"
command_args="${command_args} ${_fahclient_command_args}"
extra_commands="log showconfig"
log_cmd="tail -F -- ${fahclient_logfile}"
showconfig_cmd="${procname} ${fahclient_flags} ${_fahclient_command_args} --print"
showconfig_cmd="${procname} ${_fahclient_command_args} --log-to-screen=true --print"
if [ -n "$fahclient_user" ]; then
showconfig_cmd="su -m $fahclient_user -c 'sh -c \"$showconfig_cmd\"'"
fi
required_modules='linprocfs linsysfs linux64:linux64elf'
cd ${fahclient_chdir}
run_rc_command "$1"
biology/linux-foldingathome/files/pkg-message.in
+2 -82
View File
@@ -1,88 +1,8 @@
[
{ type: install
message: <<EOM
Quick start
===========
Here is a list of steps to quickly get started with Folding@home on FreeBSD:
1. Mount linprocfs(5) in /compat/linux/proc.
2. Mount linsysfs(5) in /compat/linux/sys.
3. Enable the fahclient service:
sysrc fahclient_enable=YES
4. Consider setting Folding@home donor name and team ID:
sysrc fahclient_donor=my_fah_username
sysrc fahclient_team=0
Team 0 means "no team", by default fahclient joins team FreeBSD
(11743).
5. Start the service:
service fahclient start
At this point, the daemon should be up. By default it listens on http://localhost:7396
for incoming HTTP connections. There you can login and configure and/or
register/connect with your F@H account. If you have already an existing account you
can join by getting the account-token from there and adding it either to a config
file or by running
sysrc fahclient_extra_flags+=" --account-token=<your-token>"
Additional notes
================
- The current status of folding can be inspected by running
the following command:
service fahclient log
- The default working directory for fahclient is %%FAHCLIENT_WORK_DIR%%.
In order to function properly, fahclient requires its working directory
to be on a partition/dataset with execute permissions on. For example
if /var/db is on a ZFS dataset with exec=off, then %%FAHCLIENT_WORK_DIR%%
needs to have exec=on.
Note, that usually the permissions are on unless the system
configuration was modified by the administrator.
- By default the FreeBSD team (team id 11743) is joined.
This can be overridden by changing the configuration in rc.conf:
sysrc fahclient_team=0
The service has to be restarted to pick up the change.
Statistics for the FreeBSD team can be viewed here:
https://stats.foldingathome.org/team/11743
- Team and donor configuration values in %%FAHCLIENT_CONFIG_XML%% take
precedence over those configured in rc.conf using sysrc.
- It's possible to specify additional flags in rc.conf. Those take
precedence over what is configured in the config file, e.g., setting
the maximum number of cpus to be used:
sysrc fahclient_flags+=" --cpus=7"
Flags that are set this way will be overridden by settings in
%%FAHCLIENT_CONFIG_XML%%. You can set fahclient_extra_flags
to override settings in %%FAHCLIENT_CONFIG_XML%%:
sysrc fahclient_extra_flags+=" --cpus=7"
- You can check the actual configuration values applied with:
service fahclient showconfig
- More information about configuring and running the Folding@home
software is available on those websites:
- https://foldingforum.org/
- https://foldingathome.org/support/faq/
Refer to the fahclient(8) manual page for instructions
on how to get started with Folding@home on FreeBSD.
EOM
}
]
biology/linux-foldingathome/pkg-plist
+1
View File
@@ -1,4 +1,5 @@
bin/fah-client
share/man/man8/fahclient.8.gz
@dir(fahclient,fahclient,) %%ETCDIR%%
@sample(fahclient,fahclient,) %%ETCDIR%%/config.xml.sample
@dir(fahclient,fahclient,) %%FAHCLIENT_WORK_DIR%%