import repository from arizona
[raven.git] / webpage / tutorial-walkthrough.html
1 <html>
2 <head>
3 <title>Stork Project - Tutorial - Walkthrough</title>
4 <LINK href="stork.css" rel="stylesheet" type="text/css">
5 <style type="text/css">
6         code.shell {
7                 padding : 0.8em;
8                 display : block;
9                 background : #EFEFFA;
10                 white-space : pre;
11         }
12         code.block {
13                 padding : 0.6em;
14                 display : block;
15                 background : #FFFCD4;
16                 white-space : pre;
17         }
18 </style>
19 </head>
20
21 <body>
22
23
24 <div class="display" align="center">
25         <table border="0">
26         <tr>
27                 <td width="170" valign="top">
28
29                                 <br/>
30                                 <table cellpadding="3" width="170" id="links" class="links">
31                                         <tr>
32                                                 <td align="right">
33
34                                                         <ul class="links">
35
36                                                                 <a href="index.html"><h3>Stork</h3></a>
37                                                                 <li class="links"><a href="tutmain.html">Stork Tutorial</a></li>
38
39                                                                 <li class="links"><a href="advanced.html">Advanced Usage</a></li>
40                                                                 <li class="links"><a href="arch.html">Stork Architecture</a></li>
41                                                                 <li class="links"><a href="filelist.html">Stork File List</a></li>
42                                                                 <li class="links"><a href="about.html">About Us</a></li>
43                                                                 <li class="links"><a href="apps.html">Related Links</a></li>
44                                                                 <li class="links"><a href="contact.html">Contact Stork</a></li>
45                                                                 <h4>Links</h4>
46                                                                 <li class="links"><a href="http://appmanager.berkeley.intel-research.net/plcontrol/apps.php?appid=1029">
47                                                                 Slice Status</a></li>
48                                                                 <li class="links"><a href="https://stork-repository.cs.arizona.edu">Stork Repository</a></li>
49                                                         </ul>
50
51                                                  </td>
52                                         </tr>
53                                 </table>
54                                 <br/>
55                 </td>
56
57                 <td valign="top">
58                 <table class="info" cellpadding="0" width="700" >
59                 <tr  height="75"><td colspan="3"><img style="margin-left: -0px;" src="images/stork-header.png" alt="stork logo"/></td></tr>
60                 <tr  bgcolor="#444444" class="headerrow" width="100%" height="2">
61
62                         <th colspan="2">Stork Walkthrough</th>
63
64                 </tr>
65                 <tr valign="top" align="left">
66
67                         <td>
68                                 <table cellpadding="8" id="content" class="content">
69                                         <tr>
70                                                 <td>
71
72                                                         <!-- TODO: possibly clean up use of "we" vs. "you" throughout entire tutorial. -->
73
74                                                         <h1><a name="top"></a>Learn Stork by walking through it step-by-step</h1>
75                                                         
76                                                         <h2>Part I: Stork for Package Management</h2>
77                                                         
78                                                         <p>
79                                                         This part of the walkthrough will show you how to setup Stork and how to easily manage which 
80                                                         packages are installed on your nodes. This is a good place to start if you are new to Stork. Once you're 
81                                                         familiar with the steps outlined here in Part I, you can move on to Part II which will show you how to make 
82                                                         your own packages available from the repository so that you can use Stork to install packages you've created.
83                                                         </p>
84                                                         
85                                                         <p>
86                                                         <b>Initial setup checklist:</b><br />
87                                                         <a href = "#downloadenduser">1. Download and extract Stork enduser tarball.</a><br />
88                                                         <a href = "#genpair">2. Choose a username and create a keypair for that username.</a><br />
89                                                         <a href = "#stork.conf">3. Prepare your stork.conf file.</a><br />
90                                                         <a href = "#uploadpubkey">4. Upload your public key and stork.conf to the repository.</a><br />
91                                                         <a href = "#installstork">5. Install stork on your nodes.</a>
92                                                         </p>
93                                                         
94                                                         <p>
95                                                         <b>Package management checklist:</b><br />
96                                                         <a href = "#editpacgroups">1. Edit your pacman groups file.</a><br />
97                                                         <a href = "#editpacpackages">2. Edit your pacman packages file.</a><br />
98                                                         <a href = "#edittpfile">3. Edit your trusted packages file.</a><br />
99                                                         <a href = "#uploadpacmanfiles">4. Upload these three files to the repository.</a>
100                                                         </p>
101                                                         
102                                                         <h2>Part II: Stork for Package Distribution</h2>
103                                                         
104                                                         <p>
105                                                         This part of the walkthrough will show you how to use Stork to distribute to your 
106                                                         nodes packages that you've created. This part assumes you have completed Part I.
107                                                         </p>
108                                                         
109                                                         <p>
110                                                         <b>Package distribution checklist:</b><br />
111                                                         <a href = "#createpackage">1. Create a package to be distributed.</a><br />
112                                                         <a href = "#addpackagetotpfile">2. Add the package to the trusted packages file (TPFile).</a><br />
113                                                         <a href = "#addpackagetopackagesfile">3. Add the package to the pacman packages file.</a><br />
114                                                         <a href = "#uploadpackage">4. Upload the package, TPFile, and pacman packages file to repository.</a><br />
115                                                         </p>
116                                                                                                         
117 <hr />
118
119 <h3>Conventions used in this tutorial:</h3>
120
121 <p>1. Commands that are to be run through a shell. Parts to be typed are bold;
122  non-bold text is output.</p>
123
124 <code class="shell"><b>grep "example string" *.txt</b>
125 foo.txt:something something example string</code>
126
127 <p>2. Information that you may see in a file, terminal window, or browser but 
128  that is not part of a command to be entered in a shell.</p>
129
130 <code class="block">configoption = true</code>
131
132 <hr />
133
134
135 <h2>Part I: Stork for Package Management</h2>
136
137 <h3>Initial Setup</h3>
138
139 <a name="downloadenduser"></a>
140 <h4>1. Download and extract Stork enduser tarball.</h4>
141
142 <p>Note: Steps 1-4 do not have to be done on a PlanetLab node. They normally 
143  should be done on a non-PlanetLab system of your own.
144  
145 <p>Download the latest Stork enduser tarball linked from the 
146  <a href="http://www.cs.arizona.edu/stork/filelist.html">Stork file list</a>, 
147  extract it, and rename the extracted directory as desired.</p>
148
149 <p>The following shows an example of downloading the enduser utilities and
150  putting them in a directory called <code>stork-enduser</code>:</p>
151
152 <code class="shell"><b>wget http://www.cs.arizona.edu/stork/downloads/stork-enduser-tar-latest.tar.gz</b>
153 <b>tar xzf stork-enduser-tar-latest.tar.gz</b>
154 <b>mv stork-enduser-tar-<i>xx</i> stork-enduser</b></code>
155
156
157 <a name="genpair"></a>
158 <h4>2. Choose a username and create a keypair for that username</h4>
159
160 <p>Choose a username. We'll use "example2" in this tutorial.</p>
161
162 <p>Next, change directory to where you placed your Stork enduser utilities and
163  create a keypair using the username you've chosen:</p>
164
165 <code class="shell"><b>cd stork-enduser</b>
166 <b>./storkutil.py genpair example2</b>
167 Generated example2.privatekey...
168 Extracted example2.publickey...
169 Would you like to make 'example2' your default identity? (y/n) &gt;
170 <b>y</b>
171 'example2' is now your default identity</code>
172
173 <p>This command has created 2 new files in the current directory:</p>
174
175 <code class="block">example2.privatekey
176 example2.publickey</code>
177
178 <p>As we chose to make this key our new default identity, the following file
179  (in our home directory) was modified to make use of this key:</p>
180
181 <code class="block">~/.storkutil.conf</code>
182
183 <p>Note: <code>~/.storkutil.conf</code> is using the full path on our filesystem
184  to the key pair we just generated. If we decided to move these keys elsewhere 
185  on our filesystem, minor reconfiguring of storkutil would be needed so that it 
186  could find these keys in their new location.</p>
187
188
189 <a name="stork.conf"></a>
190 <h4>3. Prepare your stork.conf file.</h4>
191
192 <p>The stork enduser tarball comes with a sample <code>stork.conf</code> file,
193  appropriately named <code>sample-stork.conf</code>. You will need to make a 
194  copy of the <code>sample-stork.conf</code> file and edit the username in two 
195  places.</p>
196
197 <code class="shell"><b>cp sample-stork.conf stork.conf</b></code>
198
199 <p>Now edit the <code>stork.conf</code> file and modify the following lines:</p>
200
201 <code class="block">username = default
202 publickeyfile = /usr/local/stork/var/keys/default.publickey</code>
203
204 <p>you want the username you have chosen, along with its respective key, to be
205  used. So, change the "default" to your username, which for this tutorial is
206   "example2":</p>
207
208 <code class="block">username = example2
209 publickeyfile = /usr/local/stork/var/keys/example2.publickey</code>
210
211
212 <a name="uploadpubkey"></a>
213 <h4>4. Upload your public key and stork.conf to the repository.</h4>
214
215 <p>To upload these files, first login to the
216  <a href="https://stork-repository.cs.arizona.edu/">Stork repository</a>.</p>
217
218 <p>Next, click on the "Public Keys" link in the left navigation. Select the
219  slice the public key is for using the drop-down menu that lists all of your 
220  slices. Then, click "Browse" and choose the public key file generated during 
221  step 2 above. For this tutorial, we would select the example2.publickey file. 
222  After selecting your public key, press the "Upload File" button. You will 
223  receive a confirmation that your public key was successfully uploaded.</p>
224
225 <p>Next, click on the "Configuration File" link in the left navigation. Repeat
226  the process above, this time selecting the stork.conf file you created in step 
227  3 above. You will once again receive a confirmation of successful upload.</p>
228
229
230 <a name="installstork"></a>
231 <h4>5. Install stork on your nodes.</h4>
232
233 <p>Now that the repository has the basic files needed for new Stork installs on 
234  your nodes to operate, you can proceed with installing Stork on them.</p>
235  
236 <p><b>=&gt; Install Method 1: PlanetLab initscript [Recommended]</b></p>
237
238 <p>The easiest way to install Stork is using the initscript through PlanetLab.</p>
239
240 <p>To run the initscript through PlanetLab, log into 
241  <a href="https://www.planet-lab.org/">PlanetLab</a>, go to the 
242  <a href="https://www.planet-lab.org/db/slices/">Slices 
243  page of your PlanetLab account</a>, click on the name of the slice in which you 
244  want Stork installed when you add new nodes, and click on Add New Attribute. 
245  Next, select <b>plc_initscript_id</b>, set the value to <b>2</b>, and click the 
246  "Add Attribute" button. You will now see on your slice details page the Slice 
247  Attribute of:</p>
248  
249 <code class="block">Attribute           Value   Description
250 plc_initscript_id       2       Script used to initialise slice</code>
251
252 <p>This slice attribute you have set will cause Stork to be installed when a 
253  new node is added to your slice. It will not be run on nodes that are already 
254  part of your slice. However, you can remove a node and re-add it to your slice 
255  to have PlanetLab reinitialize the node and run the Stork initscript 
256  automatically.</p>
257
258 <p><b>=&gt; Install Method 2: Manual initscript</b></p>
259
260 <p>To install Stork on existing nodes without reinitializing them, 
261  you can manually download and run the 
262  <a href="http://www.cs.arizona.edu/stork/downloads/initscript">Stork initscript</a> 
263  on each of your nodes. To do this, login to each node on which you want to 
264  install Stork and run the following:</p>
265
266 <code class="shell"><b>wget http://www.cs.arizona.edu/stork/downloads/initscript</b>
267 <b>chmod 755 initscript</b>
268 <b>sudo ./initscript</b>
269 Your slice name is 'your_slice_name'.
270 Contacting the stork nest on this node
271 ...</code>
272
273
274 <hr />
275
276 <h3>Package Management</h3>
277
278 <a name="editpacgroups"></a>
279 <h4>1. Edit your pacman groups file.</h4>
280
281 <p>Your pacman groups file will allow you to specify sets of nodes that can be
282  referred to collectively for the purposes of installing, upgrading and removing 
283  packages. Specifying groups is not required but can make package management 
284  simple in some complex situations.</p>
285
286 <p>Note: if you do not have a pacman groups file already when you add a group, 
287  a new groups file will be created for you.</p>
288
289 <p>To create a group called "exampleGroup" made up of three nodes
290  (planetlab-[5-7].cs.princeton.edu), we will go to the directory where we placed 
291  the Stork enduser utilities and run the following command:</p>
292
293 <p>Note: a backslash (\) is used in the command below to tell the shell that the 
294  command spans to the next line. This is not necessary when you are entering
295  longer storkutil commands and is only done for display reasons in this 
296  tuturial.</p>
297
298 <code class="shell"><b>./storkutil.py pacgroups include exampleGroup planetlab-5.cs.princeton.edu \
299 planetlab-6.cs.princeton.edu planetlab-7.cs.princeton.edu</b>
300 Using groups file: ./example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMw
301 tXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.groups.pacman
302
303 File Not Found, Creating New File
304 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
305 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.groups.pacman' successfully signed</code>
306
307 <p>Note: the pacman groups file is named in the format:</p>
308
309 <code class="block">{username}.{publickey}.groups.pacman</code>
310
311 <p>We can view the groups defined in our pacman groups file using the following
312  command:</p>
313
314 <code class="shell"><b>./storkutil.py view groups</b>
315 Viewing: example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJ
316 r_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.groups.pacman
317
318 PACMAN GROUP FILE
319         GROUP:  exampleGroup
320                 INCLUDE:        planetlab-5.cs.princeton.edu
321                 INCLUDE:        planetlab-6.cs.princeton.edu
322                 INCLUDE:        planetlab-7.cs.princeton.edu</code>
323
324 <p>We see that the group we added and the nodes it consists of are as we just
325  specified.</p>
326
327
328 <a name="editpacpackages"></a>
329 <h4>2. Edit your pacman packages file.</h4>
330
331 <p>We will now specify which packages we want installed, updated and removed on
332  our nodes. We can specify such actions by individual node, by group (according 
333  to the groups we created above), or even for all nodes in our slice.</p>
334
335 <p>Let's install vim-enhanced on all nodes in our group called "exampleGroup" 
336 and gnupg on one individual node that is not part of any group.</p>
337
338 <p>To configure our pacman packages file for this, we do the following:</p>
339
340 <code class="shell"><b>./storkutil.py pacpackages group exampleGroup install vim-enhanced</b>
341 Using Package File: ./example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpM
342 wtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman
343
344 File Not Found, Creating New File
345 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
346 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman' successfully signed
347
348 <b>./storkutil.py pacpackages node planetlab-4.cs.princeton.edu install gnupg</b>
349 Using Package File: ./example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpM
350 wtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman
351
352 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
353 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman' successfully signed</code>
354
355 <p>Note: we could install a package to all nodes in our slice by using a command
356  of the format <code>./storkutil.py pacpackages all install {package-name}</code></p>
357
358 <p>Note: the pacman packages file is named in the format:</p>
359
360 <code class="block">{username}.{publickey}.packages.pacman</code>
361
362 <p>We can now check the contents of our pacman packages file:</p>
363
364 <code class="shell"><b>./storkutil.py view packages</b>
365 Viewing: example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
366 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman
367
368 PACMAN PACKAGES FILE
369 CONFIG ALL:
370                 UPDATE: stork-client
371                 UPDATE: arizona-lib
372         CONFIG GROUP:   exampleGroup
373                 INSTALL:        vim-enhanced
374         CONFIG NODE:    planetlab-4.cs.princeton.edu
375                 INSTALL:        gnupg</code>
376
377 <p>This is correct. Note the two additional UPDATE commands that we didn't
378  define. These are part of every newly-created pacman packages file. They serve 
379  to keep Stork itself updated.</p>
380
381
382 <a name="edittpfile"></a>
383 <h4>3. Edit your trusted packages file.</h4>
384
385 <p>We'll now create a trusted packages file (a.k.a. TPFile). For the purposes 
386  of this tutorial, we just want to allow packages from user "default". This
387  default user trusts Stork and PlanetLab, as well as a few other packages, 
388  meaning you should be able to install the newest Stork and PlanetLab releases 
389  without adding them to your TPFile.</p>
390
391 <p>Note: When a TPFile does not already exist, the 'default' user is added to
392  your is newly-created TPFile's trusted list automatically. Here we add this 
393  user explicitly because we won't be performing any other action on the TPFile.</p>
394
395 <p>The command we run to add this default user is as follows (note that
396  default.publickey is included in the Stork enduser tarball):</p>
397
398 <p>Note: the asterisk (*) is escaped so that the shell does not treat it as a
399  glob.</p>
400
401 <code class="shell"><b>./storkutil.py adduser default default.publickey allow \*</b>
402 No tpfile found for example2.  Generating new tpfile.
403
404 default user public key found: Adding user to TPFile
405
406 File 'example2.tpfile' successfully signed
407 File 'example2.tpfile' has been copied to 'example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4
408 L_AvEeN3doBfNpMwtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile'
409 Unembedded trusted packages file 'example2.tpfile' removed.
410 Using trustedpackages file './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN
411 3doBfNpMwtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile'.
412 Successfully added user 'default'.
413 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
414 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile' successfully signed</code>
415
416 <p>Note: the trusted packages file is named in the format:</p>
417
418 <code class="block">{username}.{publickey}.tpfile</code>
419
420 <p>We can verify the contents of our TPFile with the following:</p>
421
422 <code class="shell"><b>./storkutil.py view tpfile</b>
423 Viewing: example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
424 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile
425
426 TRUSTED PACKAGES FILE
427         ALLOW * from default
428         ALLOW * from default</code>
429
430 <!-- TODO: determine if there is a better way to create the key so that 'default' isn't added twice. -->
431 <p>Note: because we explicitly added the user 'default' and storkutil adds this
432  user automatically when creating a new TPFile, the user is listed twice. This 
433  is OK.</p>
434
435
436 <a name="uploadpacmanfiles"></a>
437 <h4>4. Upload these three files to the repository.</h4>
438
439 <p>We log in to the
440  <a href="https://stork-repository.cs.arizona.edu/">Stork repository</a>.</p>
441
442 <p>Next, we go to the link in the left navigation titled "Trusted Package Files"
443  and upload the TPFile we created. When browsing for this file, we will be 
444  looking for a file named in the format <code>{username}.{publickey}.tpfile</code>.</p>
445
446 <p>We then go to the link in the left navigation titled "Pacman Files". We will
447  first upload our pacman groups file (the file named in the format 
448  <code>{username}.{publickey}.groups.pacman)</code>. After uploading the groups 
449  file, we will return to this same page and upload our pacman packages file (the 
450  file named in the format <code>{username}.{publickey}.packages.pacman</code>).</p>
451
452 <hr />
453
454 <h3>"Package Management" Completed</h3>
455
456 <p>We have now completed the steps necessary to install the files we desired on
457  the nodes we wanted them installed on. These files will normally begin 
458  installing on the appropriate nodes within ten minutes. The total time required 
459  for the installation to finish on a given node will depend on which packages 
460  are being installed and the load on that node.</p>
461
462 <p>In the case of our example, we check a little while later on our various
463  nodes and see the following:</p>
464
465 <p>On all nodes in group "exampleGroup" we see:</p>
466
467 <code class="shell"><b>rpm -q vim-enhanced</b>
468 vim-enhanced-6.3.071-3</code>
469
470 <p>And only on planetlab-4.cs.princeton.edu:</p>
471
472 <code class="shell"><b>rpm -q gnupg</b>
473 gnupg-1.4.1-3</code>
474
475 <!-- TODO: clarify use of upgrade vs. install. (e.g. will upgrade also install a package?) -->
476 <p>If we wanted to have these packages upgraded or removed on specific groups or
477  nodes, or even on all nodes in our slice, we would use storkutil to modify our 
478  pacman packages file and add entries to "upgrade" and "remove" whichever 
479  packages we wanted affected.</p>
480
481 <p>If you want to use Stork to distribute your own packages, you can now move on
482  to the tutorial titled "Using Stork to distribute your own packages".</p>
483
484
485
486 <hr />
487
488
489 <h2>Part II: Stork for Package Distribution</h2>
490
491 <h3>Package Distribution</h3>
492
493 <a name="createpackage"></a>
494 <h4>1. Create a package to be distributed.</h4>
495
496 <p>Stork currently supports two types of packages: RPMs and tarballs. For more
497  information on using each, please see the 
498  <a href="http://www.cs.arizona.edu/stork/tut.html#tarball">Stork tutorial</a>. 
499  In this tutorial we will create and distribute a tarball.</p>
500
501 <p>Our tarball package will be quite simple for this example. We've made a
502  directory called example-package and inside of that directory is one file:</p>
503
504 <code class="shell"><b>ls examplepackage-0.0.1-1/</b>
505 existing-file</code>
506
507 <p>We also have a separate file called .postinstall that is not in the
508  examplepackage-0.0.1-1 directory that we are going to put in the archive. Stork 
509  will run this .postinstall file after the package has been installed. For more 
510  information on other special files that can be used in tarball packages, see 
511  the <a href="http://www.cs.arizona.edu/stork/tut.html#tarball">Stork tutorial</a>.</p>
512
513 <p>In our <code>.postinstall</code> file we have put the following:</p>
514
515 <code class="block">#!/bin/bash
516 /bin/touch ~/examplepackage-0.0.1-1/new-file</code>
517
518 <p>So that it can be run, we make sure the <code>.postinstall</code> file is
519  executable:</p>
520
521 <code class="shell"><b>chmod 755 .postinstall</b></code>
522
523 <p>and then we create our tarball of the example-package directory:</p>
524
525 <code class="shell"><b>tar -czf examplepackage-0.0.1-1.tar.gz examplepackage-0.0.1-1 .postinstall</b></code>
526
527 <p>We are now done creating our tarball package.</p>
528
529
530 <a name="addpackagetotpfile"></a>
531 <h4>2. Add the package to the trusted packages file (TPFile).</h4>
532
533 <p>We now add our tarball package to our TPFile using storkutil. Note that we
534  need to provide the path to the actual tarball, not just it's name, as a hash 
535  specific to this tarball will be used to ensure only this specific file is 
536  trusted and not any other that may have the same filename.</p>
537
538 <code class="shell"><b>./storkutil.py addfile /path/to/examplepackage-0.0.1-1.tar.gz</b>
539 Using trustedpackages file './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN
540 3doBfNpMwtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile'.
541 Successfully added file 'examplepackage-0.0.1-1.tar.gz'.
542 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
543 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile' successfully signed</code>
544
545 <p>We can then check the contents of our TPFile, if desired:</p>
546
547 <code class="shell"><b>./storkutil.py view tpfile</b>
548 Viewing: example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
549 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.tpfile
550
551 TRUSTED PACKAGES FILE
552         ALLOW examplepackage-0.0.1-1.tar.gz
553         ALLOW * from default</code>
554
555 <p>We see our package is now trusted.</p>
556
557
558 <a name="addpackagetopackagesfile"></a>
559 <h4>3. Add the package to the pacman packages file.</h4>
560
561 <p>Trusting a package as we have done above will not cause the package to be
562  distributed. It will only allow a given file to be trusted if installation of 
563  the package has been requested. Therefore, we still need to get this package 
564  distributed to the nodes we want it installed on. To do this, we will add this 
565  package to our pacman packages file.</p>
566
567 <p>Note: we don't need to provide the full path to the file when specifying it
568  to be installed/upgraded/removed in the pacman packages file.</p>
569
570 <p>Note: when specifying a tarball package rather than an RPM package, the
571  entire filename should be used.</p>
572
573 <code class="shell"><b>./storkutil.py pacpackages group exampleGroup install examplepackage</b>
574 Using Package File: ./example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpM
575 wtXLuFbyCjsRJr_BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman
576
577 File './example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
578 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman' successfully signed</code>
579
580 <p>We can verify this has been added to our packages file, if desired:</p>
581
582 <code class="shell"><b>./storkutil.py view packages</b>
583 Viewing: example2.MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOsyG3F4L_AvEeN3doBfNpMwtXLuFbyCjsRJr
584 _BevXU9YTPVBIYfJsKZY_pumvGEr3bUg0PRh6N8VRl1rrSRDDUCAwEAAQ.packages.pacman
585
586 PACMAN PACKAGES FILE
587 CONFIG ALL:
588                 UPDATE: stork-client
589                 UPDATE: arizona-lib
590         CONFIG GROUP:   exampleGroup
591                 INSTALL:        vim-enhanced
592                 INSTALL:        examplepackage
593         CONFIG NODE:    planetlab-4.cs.princeton.edu
594                 INSTALL:        gnupg</code>
595
596
597 <a name="uploadpackage"></a>
598 <h4>4. Upload the package, TPFile, and pacman packages file to repository.</h4>
599
600 <p>We are now ready to upload our files to the repository.</p>
601
602 <p>First, we login to the repository at
603  <a href="https://stork-repository.cs.arizona.edu/">Stork repository</a>. Next 
604  we click the link titled "Packages" in the left navigation. We click the 
605  "Browse" link, select our examplepackage-0.0.1-1.tar.gz file on our local 
606  system, then click "Upload File". We will receive a confirmation when the file 
607  has been successfully uploaded.</p>
608
609 <p>Note: If the package being uploaded is large, this step may take some time
610  depending on your connection speed and the load on the repository.</p>
611
612 <p>Next, we upload our new TPFile and pacman packages file by going to the
613  "Trusted Packages Files" and "Pacman Files" links, respectively.</p>
614
615 <p>Note: You do not need to re-upload your pacman groups file unless you have
616  changed any of your group definitions.</p>
617
618 <p>After uploading these three files---the tarball package, TPFile, and pacman
619  packages file---we are finished. Our package should begin installation on our 
620  desired nodes within ten minutes. The total time required for the installation 
621  to finish on a given node will depend on which the package being installed and 
622  the load on that node. As our example package is pretty small, this shouldn't 
623  take too long.</p>
624
625 <p>When we check the <code>/root/</code> directory a little while later, we see
626  the following:</p>
627
628 <code class="shell"><b>ls</b>
629 examplepackage-0.0.1-1</code>
630
631 <p>So we can tell the package was installed. If we look inside that directory:</p>
632
633 <code class="shell"><b>ls examplepackage-0.0.1-1</b>
634 existing-file  new-file</code>
635
636 <p>we see there is a file called <code>new-file</code>. That was the file that
637  we had our <code>.postinstall</code> script create, so that means the 
638  <code>.postinstall</code> script did run as expected.</p>
639
640 <p>If we wanted to upgrade our nodes to a new version of our package, we would
641  increment the version and/or release numbers, add the new file to our TPFile, 
642  set our pacman packages file to upgrade this package rather than just install 
643  it, and update our new package, TPFile, and pacman packages file to the 
644  repository. We would likely also want more realistic <code>.preinstall</code> 
645  and <code>.postremove</code> scripts. Remember that RPMs can be used also. For 
646  more complex packages, that can be a better choice than tarballs.</p>
647
648
649 <hr />
650
651 <h3>Congratulations, you're almost a Stork expert!</h3>
652
653 <p>Should you still have unanswered questions after looking through our website,
654  or if you are having problems using this tutorial or suspect it has an error, 
655  please let us know! An excellent way to contact us is through the 
656  <a href="http://cgi.cs.arizona.edu/projects/stork/forum/">Stork forum</a></p>
657
658
659
660
661                                                         <center><a href = "index.html">Home</a>     <a href = "#top">Top</a></center>
662
663
664                                                 </td>
665                                         </tr>
666                                 </table>
667                         </td>
668                 </tr>
669
670        </table>
671        </td>
672
673      </tr>
674      <tr>
675         <td></td>
676         <td>
677                 <a href="http://www.planet-lab.org"><img style="border: 0px; border-style: none;" src="images/powered_by_pl_grey.png" alt="powered by planetlab"></a>
678
679                                         <a href="http://www.cs.arizona.edu"><img style="position:relative; left: 20px; border: 0px; border-style: none;" src="images/template_logo_small_grey.png" alt="University of Arizona, Computer Science logo"></a>
680
681
682
683
684
685         </td>
686      </tr>
687
688 </table>
689
690 </div>
691
692
693 </body>
694 </html>