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 [email protected]

Mac OS March 5, 2004 Mac OS