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