xgrid(1) BSD General Commands Manual xgrid(1)
NAME
xgrid -- submit and monitor xgrid jobs
SYNOPSIS
xgrid [-h[ostname] hostname] [-auth { Password | Kerberos }]
[-p[assword] password]
xgrid -job run [-gid grid-identifier] [-si stdin] [-in indir]
[-so stdout] [-se stderr] [-out outdir] [-email email-address] cmd
[arg1 [...]]
xgrid -job submit [-gid grid-identifier] [-si stdin] [-in indir]
[-dids jobid [, jobid]*] [-email email-address] cmd [arg1 [...]]
xgrid -job batch [-gid grid-identifier] xml-batch-file
xgrid -job results -id identifier [-so stdout] [-se stderr] [-out outdir]
xgrid -job {stop | suspend | resume | delete | specification | restart}
-id identifier
xgrid -job list [-gid grid-identifier]
xgrid -job attributes -id identifier
xgrid -grid list
xgrid -grid attributes -gid 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
-auth { Password | Kerberos } Default is Password. If Kerberos,
then use or obtain a kerberos ticket
to authenticate to the Xgrid con-
troller
-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 of
interest (not used when submitting a
job)
-gid grid-identifier the xgrid identifier for logical grid
of interest
-job {list | attributes} retrieve list of, or attributes of a
job
-job stop stop job execution but don't delete
job
-job suspend suspend execution of the job (i.e. do
not schedule any pending tasks)
-job resume resume execution of the job -- any
pending tasks may now be scheduled
-job delete stop job execution (if it is running)
and delete job
-job results retrieve results of job previously
submitted
-job specification retrieve specification used when sub-
mitting job
-job restart restart a running or stopped job from
the beginning
-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
-dids jobid [, jobid]* do not schedule this job for execu-
tion until the list of dependent jobs
have successfully Finished.
-email email-address email address to send job state
change notifications (i.e. "Finished"
or "Cancelled")
-grid list list identifiers of all logical grids
-grid attributes retrieve attributes of the specified
logical grid
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
/etc/xgrid/agent/controller-password
Password that the agent may require the controller to have (only
readable by root)
/etc/xgrid/controller/agent-password
Password that the controller may be required by the agent to have
(only readable by root)
/etc/xgrid/controller/client-password
Password that the controller may require the client to have (only
readable by root)
/Library/Preferences/com.apple.xgrid.controller.plist
Controller preferences file
/etc/xgrid/controller/com.apple.xgrid.controller.plist.default
Commented sample of all controller preferences
/Library/Preferences/com.apple.xgrid.agent.plist
Agent preferences file
/etc/xgrid/agent/com.apple.xgrid.agent.plist.default
Commented sample of all agent preferences
EXAMPLES
List all grids and specify hostname and password:
$ xgrid -h mycomputer.apple.com -p pword -grid list
(0, 1)
Show information about grid 0:
$ xgrid -h mycomputer.apple.com -p pword -grid attributes -gid 0
{isDefault = YES; name = Xgrid; }
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 attributes for one of the jobs:
$ xgrid -job list
{ jobArray = ({ jobIdentifier = 26; } ); }
$ xgrid -job attributes -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 2005
Submit myscript with the files in the input directory. Send email to
somebody@apple.com on every job state change. Then retrieve the results
and save the stdout and stderr streams in files instead of printing them
out to the terminal and save the output files in the specified directory.
Finally delete the job:
$ xgrid -job submit -in ~/data/working -email somebody@apple.com
myscript param1 param2
{ jobIdentifier = 27; }
$ xgrid -job results -id 27 -so job.out -se job.err -out job-outdir
$ xgrid -job delete -id 27
Batch file examples
Complex multi-job specification may be submitted via an XML batch prop-
erty list. Batch file job specifications are submitted as follows:
$ xgrid -job batch sample_batch.xml
The following XML plist submits a simple /usr/bin/cal job:
name
Cal Job
taskSpecifications
0
command
/usr/bin/cal
arguments
6
2005
A list of all XML batch submission properties follows:
name
Full Job
notificationEmail
somebody@example.com
schedulerParameters
tasksMustStartSimultaneously
YES
minimumTaskCount
5
dependsOnJobs
23
44
inputFiles
textfile
fileData
dGhpcyBpcyBhIHRlc3Q=
isExecutable
NO
task1/textfile
fileData
dGhpcyBpcyBhIHRlc3Q=
taskPrototypes
echoTask
command
/bin/echo
arguments
echoTask Arguments
are here
taskSpecifications
0
command
/bin/echo
environment
MY_ENV_VARIABLE
MY_VALUE
arguments
HelloWorld
inputStream
textfile
dependsOnTasks
1
1
taskPrototypeIdentifier
echoTask
arguments
Task 1
inputFileMap
textfile
task1/textfile
name
Calendar Job
taskSpecifications
0
command
/usr/bin/cal
arguments
6
2005
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:
· Error 1: The permissions of some file are set incorrectly.
· Error 2: No such file exists.
· Error 8: The executable file wasn't actually executable.
SEE ALSO
xgridctl(8) ssh(1)
CONFORMING TO
The protocol used by Xgrid conforms to:
· RFC 3080 (BEEP Protocol)
· 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
Some commonly reported issues are:
1. 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 January 25, 2005 Mac OS