setiathome(1)

NAME
setiathome - the SETI@home client program

SYNOPSIS
setiathome [options]

DESCRIPTION
setiathome is the UNIX version of the SETI@home client. It downloads radio telescope data from a network server, analyzes the data looking for signals of extraterrestrial origin, and uploads results to the server, repeating this cycle indefinitely. See http://setiathome.berkeley.edu for more information.

The first time you run setiathome it will interactively ask you for E-mail address, name, country etc. This info is stored in a file and no interaction is needed when you run the program subsequently.

After this you can run setiathome in the background, and direct its output to /dev/null if you like.

setiathome can be freely stopped and restarted. It saves its state in files, and will pick up where it left off.

If you want to run multiple instances of setiathome (on a multiprocessor machine, or on multiple machines that share a filesystem) each one must be run in a different directory.

IMPLEMENTATION NOTES
setiathome requires about 0.5 MBytes of disk space per working directory, and about 15 MBytes of memory per instance. If you have ample physical memory, its work load should be almost undetectable. Additionally, setiathome requires a permanent or “dial on demand” Internet connection to upload results to and download new work units from the SETI@home server at any time.

OPTIONS

-countries
    Show list of country codes.

-email
    Send E-mail (to login E-mail address) on errors. Useful if you run in background directed to /dev/null.

-graphics
    Generate a data stream for the xsetiathome(1) graphical interface.

-login
    Login or create new account.

-nice N
    Set nice(1) priority to N (default 1).

-nolock
    Omit the multiple-instance check, which uses file locking (not available on some NFS systems).

-proxy hostname:port
    Connect to SETI@home server via specified HTTP proxy server and port.

-socks_passwd password
    SOCKS password.

-socks_server hostname:port
    Connect to SETI@home server via specified SOCKS server and port. Overrides SOCKS_SERVER. SOCKS versions 4 and 5 are supported.

-socks_user name
    SOCKS user name.

-stop_after_process
    Stop after processing current work unit. Do not send result.

-stop_after_xfer
    Stop after current work unit has been sent to the SETI server and a new work unit has been obtained. (See also stop_after_send.txt mentioned in FILES below.)

-verbose
    Print a running summary of the work being done.

-version
    Show software version.

USAGE

  Starting setiathome
This FreeBSD port includes a start-up script that starts setiathome at system start-up and stop it at system shut-down.

  Stopping setiathome
There is two way to stop setiathome, gracefully (See stop_after_send.txt mentioned in FILES below) and urgently (using kill as done at system shut-down time). To do so, respectively run

    %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh gracefull
or
    %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh stop

  Configuration File
The optional configuration file %%PREFIX%%/etc/rc.%%PREFX%%setiathome%%SUFX%%.conf may contain one or more of the following variable assignments to override their default values:

seti_wrkdir=/var/db/setiathome
    The working directory where setiathome will store it's temporary files.

seti_std_args=-email and/or -graphics
    The command line arguments for normal start-up.

seti_reg_args=-login
    The command line arguments for registration.

seti_proxy_server=hostname:port
    The HTTP proxy server and port to connect through.

seti_socks_server=hostname:port
    The SOCKS server and port to connect through.

seti_socks_user=username
    The SOCKS user name to connect with.

seti_socks_passwd=password
    The SOCKS password to connect with.

seti_user=setiathome
    The user to run setiathome as.

seti_group=setiathome
    The group to run setiathome as (only used at registration time).

seti_nice=15
    The nice(1) value to run setiathome at.

seti_maxprocs=Number of CPUs
    The number of setiathome processes to run concurrently. Defaults to the number of CPUs installed. Running more than one instance per CPU is not useful, as setiathome is almost completely CPU-bound.

seti_sleep_time=21600
    The time to sleep (in seconds) between restarts if the setiathome data server is unresponsive.

If you change values in the configuration file, you need to stop and start setiathome, and possibly reconfigure the working directory for the changes to take effect. Run

    %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh stop
    %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh register
    %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh start

to do that.

  Setting up setiathome
You can use the start-up script to set up a working directory and register with or log in to SETI@home by calling it with the argument register. If you'd like to configure and run it manually, you should first disable the start-up script. Then, for each setiathome instance you'd like to run, create a directory, make it owned by the user you'd like to run setiathome as, and run setiathome -login in that directory.

Then, arrange for setiathome to be started automatically. You can easily do so by adding a line similiar to

*/10 * * * * cd working directory && setiathome -email >/dev/null

to the user's crontab.

ENVIRONMENT

HTTP_PROXY
    If defined, setiathome will connect through a proxy server, specified as “hostname [:port] ”.

SOCKS_SERVER
    If defined, setiathome will connect through a SOCKS server, specified as “hostname [:port] ”.

SOCKS_USER, SOCKS_PASSWD
    If defined, these will be used as the login name and password for the SOCKS server. Otherwise setiathome will query you.

FILES
%%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh
    Start-up script.

%%PREFIX%%/etc/rc.%%PREFX%%setiathome%%SUFX%%.conf
    Optional configuration file for the start-up script.

/var/db/setiathome/
    Primary working directory.

/var/db/setiathome/user_info.sah
    Registration data.

/var/db/setiathome/n/
    Working directories for additional process n (when running more than one instance).

/var/db/setiathome/
    [n/] lock.sah Lock file to prevent multiple instances to work on the same data.

/var/db/setiathome/
    [n/] *.sah Working files. These should not be modified.

/var/db/setiathome/
    [n/] pid.sah The process ID of the current instance.

/var/db/setiathome/
    [n/] stop_after_send.txt While the client is running, touch this file in the working directory to finish up your current work unit, return your result, and not download a new work unit. When the processing is finished, and the result sent, the client will stop. Note this one file extension is .txt, while all other files used by the client have extensions .sah.

SEE ALSO
xsetiathome(1), ipcs(1), ipcrm(1).

AUTHORS
SETI@home was developed by David Anderson, Jeff Cobb, Charles Congdon, Charlie Fenton, David Gedye, Kyle Granger, Eric Korpela, Matt Lebofsky, Peter Leiser, Brad Silen, Woody Sullivan, and Dan Werthimer.

Stefan Bethke <stb@freebsd.org> amended the original manual page for this FreeBSD port.

BUGS
Outstanding shared memory segments and semaphores may be left active in case of an abnormal exit of the setiathome -graphics process. These can prevent any future invocation of setiathome -graphics. To resolve this problem, use ipcs(1) and ipcrm(1) to remove shared memory segments and semaphores that are not associated with a process. This behavior may vary depending upon how your UNIX system handles this situation.

For version 3.* clients, the estimated progress as indicated by the prog= line in the state.sah file in not exactly linear in relationship to completion time. Using this value to predict completion time may not be completely accurate. The linear relationship will vary depending upon the characteristics of the work unit parameters.