Manual Pages for UNIX Darwin command on man xgrid

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

NAME

xxggrriidd - submit and monitor xgrid jobs

SYNOPSIS

xxggrriidd [-hh[[oossttnnaammee]] hostname] [-aauutthh { Password | Kerberos }]

[-pp[[aasssswwoorrdd]] password] [-ff[[oorrmmaatt]] xxmmll]

xxggrriidd -jjoobb run [-ggiidd grid-identifier] [-ssii stdin] [-iinn indir]

[-ssoo stdout] [-ssee stderr] [-oouutt outdir] [-eemmaaiill email-address]

[-aarrtt art-path -aarrttiidd art-identifier] [-aarrtteeqquuaall art-value]

[-aarrttmmiinn art-value] [-aarrttmmaaxx art-value] cmd [arg1 [...]]

xxggrriidd -jjoobb submit [-ggiidd grid-identifier] [-ssii stdin] [-iinn indir]

[-ddiiddss jobid [, jobid]*] [-eemmaaiill email-address]

[-aarrtt art-path -aarrttiidd art-identifier] [-aarrtteeqquuaall art-value]

[-aarrttmmiinn art-value] [-aarrttmmaaxx art-value] cmd [arg1 [...]]

xxggrriidd -jjoobb batch [-ggiidd grid-identifier] xml-batch-file

xxggrriidd -jjoobb results -iidd identifier [-ssoo stdout] [-ssee stderr] [-oouutt outdir]

[-ttiidd task-identifier]

xxggrriidd -jjoobb {stop | suspend | resume | delete | restart} -iidd identifier

xxggrriidd -jjoobb {attributes | specification | log | wait} -iidd identifier

xxggrriidd -jjoobb list [-ggiidd grid-identifier]

xxggrriidd -ggrriidd list

xxggrriidd -ggrriidd attributes -ggiidd identifier

OOPPTTIIOONNSS The available options are as follows:

-hh[[oossttnnaammee]] hostname the hostname or IP address of the

controller - if not present, xgrid

will use the value specified in

XGRIDCONTROLLERHOSTNAME

-aauutthh { Password | Kerberos } Default is Password. If Kerberos,

then use or obtain a kerberos ticket

to authenticate to the Xgrid con-

troller

-pp[[aasssswwoorrdd]] password if the controller requires a password

(as is the default), the password must be specified here or in XGRIDCONTROLLERPASSWORD

-iidd identifier the xgrid identifier for the job of

interest (not used when submitting a job)

-ggiidd grid-identifier the xgrid identifier for logical grid

of interest

-jjoobb {list | attributes} retrieve list of, or attributes of a

job

-jjoobb stop stop job execution but don't delete

job

-jjoobb suspend suspend execution of the job (i.e. do

not schedule any pending tasks)

-jjoobb resume resume execution of the job - any

pending tasks may now be scheduled

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

and delete job

-jjoobb results retrieve results of job previously

submitted

-jjoobb specification retrieve specification used when sub-

mitting job

-jjoobb restart restart a running or stopped job from

the beginning

-jjoobb {submit | run} cmd arg1 ... specify a command (with arguments) to

either run synchronously or submit asynchronously

-ssii stdin for submit/run, file to use for stan-

dard input

-iinn indir for submit/run, working directory to

submit with job

-ssoo stdout for run/results, file to write the

standard output stream to

-ssee stderr for run/results, file to write the

standard error stream to

-oouutt outdir for run/results, directory to store

job results in

-ddiiddss jobid [, jobid]* do not schedule this job for execu-

tion until the list of dependent jobs have successfully Finished.

-eemmaaiill email-address email address to send job state

change notifications (i.e. "Finished" or "Cancelled")

-ggrriidd list list identifiers of all logical grids

-ggrriidd 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

XGRIDCONTROLLERHOSTNAME gives the hostname or IP address of the con-

troller XGRIDCONTROLLERPASSWORD 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 EEXXAAMMPPLLEESS 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 XGRIDCONTROLLERHOSTNAME mycomputer.apple.com

% setenv XGRIDCONTROLLERPASSWORD pword

Set environment variables for the following examples (bash):

$ export XGRIDCONTROLLERHOSTNAME=mycomputer.apple.com

$ export XGRIDCONTROLLERPASSWORD=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

BBaattcchh ffiillee eexxaammpplleess

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 samplebatch.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

command /bin/echo

environment MYENVVARIABLE MYVALUE

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

EERRRROORRSS 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: ++oo Error 1: The permissions of some file are set incorrectly. ++oo Error 2: No such file exists. ++oo Error 8: The executable file wasn't actually executable.

xgridctl(8) ssh(1)

CCOONNFFOORRMMIINNGG TTOO The protocol used by Xgrid conforms to: ++oo RFC 3080 (BEEP Protocol) ++oo 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 June 27, 2007 Mac OS