RSS

(root)/integrade : /integrade/INSTALL (revision 1180)

To get this branch, use:
bzr branch /integrade
Line Revision Contents
1 1072
InteGrade: Object-Oriented Grid Middleware v0.5
2 935
3
Installation Manual
4
5 1168.4.3
Last updated: June 23rd 2009.
6 935
7
-----------------------------------------------------------------------------
8
INTRODUCTION
9
10
InteGrade is  a middleware  platform for opportunistic  grid computing
11
being  developed as part  of a  multi-university initiative.  The main
12
goal  of InteGrade  is to  allow organizations  to use  their existing
13
computing  infrastructure  to   perform  useful  computation,  without
14
requiring   the  purchase  of   additional  hardware.   The  InteGrade
15
infrastructure preservers  the quality  of service perceived  by users
16
who share the idle portion of their resources with the grid. InteGrade
17
provides    support   for   highly-coupled    parallel   applications,
18
checkpointing, security, and an integrated development environment.
19
20
This  document  describes  the  procedures for  the  installation  and
21
configuration  of  InteGrade.   It  is   intended  to  be  used  as  a
22
step-by-step  guide for  users not  familiar with  InteGrade,  nor the
23
technologies it  leverages. This document does not,  though, cover the
24
construction of applications based on InteGrade. For information about
25
this  subject  or any  problems,  questions,  musings, or  suggestions
26
regarding  InteGrade, please  contact  the InteGrade  support team  at
27 1168.4.1
integrade-support@googlegroups.com  or  consult the  InteGrade  portal
28
(http://ccsl.ime.usp.br/integrade).
29 935
30
31
-----------------------------------------------------------------------------
32
REQUIRED PACKAGES
33
34
In  order   to  compile  and  run  InteGrade,   several  packages  are
35
required. All of  these packages are based on  open standards and most
36
are free software. The current  version of InteGrade only works on the
37
GNU/Linux  platform,  but versions  that  run  on BSD-based  operating
38
systems (such as FreeBSD and Mac OS X) and Windows are currently being
39
developed. InteGrade requires the following packages:
40
41
 - GCC  4.0  or greater  -  The GNU  C  Compiler.   Debian and  Fedora
42 1072
   packages: gcc-4.0,  gcc-4.0-base
43
44
 - G++  4.0 or  greater -  The GNU  C++ Compiler.
45 935
   Debian  and Fedora package: g++-4.0
46
47 1072
 - GNU Make  - The popular  UNIX-based build tool.
48 935
   Debian and Fedora package: make
49
50
 - JDK 1.5  or greater  - The Java  Development Kit  v1.5.0, including
51
   both the  compiler and runtime  environment for the  Java Language.
52
   Available  at  http://java.sun.com/javase/downloads/index_jdk5.jsp
53
54
 - Ant 1.5 or greater  - A Java-based platform-independent build tool.
55
   Available at http://ant.apache.org/bindownload.cgi
56
57
 - JacORB  2.2.3 -  A Java-based  open-source CORBA  ORB that  runs on
58 1072
   cluster manager machines.
59 1168.4.1
   Available  at http://ccsl.ime.usp.br/integrade/en/software
60 935
   and http://www.jacorb.org
61
62
 - OiLPack (incl.  Lua-5.0-Plus, Compat-Lua-5.1-r5, LuaSocket-2.0, and
63
   OiL 0.3.1) - A software bundle containing the compiler  and runtime
64
   for the Lua scripting language,  a library  for  building Lua-based
65
   socket applications, and the  OiL lightweight CORBA ORB, which runs
66 1072
   on resource  provider nodes.
67 1168.4.1
   Available  at http://ccsl.ime.usp.br/integrade/en/software
68 935
69
 - The  MPICH2  library,  an  implementation of  the  Message  Passing
70 1072
   Interface built by the Argonne National Laboratory, USA. This
71
   module is necessary to run MPI applications over InteGrade.
72 935
   Available at http://www-unix.mcs.anl.gov/mpi/mpich2/
73
74 1168.1.6
 - Common  error  description  library.
75
   Debian package: comerr-dev
76
77
 - Readline Library.
78
   Debian package: libreadline5-dev
79
80 935
If a  secure application repository is necessary  (this is recommended
81
for jobs running on shared  machines), the following packages are also
82
required:
83 1072
84
 - General  purpose  cryptographic  C++  library.
85 935
   Debian  package: libcrypto++-dev
86
87
 - Kerberos with  all libraries and header files.
88
   Debian   packages:   libkrb5-dev,   krb5-user,   krb5-admin-server,
89
   krb5-kdc
90
91
All of these  packages must be installed before  attempting to compile
92
InteGrade. The packages  are listed in the order  in which they should
93
be installed.  The  first four packages are often  included in default
94
installations of  GNU/Linux. If this  is not the  case, it is  easy to
95
obtain and  install them if you  have an Internet  connection and root
96
access. Linux distributions  based on Debian (such as  Ubuntu) and Red
97
Hat  (such as  Fedora)  include specific  utilities for  automatically
98
downloading and installing applications. Also, all the packages can be
99
easily  obtained in  the Web.  See  the appendix  for instructions  on
100
obtaining the packages, if they are not available in your system.
101
102
103
-----------------------------------------------------------------------------
104
OBTAINING AND COMPILING INTEGRADE
105
106
The latest  version of  InteGrade can be  obtained from  the InteGrade
107
portal,                 at                 the                 address
108 1168.4.1
http://ccsl.ime.usp.br/integrade/en/software.   As  of  June 2009, the
109
current   version   of   InteGrade  is   0.5. After   downloading  the 
110
distribution  (package integrade-0.3-rc1.tar.gz), you  must unpack it:
111
112
  $ tar -zxvf ig-0.5RC1.tar.gz
113
114
This command  will unpack InteGrade in a  directory named `ig-0.5RC1'.
115
From now on this will be InteGrade root directory.
116 935
117
In  the rest  of this  section,  we describe  the steps  to setup  and
118
compile  InteGrade.  Initially, we  do not  take security  issues into
119
account. Later in the document,  we describe how to build InteGrade so
120
that it uses a secure Kerberos-based Application Repository. We do not
121 1168.4.1
recommend  the use  of  InteGrade in  real-life  projects without  the
122 935
secure Application Repository activated.
123
124
The  setup.sh script  will help  you on  configuring  InteGrade.  This
125 1168.4.1
script is  located in InteGrade's root directory. To setup
126 935
InteGrade,  go  to the  InteGrade  directory  and  choose one  of  two
127
options:
128
129
 (a)  Run setup.sh  without any  arguments and  answer  some questions
130
     about the locations of  the required packages.  Additionally, the
131
     script will  ask you if the  current machine will be  acting as a
132
     server. Answer  'y' if you intend  to run the GRM  on the current
133
     node. The information you provide will be saved on the setup.conf
134
     file to be used by the build procedure.
135
136
 (b) You can  directly edit the setup.conf file and  tailor it to your
137
     environment.  If a secure application repository is not required,
138
     leave  properties  kerberosDomain  and kerberosConfigPath  blank.
139
     After  assigning  the appropriate  values  to  the properties  in
140
     setup.conf, execute the following command:
141 1072
142 1168.4.2
  $ ./setup.sh --file setup.conf
143 935
144 1072
More information can be found by running
145 935
146 1168.4.2
  $ ./setup.sh --help.
147 935
148 1168.4.1
To compile all the InteGrade modules, setup the environment and execute
149
make in InteGrade root directory:
150 935
151 1168.4.1
   $ source ./startservices.sh env
152 935
   $ make all
153
154
After this, InteGrade is ready to be executed.
155
156
-----------------------------------------------------------------------------
157
LAUNCHING INTEGRADE
158
159
To execute InteGrade,  you need to start at  least one Global Resource
160
Manager (GRM, runs on the nodes responsible for managing the grid) and
161
one  or  more Local  Resource  Managers  (LRMs,  run on  the  resource
162
provider  nodes). Several  LRMs can  be  started using  a single  GRM.
163
Additionally, in order to submit jobs  to the grid, it is necessary to
164
initialize the ASCT (Application Submission and Control Tool).  Before
165
launching the  InteGrade modules, make  sure that all  the environment
166
variables that InteGrade  requires are set.  You can  do this by going
167 1168.4.1
to the  InteGrade root directory  and  loading the  settings   in  the
168 935
startservices.sh file:
169
170 1170.1.10
  $ source ./startservices.sh env
171 935
172 1170.1.10
It is  recommended  to write the source  command (with  full path)  in
173
~/.bashrc,  so next time  you login  you won't  need to run it  again.
174 935
After this, you can start InteGrade services with the startservices.sh
175
script. To start  up a global resource manager in  one of the machines
176 1072
(where  you   will  start  all  servers),   type:
177 935
178
  $ ./startservices.sh servers
179
180
As previously mentioned, several machines can act as LRMs based on the
181
same GRM.  The  easiest way to do  this is to simply log  onto each of
182
these  machines  using SSH  and  activating the  LRM  in  each one  of
183
them. To start the LRM, on the InteGrade directory, type:
184
185 1168.4.2
  $ ./startservices.sh client
186 935
187
In each  machine that  will be used  for submitting  applications that
188
will execute on the grid, type:
189 1072
190 935
  $ ./startservices.sh asctGui
191
192
This command will  present the ASCT GUI, which  allows users to submit
193
jobs to the grid, set  input arguments, access the output produced the
194
the execution  of the jobs, and  define the type of  application to be
195
executed.   InteGrade  currently  supports  four  different  types  of
196
applications:  (i) Regular (single-threaded),  used only  for testing;
197
(ii) parametric  (or bag-of-tasks), for parallel  applications that do
198
not  require communication amongst  processes; (iii)  Bulk Synchronous
199
Parallel  (BSP),  for highly  coupled  applications  that need  strong
200
synchronization; and (iv) Message Passing Interface (MPI), for general
201
highly  coupled applications.  In  the following  two sections,  we'll
202
learn  how  to  execute   regular  and  BSP  applications.  The  other
203
app. types work in a similar vein.
204
205 1168.4.2
You    can   stop   InteGrade  in  a  similar way,  using  the  script 
206
stopservices.sh, for instance:
207
208
  $ ./stopservices.sh all
209
210 935
-----------------------------------------------------------------------------
211
EXECUTING A NON-PARALLEL APPLICATION
212
213
We will test the execution  of regular applications on InteGrade using
214
a very  simple example based on  the UNIX 'ls' command.   In the ASCT,
215
right-click the  root character ('/') that  appears under "Application
216
Repository"  and left-click the  option "Register  Application".  Then
217
enter a name for the application you're registering (e.g.  "LS", "ls",
218
"List", you get the picture).  Right-click the name of the application
219
you  just entered  (let's assume  it's "List")  and choose  the option
220
"Upload Binary".  A  text field will then appear  and you should enter
221
"/bin/ls"  (the  path  for  the   "ls"  UNIX  command)  and  click  on
222 1072
``Upload''.
223 935
224
To  run the  test,  Right-click  the second  item  below "List"  (e.g.
225
"Linux_i686", depending on the machine and OS where you're running the
226
application)   and   left-click   "Execute".    A  new   window   will
227
appear. Choose  ``Regular'' as the application type.  Also, type "-la"
228
on  the "Arguments"  text field  and  mark the  "stderr" and  "stdout"
229
checkboxes that appear under  ``Output Files''. Then click on "Submit"
230
and a  new item  labeled "List"  will appear in  the main  ASCT window
231
under "Requested  Executions".  Wait for  the label to turn  green and
232
then right-click it and left-click  "View Results".  A new window will
233
pop-up. On the left-hand pane, there's only one item: "Node1". This is
234
expected,  since   the  application  you  just   executed  is  regular
235
(non-parallel) and  only uses one node. Double-click  "Node1" and then
236
click  on "stdout".  The  pane on  the right-hand  side will  show the
237
results of the "ls" command.
238
239
240
-----------------------------------------------------------------------------
241
EXECUTING A PARALLEL APPLICATION
242
243
To execute a parallel application,  one should follow the same overall
244
steps as a  regular application. To illustrate this,  we will show how
245
to execute  the matrix multiplication application that  is included in
246 1168.4.1
the   InteGrade    distribution,   under   examples/bsp/matrix.   This 
247 935
application  randomly  generates  two   square  n  x  n  matrices  and
248
multiplies them a certain number of times. To execute it on InteGrade,
249
it  is necessary  to  first compile  the  sources that  come with  the
250
InteGrade distribution.  Since this  application uses the BSP model of
251
parallel programming, we  need to compile it using  a special compiler
252
targeting this  communication model. This compiler is  included in the
253 1168.4.1
InteGrade distribution, under libs/bspLib/.
254 935
255
Go       to       the       matrix      multiplication       directory
256 1168.4.1
(examples/bsp/matrix)  and  compile  the  example  with  the following
257
command in InteGrade root directory:
258 935
259 1168.4.1
  $ ./libs/bspLib/bspcc.sh matrix.c -o matrix
260 935
261
Now, if  you haven't done  it yet, execute  the GRM, the LRM,  and the
262
ASCT. Since this is a  parallel application, you might want to execute
263
it using  two or  more machines.  Remember  that, to run  an InteGrade
264
application on  multiple nodes,  you simply start  the LRM in  all the
265
nodes you  want to use  as service providers.   The easiest way  to do
266
this is to ssh these machines and, using the same code base from which
267
you started  the GRM, start the LRM  in each one of  them. Notice that
268
this also  applies to the ASCT.   It is straightforward  to execute it
269
from  a  machine  where neither  the  GRM  nor  LRMs are  runnning  by
270
following the same steps.
271
272
To  execute the  matrix multiplication,  on the  ASCT, register  a new
273
application named "Matrix", upload the binary you just generated whose
274
full  path  is  $IG_HOME/examples/bsp/matrix/matrix, and  execute  the
275
application. For  the Application  Type, choose "BSP".   You'll notice
276
that a new text field labeled "Number of Tasks" appears.  Enter "4" in
277
this field.  In the "Arguments" field,  enter "4 100 10", where '4' is
278
the number of concurrent (or parallel,  in case you create two or more
279
LRMs running  on different machines)  processes that will  execute the
280
application, '100' means  that the matrices will be  100x100, and '10'
281
is the number of times they are multiplied. Mark the stderr and stdout
282
checkboxes in  order to be able  to visualize the  results and submit
283 1072
the application.
284 935
285
You can view the resulsts just  like you did for the "ls" application.
286
Four different tasks  (labeled Node1-4) are listed on  the window that
287
shows  the execution  results for  the matrix  multiplication example.
288
Notice  that, even  though these  tasks  are labeled  NodeX, they  are
289
actually just process  that might not have been  executed in different
290
machines, depending on  the number of LRMs you  initiated. If you look
291
at the "stdout" part of the output, you'll notice that it mentions the
292
name of  the machine where each  task was run. This  is useful because
293
InteGrade's users  cannot control how  InteGrade's scheduler allocates
294
tasks to nodes, assuming that more than one node is available.
295
296
297
-----------------------------------------------------------------------------
298 1072
EXECUTING AN APPLICATION IN TEXT-MODE
299
300
You  can  also  start  jobs  without  the  graphical  interface.  After
301
following the  compilation steps  detailed in  the previous section, go
302
to the InteGrade's directory and type:
303
304
  $./startservices.sh asctText -b $IG_HOME/examples/bsp/matrix/matrix
305
-i $IG_HOME/examples/bsp/matrix/matrix.conf
306
307
The -b value  is the path  of the binary  you want  to execute, and the
308
-i is the path  to the execution  descriptor file, which can be created
309
by clicking in the Save button in AsctGui.
310
311
312
-----------------------------------------------------------------------------
313 935
RUNNING INTEGRADE WITH A SECURE APPLICATION REPOSITORY
314
315
InteGrade provides users with a persistent Application Repository that
316
saves the state of the applications that each user registers.  In this
317
manner, a  user does not  have to re-register applications  he/she has
318
previously executed  on InteGrade.  Since the  users of a  grid may be
319
unwilling  to make  the state  of their  applications public  to other
320
users, InteGrade's Application Repository  can be executed in a secure
321
mode, using the Kerberos authentication  protocol. In the rest of this
322
section,  we briefly  explain how  to run  InteGrade using  the secure
323
Application Repository.  If you need further explanations, contact the
324 1168.4.3
InteGrade team at integrade-support@googlegroups.com.
325 935
326
First and foremost:  If you choose to enable  security support for the
327
Application Repository, you have  to install and configure Kerberos (a
328
3rd.   party  software)  before  attempting  to  configure  InteGrade.
329
Kerberos  is developed  by a  MIT group  and all  required information
330
about it can be found at http://web.mit.edu/kerberos.
331
332
To enable the secure Application  Repository, you will have to setup a
333
kerberos  realm in  your network  and create  at least  one  user with
334
administration priveilegies.  After that, execute setup.sh and respond
335
``y''  to the  question  about  security.  The  script  will ask  some
336
questions about  how you  have set up  your Kerberos  environment, and
337
will create all  the necessary groups under your  realm.  Now you need
338
to create the users (using kadmin) that will have access to InteGrade.
339
The users  must belong to  the group ARSC,  and so they have  the form
340
``username/ARSC@Realm``.  After  that you can  recompile InteGrade. To
341
run InteGrade  using a secure Application Repository,  it is necessary
342
to first have the Kerberos realm working.
343
344
345
-----------------------------------------------------------------------------
346
APPENDIX - OBTAINING THE REQUIRED PACKAGES
347
348
To install  GCC, G++, and  Make in a Debian-based  Linux distribution,
349
make  sure  that you  have  root  privileges  and type  the  following
350
commands in the terminal:
351
352
  $ apt-get install gcc-4.0
353
  $ apt-get install g++
354
  $ ant-get install make
355
356
For Red Hat and Fedora, use the yum utility instead:
357
358
  $ yum install gcc-4.0
359
  $ yum install g++
360
  $ yum install make
361
362
Other Linux  distributions provide  different means for  obtaining and
363
installing     these      packages.      Contact     the     InteGrade
364 1168.4.3
(integrade-support@googlegroups.com) team for more information.
365 935
366
To install the JDK 1.5.0, we suggest you download it directly from the
367
Sun website.  Choose the self-extracting package  (.bin extension), as
368
it does not  depend on Linux distribution-specific tools  and does not
369
require    root   privileges.    After    you   download    the   file
370
jdk-1_5_0_<version>-linux-i586.bin  (replace   `<version>'  by  the
371
version number), assuming  it was saved in the  current directory, set
372
the file permissions in order for  it to be executable and execute it.
373
For  example,  if  you  downloaded  JDK  1.5.0  Update  11,  type  the
374
following:
375
376
  $ chmod u+x jdk-1_5_0_11-linux-i586.bin
377
  $ ./jdk-1_5_0_11-linux-i586.bin
378 1072
379 935
Simply type `yes' when the program  asks if you agree with the license
380
agreement  and  JDK  will  be  installed in  your  system.   For  more
381
information      on      installing      the      JDK,      go      to
382
http://java.sun.com/j2se/1.5.0/install-linux.html#self-extracting.
383
After installation,  you need  to modify your  system settings.  Use a
384
text editor such  as pico, vim, or emacs to edit  the .bashrc file. We
385
will, from now on, assume that you are unpacking all the packages in a
386
directory named /home/user. In case you don't know the directory where
387
you are, type
388
389 1072
  $ pwd
390 935
391
and the  shell will  display the name  of the current  directory.  Use
392
that name  instead of /home/user  wherever we use  the latter in
393
the  rest of the  text.  After  installing the  JDK, modify  your user
394
settings in order for Java to  be accessible from any directory in the
395
system.  To  do this, edit the  .bashrc file  (assuming that you
396 1072
are using the bash shell) by typing:
397 935
398
  $ pico ~/.bashrc
399
400
When the text  editor screen appears, go to the  line that starts with
401
`export PATH' and add
402
403 1072
  :/home/user/jdk-1.5.0_11/bin
404 935
405
at the end of that line.  Moreover, add the following two lines at the
406
end of the file:
407
408 1072
  export CLASSPATH=$CLASSPATH:/home/user/jdk1.5.0_01/jre/lib/rt.jar
409 935
  export JAVA_HOME=/home/user/jdk1.5.0_11/
410
411
After  applying these modifications,  save them  and exit  the editor.
412
Then type
413
414 1072
  $ source ~/.bashrc
415 935
416
for them to take effect.
417
418 1168.4.3
To install Ant,  download the current version from  the website. Using
419
the 1.7.0 version as example, download the file
420 935
apache-ant-1.7.0-bin.tar.gz and unpack it as follows:
421
422
  $ tar -xzvf apache-ant-1.7.0-bin.tar.gz
423
424
Assuming Ant was unpacked in  the /home/user/ directory, edit the file
425
.bashrc and include
426
427
  :/home/user/apache-ant-1.7.0/bin
428
429
at the  end of the `export PATH'  line, similarly to what  you did for
430
the JDK. Moreover, add the following line at the end of the file:
431
432
  export ANT_HOME=/home/user/apache-ant-1.7.0/
433
434 1072
Again, after editing the .bashrc file, type
435 935
436
  $ source ~/.bashrc
437
438
for the changes to take effect.
439
440
Installing  JacORB  is then  a  simple  process.   First download  its
441
distribution.  Then, assuming it was download in directory /home/user,
442
type the following:
443
444 1072
  $ tar -zxvf JacORB-2.2.3-source.tar.gz
445
  $ cd JacORB-2.2.3
446
  $ ant
447 935
  $ cd  ..
448
449
InteGrade  also  requires  the  OiLPack,  a package  that  includes  a
450
compiler and a runtime for  the Lua programming language, the OiL ORB,
451
a lightweight ORB that runs on the grid's resource provider nodes, and
452
LuaSocket, a library providing  support for socket programming in Lua.
453
Download the current version of OiLPack and unpack it as follows:
454
455
  $ tar -zxvf oilpack.tar.gz
456
457
The version  of OiL's distribution available in  the InteGrade website
458
includes a  script, install.sh, that  automatically installs all
459
the components of  OiLPack. Simply execute the script  and provide the
460
full path where the contents of the package will be installed:
461
462
  $ cd oilpack
463
  $ install.sh
464
  This script will configure compile and install lua-5.0.2 with:
465
     -> compat-5.1r5
466
     -> luasocket-2.0-beta3
467
     -> oil-0.3.1-alpha
468
469
  Enter the full path where you want to install lua-5.0.2:
470
471
When the last sentence above  appears, enter the name of the directory
472
where Lua will be installed, for example, /home/user/lua-5.0.2.
473
474
Finally, for instructions on how to install the MPICH2 library, take a
475
look at the  MPICH2 Installer's Manual. This document  is available at
476
the following URL:
477
478
http://www-unix.mcs.anl.gov/mpi/mpich2/downloads/mpich2-doc-install.pdf
479
480
-----------------------------------------------------------------------------
481
482

Loggerhead 1.17 is a web-based interface for Bazaar branches