freebsd-ports/astro/setiathome/files/setiathome.1

.\" $FreeBSD$
.Dd Dec 12, 2000
.Dt setiathome 1 LOCAL
.Os FreeBSD
.Sh NAME
.Nm setiathome
.Nd the SETI@home client program
.Sh SYNOPSIS
.Nm
.Op Ar options
.Sh DESCRIPTION
.Nm
is the
.Ux
version of the
.Tn 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
.Li http://setiathome.berkeley.edu
for more information.
.Pp
The first time you run
.Nm
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.
.Pp
After this you can run
.Nm
in the background,
and direct its output to
.Pa /dev/null
if you like.
.Pp
.Nm
can be freely stopped and restarted.
It saves its state in files, and will pick up where it left off.
.Pp
If you want to run multiple instances of
.Nm
(on a multiprocessor machine, or on multiple machines
that share a filesystem) each one must be run in a different directory.
.Sh IMPLEMENTATION NOTES
.Nm
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,
.Nm
requires a permanent or
.Dq dial on demand
Internet connection to upload results to and download new work units from the
.Tn SETI@home
server at any time.
.Sh OPTIONS
.Bl -tag -width countries
.It Fl countries
Show list of country codes.
.It Fl email
Send E-mail (to login E-mail address) on errors.
Useful if you run in background directed to
.Pa /dev/null .
.It Fl graphics
Generate a data stream for the
.Xr xsetiathome 1
graphical interface.
.It Fl login
Login or create new account.
.It Fl nice Ar N
Set
.Xr nice 1
priority to
.Ar N
(default 1).
.It Fl nolock
Omit the multiple-instance check, which uses file locking
(not available on some NFS systems).
.It Fl proxy Ar hostname : Ns Ar port
Connect to
.Tn SETI@home
server via specified HTTP proxy server and port.
.It Fl socks_passwd Ar password
SOCKS
.Ar password .
.It Fl socks_server Ar hostname : Ns Ar port
Connect to
.Tn SETI@home
server via specified SOCKS server and port.
Overrides
.Ev SOCKS_SERVER .
SOCKS versions 4 and 5 are supported.
.It Fl socks_user Ar name
SOCKS user
.Ar name .
.It Fl stop_after_process
Stop after processing current work unit.
Do not send result.
.It Fl 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
.Pa stop_after_send.txt
mentioned in
.Sx FILES
below.)
.It Fl verbose
Print a running summary of the work being done.
.It Fl version
Show software version.
.El
.Sh USAGE
.Ss Starting setiathome
This
.Fx
port includes a start-up script that starts
.Nm
at system start-up and stop it at system shut-down.
.Ss Stopping setiathome
There is two way to stop
.Nm ,
gracefully (See
.Pa stop_after_send.txt
mentioned in
.Sx FILES
below) and urgently (using kill as done at system shut-down time).
To do so, respectively run
.Pp
.Dl %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh gracefull
or
.Dl %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh stop
.Ss Configuration File
The optional configuration file
.Pa %%PREFIX%%/etc/rc.%%PREFX%%setiathome%%SUFX%%.conf
may contain one or more of the following variable assignments to override
their default values:
.Bl -tag -width seti_wrkdir
.It Pa seti_wrkdir=/var/db/setiathome
The working directory where
.Nm
will store it's temporary files.
.It Pa seti_std_args=-email and/or -graphics
The command line arguments for normal start-up.
.It Pa seti_reg_args=-login
The command line arguments for registration.
.It Pa seti_proxy_server=hostname:port
The HTTP proxy server and port to connect through.
.It Pa seti_socks_server=hostname:port
The SOCKS server and port to connect through.
.It Pa seti_socks_user=username
The SOCKS user name to connect with.
.It Pa seti_socks_passwd=password
The SOCKS password to connect with.
.It Pa seti_user=setiathome
The user to run
.Nm
as.
.It Pa seti_group=setiathome
The group to run
.Nm
as (only used at registration time).
.It Pa seti_nice=15
The
.Xr nice 1
value to run
.Nm 
at.
.It Pa seti_maxprocs= Ns Va Number of CPUs
The number of
.Nm 
processes to run concurrently. Defaults to the number of CPUs installed.
Running more than one instance per CPU is not useful, as
.Nm
is almost completely CPU-bound.
.It Pa seti_sleep_time=21600
The time to sleep (in seconds) between restarts if the
.Nm
data server is unresponsive.
.El
.Pp
If you change values in the configuration file, you need to stop and start
.Nm Ns ,
and possibly reconfigure the working directory for the changes to take
effect. Run
.Pp
.Dl %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh stop
.Dl %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh register
.Dl %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh start
.Pp
to do that.
.Ss Setting up setiathome
You can use the start-up script to set up a working directory
and register with or log in to
.Tn SETI@home
by calling it with the argument
.Ar register .
If you'd like to configure and run it manually, you should first disable the
start-up script. Then, for each
.Nm
instance you'd like to run, create a directory, make it owned by the user
you'd like to run
.Nm
as, and run
.Ic setiathome -login
in that directory.
.Pp
Then, arrange for
.Nm
to be started automatically.  You can easily do so by adding a line similiar
to
.Bd -ragged -offset indent
.Li */10 * * * * cd 
.Va working directory 
.Li && setiathome -email >/dev/null
.Ed
.Pp
to the user's crontab.
.Sh ENVIRONMENT
.Bl -tag -width SOCKS_SERVER
.It Ev HTTP_PROXY
If defined,
.Nm
will connect through a proxy server, specified as
.Do Ns Va hostname Ns
.Op Li : Ns Va port
.Dc .
.It Ev SOCKS_SERVER
If defined,
.Nm
will connect through a SOCKS server, specified as
.Do Ns Va hostname Ns
.Op Li : Ns Va port
.Dc .
.It Ev SOCKS_USER , Ev SOCKS_PASSWD
If defined, these will be used as the login name and password
for the SOCKS server.
Otherwise
.Nm
will query you.
.El
.Sh FILES
.Bl -tag -width /var/db -compact
.It Pa %%PREFIX%%/etc/rc.d/%%PREFX%%setiathome%%SUFX%%.sh
Start-up script.
.Pp
.It Pa %%PREFIX%%/etc/rc.%%PREFX%%setiathome%%SUFX%%.conf
Optional configuration file for the start-up script.
.Pp
.It Pa /var/db/setiathome/
Primary working directory.
.Pp
.It Pa /var/db/setiathome/user_info.sah
Registration data.
.Pp
.It Pa /var/db/setiathome/ Ns Va n Ns Pa /
Working directories for additional process
.Va n
(when running more than one instance).
.Pp
.It Pa /var/db/setiathome/ Ns Xo
.Op Ns Va n Ns Pa / Ns 
.Pa lock.sah
.Xc
Lock file to prevent multiple instances to work on the same data.
.Pp
.It Pa /var/db/setiathome/ Ns Xo
.Op Ns Va n Ns Pa / Ns 
.Pa *.sah
.Xc
Working files.
These should not be modified.
.Pp
.It Pa /var/db/setiathome/ Ns Xo
.Op Ns Va n Ns Pa / Ns 
.Pa pid.sah
.Xc
The process ID of the current instance.
.Pp
.It Pa /var/db/setiathome/ Ns Xo
.Op Ns Va n Ns Pa / Ns 
.Pa stop_after_send.txt
.Xc
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
.Pa .txt ,
while all other files used by
the client have extensions
.Pa .sah .
.El
.Sh SEE ALSO
.Xr xsetiathome 1 ,
.Xr ipcs 1 ,
.Xr ipcrm 1 .
.Sh AUTHORS
.Tn 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.
.Pp
.An Stefan Bethke Aq stb@freebsd.org
amended the original manual page for this
.Fx
port.
.Sh BUGS
Outstanding shared memory segments and semaphores may be left
active in case of an abnormal exit of the
.Ic setiathome -graphics
process.  These can prevent any future invocation of
.Ic setiathome -graphics .
To resolve this problem, use
.Xr ipcs 1
and
.Xr ipcrm 1
to remove shared memory segments and semaphores that
are not associated with a process.  This behavior may vary
depending upon how your
.Ux
system handles this situation.
.Pp
For version 3.* clients, the estimated progress as indicated
by the
.Pa prog=
line in the
.Pa 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.