setiathome(1)		User Commands		Version 3.0 - September 2000

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.

FILES
    The program generates several files with .sah extension
    in the directory from which it's run.
    These should not be modified.

    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.
    You can use symlinks for each directory to avoid duplication
    of the binary image.  e.g.:
		ln -s cpu0/setiathome cpu1/setiathome

    setiathome uses a lock file (lock.txt) to prevent
    multiple instances from running in the same directory.

    To finish up your current work unit, return your result, and not
    download a new work unit, while the client is running, touch
    a file named "stop_after_send.txt" in the client directory.
    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 ***

    The file "pid.sah" contains the process ID of the current instance.

RUNNING SETIATHOME
    The first time you run setiathome it will interactively
    ask you for email 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 setiathome to be started automatically, you can
    set up a cron job.  Add the following line to your crontab:

    0 * * * * cd <setidir>; ./setiathome -nice 19 > /dev/null 2> /dev/null

    Where <setidir> is the directory where the setiathome client is installed.
    This cron job will attempt to start the client at the top of every hour.
    If it is already running, the next invocation will do nothing.
    If the client is not running, it will be started.
    For more information on cron jobs see the crontab(1) manual page.

    The following script will stop all instances SETI@home:
	(assuming the binary execution name is: setiathome)

    #! /bin/sh
    kill `ps aux | grep setia | grep -v grep | awk '{print $2}'`

    (adjust the ps arguments for your system)

    The following will stop the instance in the current directory:

    #! /bin/sh
    kill `cat pid.sah`

    Please do not operate the client on machines for which you do not
    have permission.

ENVIRONMENT VARIABLES

    If the environment variable HTTP_PROXY is defined,
    setiathome will connect through a proxy server,
    specified as hostname or hostname:port.

    If the environment variable SOCKS_SERVER is defined,
    setiathome will connect through a SOCKS server,
    specified as hostname or hostname:port.
    If the environment variables SOCKS_USER and SOCKS_PASSWD
    are defined, these will be used as the login name and password
    for the SOCKS server.  Otherwise setiathome will query you.

OPTIONS
    -login
	Login or create new account.

    -countries
	Show list of country codes.
    
    -version
	Show software version
    
    -nice N
	Set "nice" priority to N (default 1);

    -email
	Send email (to login email address) on errors.
	Useful if you run in background directed to /dev/null.
	This option is not available for all clients.
    
    -graphics
	Generate a data stream for the xsetiathome graphical interface
	(see README.xsetiathome)
	This option is not available for all clients.

    -proxy hostname:port
	Connect to SETI@home server via specified HTTP proxy server and port.
    
    -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.

    -socks_passwd password
	SOCKS password.

    -stop_after_process
	If a work_unit.sah file is present, process this work unit
	and stop after processing is complete, do not return result.
	If the client is started with this option, and there is
	a completed result.sah file present, the client will first
	return the results, then pick up a new work unit, process
	to completion, then exit.

    -stop_after_xfer
	Return results and pick up a new work unit.
	This option only functions if the result.sah file is present
	and complete indicating that processing is finished for this
	work unit.  If a work_unit.sah is present, indicating processing
	is not complete, no transfer or processing will be performed,
	and the client will exit.
	(see also: stop_after_send.txt mentioned in FILES above)
    
    -verbose
	print a running summary of the work being done.
	Starting with the version 2.4 clients, the client is silent
	to stdout during processing.  There are messages at the start
	and finish of processing a work unit, but there are no progress
	messages printed during processing unless this option is used.
    
    -nolock
	omit the multiple-instance check, which uses file locking
	(not available on some NFS systems)

KNOWN 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'
	and 'ipcrm' 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.
	See also ipcs(1) and ipcrm(1)

	For version 3.0 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.

SEE ALSO:
	There is much more information to be found about the operation
	of the client at the following WEB sites:
		http://setiathome.berkeley.edu/
		http://setiathome.berkeley.edu/faq.html
		http://setiathome.berkeley.edu/links.html
	with discussions of add-on programs and scripts to control
	the client in various situations.
