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] [-f[ormat] { plain | xml }]
[-failover { YES | NO }] [-autocopy { YES | NO }]
xgrid -job run [-gid grid-identifier] [-si stdin] [-in indir]
[-so stdout] [-se stderr] [-out outdir] [-email email-address]
[-art art-path [-artid art-identifier]] [-artequal art-value]
[-artmin art-value] [-artmax art-value] cmd [arg1 [...]]
xgrid -job submit [-gid grid-identifier] [-si stdin] [-in indir]
[-dids jobid[,jobid[,...]]] [-email email-address]
[-art art-path [-artid art-identifier]] [-artequal art-value]
[-artmin art-value] [-artmax art-value] cmd [arg1 [...]]
xgrid -job batch [-gid grid-identifier xml-batch-file]
xgrid -job results -id identifier [-so stdout] [-se stderr] [-out outdir]
[-tid task-identifier]
xgrid -job { stop | suspend | resume | delete | restart } -id identifier
xgrid -job { attributes | specification | log | wait } -id identifier
xgrid -job list [-gid grid-identifier]
xgrid -grid list
xgrid -grid attributes -gid identifier
xgrid -controller { list | role }
xgrid -controller { promote | autopromote } [-role { MASTER | PASSIVE }]
GLOBAL OPTIONS
-h[ostname] hostname hostname or IP address of the con-
troller (default is :user:)
-auth { Password | Kerberos } authentication method to use (default
is Password)
-p[assword] password password to use if the Password
authentication method is chosen
-f[ormat] { plain | xml } format to write output in (default is
plain)
-failover { YES | NO } enable or disable failover (default
is YES)
-autocopy { YES | NO } enable or disable autocopy (default
is YES)
ACTIONS
-job run cmd [arg1 [...]] specify a command (with arguments) to
run and retrieve results for syn-
chronously
-job submit cmd [arg1 [...]] specify a command (with arguments) to
submit asynchronously
-job batch xml-batch-file specify a batch file containing a
list of job specifications to submit
asynchronously
-job results retrieve results of job previously
submitted
-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 restart restart a running or stopped job from
the beginning
-job attributes retrieve attributes of a job
-job specification retrieve specification of a job
-job log retrieve log of a job
-job wait wait synchronously until job state
changes
-job list retrieve list of jobs
-grid list list identifiers of all logical grids
-grid attributes retrieve attributes of a grid
-controller list retrieve list of failover controllers
-controller role retrieve role of controller
-controller promote promote the controller to the speci-
fied role
-controller autopromote promote the controller (or first
available failover controller) to the
specified role
ACTION PARAMETERS
-id identifier identifier for the job of interest
-gid grid-identifier identifier for grid of interest
-si stdin file to use for standard input
-in indir working directory to submit with job
-so stdout file to write the standard output
stream to
-se stderr file to write the standard error
stream to
-out outdir 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
-art art-path the agent ranking tool to use to rank
the agents (the tool must be exe-
cutable and will be copied to agents)
-artid art-identifier identifier that uniquely identifies
the agent ranking tool
-artequal art-value restrict tasks to only run on agents
for which the agent ranking tool
returns the specified art-value
-artmax art-value restrict tasks to only run on agents
for which the agent ranking tool
returns a value no more than the
specified art-value
-artmin art-value restrict tasks to only run on agents
for which the agent ranking tool
returns a value no less than the
specified art-value (default is 1 if
none of artequal, artmax, or artmin
are specified)
-role { MASTER | PASSIVE } the role to change the controller to
(default is MASTER)
EXAMPLES
Submit a simple job to the default grid:
$ xgrid -job submit /usr/bin/cal
{ jobIdentifier = 0; }
List all jobs in the default grid:
$ xgrid -job list
{ jobList = (0); }
Show information about job 0:
$ xgrid -job attributes -id 0
{ jobAttributes = {...}; }
Submit myscript with the files in the input directory, wait for the job
state to change, then retrieve the results and save the stdout and stderr
streams to files, save the output files to the specified directory, and
then delete the job:
$ xgrid -job submit -in ~/data/working myscript param1 param2
{ jobIdentifier = 1; }
$ xgrid -job wait -id 1
{ jobStatus = Finished; }
$ xgrid -job results -id 1 -so job.out -se job.err -out job-outdir
$ xgrid -job delete -id 1
$ { }
Do the same thing as the previous example but use run instead of sub-
mit/wait/results/delete:
$ xgrid -job run -in ~/data/working -so job.out -se job.err -out
job-outdir myscript param1 param2
Submit a batch of job specifications from a property list file:
$ xgrid -job batch jobs.plist
Re-submit an existing job by retrieving the specification and piping it
back to batch using the special filename '-':
$ xgrid -job specification -id 0 | xgrid -job batch -
JOB SPECIFICATIONS
The following property list specifies a simple /usr/bin/cal job:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
<dict>
<key>name</key>
<string>cal 6 2005</string>
<key>taskSpecifications</key>
<dict>
<key>0</key>
<dict>
<key>command</key>
<string>/usr/bin/cal</string>
<key>arguments</key>
<array>
<string>6</string>
<string>2005</string>
</array>
</dict>
</dict>
</dict>
</array>
</plist>
The following property list demonstrates the usage of many of the avail-
able batch job options:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
<dict>
<!-- A symbolic name of the job -->
<key>name</key>
<string>Full Job</string>
<!-- Notification of all job state changes will be sent to this email address -->
<key>notificationEmail</key>
<string>somebody@example.com</string>
<key>schedulerParameters</key>
<dict>
<!-- do not schedule this job until the following job (id's) have finished successfully -->
<key>dependsOnJobs</key>
<array>
<string>23</string>
<string>44</string>
</array>
</dict>
<key>inputFiles</key>
<dict>
<!-- the file 'textfile1' will be created on agent machines in the working directory -->
<key>textfile1</key>
<dict>
<!-- include the base64 encoded file data inline -->
<key>fileData</key>
<!-- 'this is a test' -->
<data>dGhpcyBpcyBhIHRlc3Q=</data>
<!-- should this file have the executable bit set? -->
<key>isExecutable</key>
<string>NO</string>
</dict>
<!-- the file 'textfile2' will be created on agent machines in the sub-directory 'task1' of the working directory -->
<key>task1/textfile2</key>
<dict>
<!-- read file data from the specified path on the local host and include it with the job submission -->
<key>filePath</key>
<data>path/to/data</data>
</dict>
</dict>
<!-- define some prototype task specifications. Here we can define sets of common parts of taskSpecifications -->
<!-- Any taskSpecifications settings are valid. -->
<key>taskPrototypes</key>
<dict>
<key>echoTask</key>
<dict>
<key>command</key>
<string>/bin/echo</string>
<key>arguments</key>
<array>
<string>echoTask Arguments</string>
<string>are here</string>
</array>
</dict>
</dict>
<!-- specifications of all tasks of this job -->
<key>taskSpecifications</key>
<dict>
<!-- key is symbolic task name -->
<key>0</key>
<dict>
<!-- command to execute -->
<key>command</key>
<string>/bin/echo</string>
<!-- environment dictionary -->
<key>environment</key>
<dict>
<key>MY_ENV_VARIABLE</key>
<string>MY_VALUE</string>
</dict>
<!-- argument array -->
<key>arguments</key>
<array>
<string>HelloWorld</string>
</array>
<!-- use the given file as <stdin> -->
<key>inputStream</key>
<string>textfile</string>
<!-- do not start this task until the following tasks (symbolic names) have finished successfully -->
<key>dependsOnTasks</key>
<array>
<string>1</string>
</array>
</dict>
<key>1</key>
<dict>
<!-- by default use the echoTask prototype settings -->
<key>taskPrototypeIdentifier</key>
<string>echoTask</string>
<!-- override the prototype setting for arguments -->
<key>arguments</key>
<array>
<string>Task 1</string>
</array>
<!-- map a subset of files in the 'inputFiles' section for this task only -->
<key>inputFileMap</key>
<dict>
<key>textfile</key>
<string>task1/textfile2</string>
</dict>
</dict>
</dict>
</dict>
<!-- a completely different job -->
<dict>
<key>name</key>
<string>Calendar Job</string>
<key>taskSpecifications</key>
<dict>
<key>0</key>
<dict>
<key>command</key>
<string>/usr/bin/cal</string>
<key>arguments</key>
<array>
<string>6</string>
<string>2005</string>
</array>
</dict>
</dict>
</dict>
</array>
</plist>
AUTOCOPY
By default xgrid will attempt to include all of the necessary files with
the job submission. xgrid examines the job command and each argument to
determine which ones refer to local files. If the command or argument is
not an absolute path and refers to a file that exists on the local disk
then it will get included with the job submission. This behavior can be
turned off using the -autocopy NO option.
RETURN VALUES
Prints the job identifier when a job is submitted.
Returns 0 if command completed successfully.
ENVIRONMENT
XGRID_CONTROLLER_HOSTNAME
hostname to use by default if -h[ostname] is not specified
XGRID_CONTROLLER_PASSWORD
password to use by default if -p[assword] is not specified
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
/Library/Preferences/com.apple.xgrid.agent.plist
Agent preferences file
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
xgridctl(8) 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
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 X June 27, 2007 Mac OS X
Mac OS X 10.7 - Generated Wed Aug 10 19:03:50 CDT 2011