xgrid(1)                  BSD General Commands Manual                 xgrid(1)

NAME
     xgrid - submit and monitor xgrid jobs, nodes, and datasets

SYNOPSIS
     xgrid [-h[ostname] hostname] [-p[assword] password]
     xgrid -job run [-si stdin] [-in indir] [-so stdout] [-se stderr]
           [-out outdir] cmd [arg1 [...]]
     xgrid -job submit [-si stdin] [-in indir] cmd [arg1 [...]]
     xgrid -job results -id identifier [-so stdout] [-se stderr] [-out outdir]
     xgrid -job {stop | delete | parameters} -id identifier
     xgrid -job {list | info | status} -id identifier
     xgrid -node {list | info | status} -id identifier
     xgrid -dataset {list | info | status} -id identifier

OPTIONS
     The available options are as follows:

     -h[ostname] hostname                the hostname or IP address of the
                                         controller -- if not present, xgrid
                                         will use the value specified in
                                         XGRID_CONTROLLER_HOSTNAME

     -p[assword] password                if the controller requires a password
                                         (as is the default), the password
                                         must be specified here or in
                                         XGRID_CONTROLLER_PASSWORD

     -id identifier                      the xgrid identifier for the job,
                                         dataset, or node of interest (not
                                         used when submitting a job)

     -node {list | info | status}        retrieve list of, info about, or sta-
                                         tus of a node

     -dataset {list | info | status}     retrieve list of, info about, or sta-
                                         tus of a dataset

     -job {list | info | status}         retrieve list of, info about, or sta-
                                         tus of a job

     -job stop                           stop job execution but don't delete
                                         job

     -job delete                         stop job execution (if it is running)
                                         and delete job

     -job results                        retrieve results of job previously
                                         submitted

     -job parameters                     retrieve parameters used when submit-
                                         ting job

     -job {submit | run} cmd arg1 ...    specify a command (with arguments) to
                                         either run synchronously or submit
                                         asynchronously

     -si stdin                           for submit/run, file to use for stan-
                                         dard input

     -in indir                           for submit/run, working directory to
                                         submit with job

     -so stdout                          for run/results, file to write the
                                         standard output stream to

     -se stderr                          for run/results, file to write the
                                         standard error stream to

     -out outdir                         for run/results, directory to store
                                         job results in

RETURN VALUES
     Prints the job identifier when a job is submitted.

     Returns 0 if command completed successfully.

ENVIRONMENT
     XGRID_CONTROLLER_HOSTNAME gives the hostname or IP address of the con-
     troller

     XGRID_CONTROLLER_PASSWORD gives the password of the controller if one is
     required

FILES
     /Library/Xgrid/Documentation
             Documentation about Xgrid

     /etc/xgrid/GridAgent/controller-password
             Password that the agent may require the controller to have (only
             readable by root)

     /etc/xgrid/GridServer/agent-password
             Password that the controller may be required by the agent to have
             (only readable by root)

     /etc/xgrid/GridServer/client-password
             Password that the controller may require the client to have (only
             readable by root)

     /Library/Preferences/com.apple.xgrid.controller.plist
             RequireClientPassword : whether a client must provide a password
             to connect to the controller

     /Library/Preferences/com.apple.xgrid.agent.plist
             All values are <true/> for YES and <false/> for NO, except
             ServiceName which is a UTF-8 string.

             o   RequireControllerPassword : controllers must provide password
                 to the agent

             o   BindToFirstAvailable : connect to first controller found

             o   UsesRendezvous : search for controllers on local subnet

             o   OnlyWhenIdle : only accept jobs when idle

             o   SuspendWhenNotIdle : suspend jobs when no longer idle (else,
                 keep running at low priority)

             o   ServiceName : name of the controller service to connect to

EXAMPLES
     List available nodes and specify hostname and password:

           $ xgrid -h mycomputer.apple.com -p pword -node list

     Set environment variables for the following examples (tcsh):

           % setenv XGRID_CONTROLLER_HOSTNAME mycomputer.apple.com
           % setenv XGRID_CONTROLLER_PASSWORD pword

     Set environment variables for the following examples (bash):

           $ export XGRID_CONTROLLER_HOSTNAME=mycomputer.apple.com
           $ export XGRID_CONTROLLER_PASSWORD=pword

     List jobs and then get the status for one of the jobs:

           $ xgrid -job list
           { jobArray = ({ jobIdentifier = 26; } ); }
           $ xgrid -job status -id 26

     Run the cal program (specified using a full path so the command isn't
     copied) on a single node synchronously and print the output to standard
     output:

           $ xgrid -job run /usr/bin/cal 2002

     Submit myscript with the files in the input directory.  Then retrieve the
     results and save the stdout and stderr streams in files instead of print-
     ing them out to the terminal and save the output files in the specified
     directory.  Finally delete the job:

           $ xgrid -job submit -in ~/data/working myscript param1 param2
           { jobIdentifier = 27; }
           $ xgrid -job results -id 27 -so job.out -se job.err -out job-outdir
           $ xgrid -job delete -id 27

DIAGNOSTICS
     xgrid with no arguments will print the usage message

ERRORS
     If a job fails due to an error, the error code reported is simply the
     error code that was returned by the task (or by the system).  (For system
     error descriptions, see /usr/include/sys/errno.h.) Common errors include:

     o   Error 1: The permissions of some file are set incorrectly.

     o   Error 2: No such file exists.

     o   Error 8: The executable file wasn't actually executable.

SEE ALSO
     ssh(1)

CONFORMING TO
     The protocol used by Xgrid conforms to:

     o   RFC 3080 (BEEP Protocol)

     o   Apple XML property list (plist) specification

HISTORY
     Xgrid's history can be traced back to Zilla, which was developed by NeXT
     in the late 80's and was the first clustering desktop program to make use
     of the "noninterventive screen saver" motif, a motif which is now common-
     place and widely used in projects like Seti@Home.  Zilla won the 1991
     national ComputerWorld-Smithsonian Award in the science category for this
     noninterventive, community-supercomputing paradigm.

     Apple acquired the rights to Zilla in 1997, and later used that as the
     inspiration for the research project which became Xgrid.  Xgrid was pub-
     licly launched as a Technology Preview on January 6, 2004 at MacWorld San
     Francisco.

BUGS
     Xgrid is a Technology Preview, and there are many known issues.  Some
     commonly reported issues are:

     1.   There is no way for the controller to determine if an agent is
          trustworthy (only vice versa)


ERRORS
     If a job fails due to an error, the error code reported is simply the
     error code that was returned by the task (or by the system).  (For system
     error descriptions, see /usr/include/sys/errno.h.) Common errors include:

     o   Error 1: The permissions of some file are set incorrectly.

     o   Error 2: No such file exists.

     o   Error 8: The executable file wasn't actually executable.

SEE ALSO
     ssh(1)

CONFORMING TO
     The protocol used by Xgrid conforms to:

     o   RFC 3080 (BEEP Protocol)

     o   Apple XML property list (plist) specification

HISTORY
     Xgrid's history can be traced back to Zilla, which was developed by NeXT
     in the late 80's and was the first clustering desktop program to make use
     of the "noninterventive screen saver" motif, a motif which is now common-
     place and widely used in projects like Seti@Home.  Zilla won the 1991
     national ComputerWorld-Smithsonian Award in the science category for this
     noninterventive, community-supercomputing paradigm.

     Apple acquired the rights to Zilla in 1997, and later used that as the
     inspiration for the research project which became Xgrid.  Xgrid was pub-
     licly launched as a Technology Preview on January 6, 2004 at MacWorld San
     Francisco.

BUGS
     Xgrid is a Technology Preview, and there are many known issues.  Some
     commonly reported issues are:

     1.   There is no way for the controller to determine if an agent is
          trustworthy (only vice versa)

     2.   The controller always copies over the commands and working directory
          to the agent before each individual task, rather than checking to
          see if it is cached

     Bug reports can be sent to bugreport.apple.com

     Feedback can be sent to xgrid@apple.com

Mac OS                           March 5, 2004                          Mac OS
