import repository from arizona
[raven.git] / webpage / storkclient.html
1 <html>
2 <head>
3 <title> Stork Project </title>
4 <LINK href="stork.css" rel="stylesheet" type="text/css">
5
6 <style type="text/css">
7 dt {
8     font-weight: bold;
9     font-family: monospace;
10 </style>
11
12 </head>
13
14 <body>
15
16
17 <div class="display" align="center">
18         <table border="0">
19         <tr>
20                 <td width="170" valign="top">
21
22                                 <br/>
23                                 <table cellpadding="3" width="170" id="links" class="links">
24                                         <tr>
25                                                 <td align="right">
26
27                                                         <ul class="links">
28
29                                                                 <a href = "index.html"><h3>Stork</h3></a>
30                                                                 <li class="links"><a href="tutmain.html">Stork Tutorial</a></li>
31
32                                                                 <li class="links"><a href="advanced.html">Advanced Usage</a></li>
33                                                                 <li class="links"><a href="arch.html">Stork Architecture</a></li>
34                                                                 <li class="links"><a href="filelist.html">Stork File List</a></li>
35                                                                 <li class="links"><a href="about.html">About Us</a></li>
36                                                                 <li class="links"><a href="apps.html">Related Links</a></li>
37                                                                 <li class="links"><a href="contact.html">Contact Stork</a></li>
38                                                                 <h4>Links</h4>
39                                                                 <li class="links"><a href="http://appmanager.berkeley.intel-research.net/plcontrol/apps.php?appid=1029">
40                                                                 Slice Status</a></li>
41                                                                 <li class="links"><a href="https://stork-repository.cs.arizona.edu">Stork Repository</a></li>
42                                                         </ul>
43
44                                                  </td>
45                                         </tr>
46                                 </table>
47                                 <br/>
48                 </td>
49
50                 <td valign="top">
51                 <table class="info" cellpadding="0" width="700" >
52                 <tr  height="75"><td colspan="3"><img style="margin-left: -0px;" src="images/stork-header.png" alt="stork logo"/></td></tr>
53                 <tr  bgcolor="#444444" class="headerrow" width="100%" height="2">
54
55                         <th colspan="2"> Using Stork </th>
56
57                 </tr>
58                 <tr valign="top" align="left">
59
60
61                         <td>
62                                 <table cellpadding="8" id="content" class="content">
63                                         <tr>
64                                                 <td>
65
66
67                                                         <h1><a name = "top"></a>The Stork Client</h1>
68                                                         The Stork client is used to install packages onto your nodes.
69                             There are two different ways to install packages:<ul>
70                               <li>Manually using the stork client command-line tool</li>
71                               <li>Automatically using pacman</li>
72                             </ul>
73                             <p>There are a number of command line options that
74                             may be specified to control the behavior of stork.
75                             These options may also be specified in the stork <a href="tutfiles.html"> configuration file</a>
76                             (/usr/local/stork/etc/stork.conf by default). Stork will also check your <a href="tuttp.html">TPFile</a>
77                                                         to confirm that the package is a trusted package from the package's true creator.
78                             </p>
79                                                         <p>Stork client, while effective by itself, is also used in unison with
80                                                         <a href="tutpac.html">Pacman</a>. Pacman is used to organize nodes and packages,
81                                                         and essentially just runs the Stork client for installation of each individual node
82                                                         that you tell it to manage. Pacman will call the Stork client when a package is updated
83                                                         in the repository, thereby updating the package on your nodes.
84 <p><img src="blkfade.gif" width="100%"></img>
85                                                         <h2>Stork Client Command-line Tool</h2>
86                                                         The stork client tool can be used to manually
87                             install, remove, and upgrade packages. It does this
88                             through a command-line interface. You must be logged
89                             in as root to use the stork client tool.<p><b>
90                             Installing Packages:</b></p>
91                             <blockquote>
92                               <p>To install a package on a node,
93                                                                                                                 use the command (from root):
94                                                         <br><b><code>$ stork <i>mypackage</i></code></b>
95                               </p>
96                             </blockquote>
97
98
99                                                         <p><b>Removing Packages:</b><blockquote>
100
101
102                                                         <p>To remove a package from a node, use the option:
103                                                         <br><b><code>$ stork --remove <i>mypackage</i></code></b>
104
105
106
107
108
109
110                                                         </blockquote>
111
112
113                                                         <p><b>Upgrading Packages:</b><blockquote>
114
115
116                                                         <p>To upgrade a package from a node, use the option:
117                                                         <br><b><code>$ stork --upgrade <i>mypackage</i></code></b>
118
119
120
121
122
123
124                                                         </blockquote>
125
126
127                                                         <p><b>Specifying version numbers and tags:</b><blockquote>
128
129
130                                                         <p>Optionally, you may also specify version and tag
131                             numbers when installing and upgrading packages. For
132                             example:<p>To install a specific version number of a
133                               package:<br>
134                               <b><code>$ stork --upgrade <i>mypackage=1.0.3-11</i></code></b><p>
135                               <code><b><i>You may also use &gt;, &lt;, &gt;=, &lt;=
136                               relational operators:<br>
137                               </i>$<i>
138                               </i>stork --upgrade <i>mypackage</i></b></code>&lt;=1.0-3-11<p>
139                               To install a package with a specific tag, use the
140                               '#' syntax:<br>
141                               <code><b>$ stork --upgrade <i>mypackage</i></b></code>#mytag</blockquote>
142
143
144
145
146
147
148                                                         <p><img src="blkfade.gif" width="100%"></img>
149                                                         <h2>Stork Client Options</h2>
150                                                         The following are the options that can be used with the stork client, organized by type.
151                                                                           <h3 align="center">Help, Verbosity, and Miscellaneous</h3>
152                             <dl>
153                               <dt>-h, --help</dt>
154                               <dd>Display a short summary of
155                                           available options and exit</dd>
156                               <dt>--version</dt>
157                               <dd>Display stork version number and
158                                           exit</dd>
159                               <dt>--log</dt>
160                               <dd>Record package actions in the system log</dd>
161                               <dt>--width=CHARS</dt>
162                               <dd>Set the width of the terminal in characters (default: 80)
163                               </dd>
164                               <dt>-Q, --veryquiet</dt>
165                               <dd>Be very quiet (shorter messages)</dd>
166                               <dt>-q, --quiet</dt>
167                               <dd>Be quiet</dd>
168                               <dt>-v, --verbose</dt>
169                               <dd>Be verbose (default)</dd>
170                               <dt>-V, --veryverbose</dt>
171                               <dd>Be very verbose (useful for
172                                           debugging)</dd>
173                               <dt>--ultraverbose</dt>
174                               <dd>Be extremely verbose (might be
175                                           useful for debugging)</dd>
176                             </dl>
177                             <h3 align="center">Error Reporting</h3>
178                             <p align="left">Stork includes a built-in error
179                             logging and reporting feature. Errors in the Stork
180                             python scripts will be caught and a comprehensive
181                             error report generated and stored in a file in /tmp
182                             for future reference. The error report will be
183                             automatically emailed to the Stork developers to aid
184                             in diagnosing future problems. </p>
185                             <dl>
186                               <dt>--debug</dt>
187                               <dd>Disable the error reporting mechanism. Stork
188                               will not catch exceptions and will neither
189                               generate nor send error reports.</dd>
190                               <dt>--disableerrorreporting</dt>
191                               <dd>Disables sending of error reports to the Stork
192                               team. Reports are still generated and saved to
193                               files, but they will not be mailed to the Stork
194                               developers.</dd>
195                             </dl>
196
197
198                                                                           <center><h3>Commands</h3></center>
199                                                                           <p align="left">All of the following
200                                       options are mutually exclusive and effect
201                                       what operation stork will carry out. If no
202                                       command is given, then stork will
203                                       automatically default to package
204                                       installation.</p>
205                             <dl>
206                               <dt>(default)</dt>
207                               <dd>Install the packages listed on the command
208                               line. The version that the package will be
209                               upgraded to will generally be the first matching
210                               line that is found in your trusted packages file.
211                               The install command will fail if any version of a
212                               package is already installed.</dd>
213                               <dt>-R, --remove</dt>
214                               <dd>Remove the packages listed on the command
215                               line.</dd>
216                               <dt>--upgrade</dt>
217                               <dd>Upgrade the packages listed on the command
218                               line. Upgrade is similar to install, with the
219                               exception that upgrade does not fail when packages
220                               are installed. The specific actions of an upgrade
221                               depend on the type of package installed. For an
222                               RPM package, stork will install the new version
223                               and then remove the old version (mimicking the
224                               behavior of RPM). For tar packages, stork will
225                               remove the old version of the package before
226                               installing the new version.</dd>
227                               <dt>--whatrequires</dt>
228                               <dd>List all installed packages that require the
229                               dependencies listed on the command line.</dd>
230                               <dt>--list</dt>
231                               <dd>List installed packages. If package names are
232                               listed on the command line, then stork will query
233                               those package names. If no names are listed, then
234                               stork will list all packages installed.</dd>
235                               <dt>--tpdump</dt>
236                               <dd>Dump trusted packages data, including your
237                               trusted packages file and all trusted packages
238                               file reference by it. The dumped output will be
239                               sorted to indicate the order in which packages
240                               will be prioritized when searching for a package
241                               to install. </dd>
242                             </dl>
243                             <h3 align="center">Modifiers to Package
244                             Installation, Remove, Upgrade</h3>
245                             <dl>
246                               <dt>-s, --simulate</dt>
247                               <dd>Simulate the action instead of performing it.
248                               Packages will not be downloaded, installed,
249                               upgraded, or removed.</dd>
250                               <dt>--force</dt>
251                               <dd>Force removal and/or upgrade of packages that
252                               have outstanding dependencies. Normally stork will
253                               refuse to remove or upgrade a package, if removal
254                               or upgrade would break other packages that depend
255                               upon it. Specifying --force will cause stork to
256                               ignore those dependencies and remove/upgrade the
257                               packages anyway.</dd>
258                               <dt>-a, --abort</dt>
259                               <dd>If dependency resolution fails to resolve the
260                               dependencies of a package, then abort without
261                               continuing to try other packages. </dd>
262                               <dt>-A DEPTH, --abortdepth=DEPTH</dt>
263                               <dd>Used with the --abort option, this option
264                               specifies the depth in dependency resolution for
265                               which the --abort option will take place. The
266                               default is 0. This option has no significance if
267                               --abort is not used. </dd>
268                               <dt>--disabletrustedpackagesdata</dt>
269                               <dd>Does not check the trustedpackages file before
270                               installing a package. WARNING: Using this option
271                               will allow packages that are untrusted or rejected
272                               to be installed. It also disables the tag feature
273                               and when multiple versions of a package exist,
274                               causes the version to be chosen arbitrarily.</dd>
275                               <dt>--noupgradedeps</dt>
276                               <dd>Does not automatically upgrade dependencies when
277                                                                                                                         upgrading or installing packages.</dd>
278                               <dt>--requiretags=TAGS</dt>
279                               <dd>Specifies a list of tags that must be present
280                               in a package and its dependencies. Packages
281                               without the tags will be ignored.</dd>
282                               <dt>--tagprefrules</dt>
283                               <dd>Specifies a list of tag preference rules that
284                               will be used to sort available packages. A rule is
285                               of the form &quot;tag1&lt;tag2&quot;. Multiple rules may be
286                               specified with commas (&quot;tag1&lt;tag2, tag3&lt;tag4&quot;).</dd>
287                             </dl>
288
289
290
291
292
293
294                                                                           <center><h3>File Transfer Options</h3></center>
295                                                                           <p>Stork transfers files using a variety
296                                       of mechanisms. These mechanisms generally
297                                       include the nest, bittorrent, coblitz,
298                                       coral, http, and ftp. If a transfer method
299                                       fails, then stork will failover to the
300                                       next available transfer mechanism. The
301                                       following options control the transfer
302                                       mechanisms.<dl>
303                               <dt>--transfermethod=PROGRAM</dt>
304                               <dd>Uses this method to transfer files (default ftp, http)
305                               </dd>
306                               <dt>--transfertempdir=PATH</dt>
307                               <dd>Uses this path to temporarily save transfered files
308                                                                                                                         (default is /tmp/stork_trans_tmp)
309                               </dd>
310                               <dt>--bittorrenttrackerhost=TRACKERHOST</dt>
311                               <dd>Uses this host name of the tracker server.
312                               </dd>
313                               <dt>--bittorrenttrackerport=TRACKERPORT</dt>
314                               <dd>Uses this number to specify as the tracker port number for
315                                                                                                                         torrents. </dd>
316                               <dt>--bittorrentuploadrate=UPLOADRATE</dt>
317                               <dd>Uses this number to specify as the tracker port number for
318                                                                                                                         torrents. </dd>
319                               <dt>--bittorrentseedlookuptimeout=SEEDLOOKUPTIMEOUT</dt>
320                               <dd>The number of seconds bittorrent should timeout after
321                                                                                                                         not finding a seed.
322                               </dd>
323                               <dt>--transuser=USER</dt>
324                               <dd>Uses this user to transfer files (the default is up to
325                                                                                                                         the transfer program)
326                               </dd>
327                               <dt>--nesthostname=HOSTNAME</dt>
328                               <dd>Uses this host to transfer files. The default
329                               is localhost.</dd>
330                               <dt>--nestport=PORT</dt>
331                               <dd>Uses this port to transfer files. The default
332                               is 648.</dd>
333                             </dl>
334
335
336
337
338
339
340
341
342                                                                           <center><h3>Repository Options</h3></center>
343                                                                           <p>These options control the stork package
344                                       managers (the interface to rpm, tar, etc)
345                                       and Stork's interaction with the
346                                       repository.<dl>
347                               <dt>--packagemanagers=PACKAGEMANAGERS</dt>
348                               <dd>Uses these programs to manage packages (default rpm,
349                                                                                                                         tar) </dd>
350                               <dt>--tarpackinfo=PATH</dt>
351                               <dd>Uses this path to store tar package info (default is
352                                                                                                                         /usr/local/stork/tar_packinfo)</dd>
353                               <dt>--localpackageinfo=PACKAGEDIR</dt>
354                               <dd>Uses this location of local package information (default
355                                                                                                                         /usr/local/stork/var/packageinfo).
356                               Stork creates a directory structure under this
357                               local dirctory to hold various bits of
358                               information, including package info, trusted
359                               packages files, and pacman fils.</dd>
360                               <dt>--repositorypackagedir=MASK</dt>
361                               <dd>Specifies a mask that is used to match
362                               available packageinfo files on the repository. The
363                               default of *_packages_* will allow all packageinfo
364                               to be used. A comma-separated list may be used for
365                               multiple masks, or the option may be repeated
366                               multiple times.</dd>
367                               <dt>--repositorypackageinfo=DIR</dt>
368                               <dd>Uses this repository name and location of
369                               information about packages. A comma-separated list
370                               (or multiple switches) may be used to download
371                               repository information from multiple repositories.
372                               In case duplicate trusted packages and/or pacman
373                               files exist on multiple repositories, ties will be
374                               broken in favor of the file with the newest
375                               timestamp.
376                               </dd>
377                               <dt>--noupdatepackageinfo</dt>
378                               <dd>Does not attempt to download updated package databases
379                               from the repositories.</dd>
380                               <dt>--insecure</dt>
381                               <dd>Does not use https for transferring configuration files
382                                                                                 from the repository using curl. This
383                               switch only affects the downloading of public keys
384                               and configuration files, and not the downloading
385                               of packages or metadata.</dd>
386                             </dl>
387
388
389
390
391
392
393                                                                           <h3><center>TPFiles, Config Files, Keys</center></h3>
394                             <dl>
395                               <dt>-C FILE, --configfile=FILE</dt>
396                               <dd>Use a different config file
397                                                                                                                         (/usr/local/stork/etc/stork.conf is the default)
398                               </dd>
399                               <dt>--noupdateonstart</dt>
400                               <dd>Do not try to download latest custom configuration
401                                                                                                                         files and keys from repository upon start of stork.py
402                               </dd>
403                               <dt>--xmlsignaturedtd=FILENAME</dt>
404                               <dd>Dump trusted packages data</dd>
405                               <dt>--trustedpackagesdtd=FILENAME</dt>
406                               <dd>Sets the trustedpackages DTD file</dd>
407                               <dt>--noupdatetrustedpackages</dt>
408                               <dd>Does not attempt to update the trustedpackages files
409                               </dd>
410                               <dt>--ignoremissingtpfiles</dt>
411                               <dd>Ignores missing trusted packages files.</dd>
412                               <dt>--certificate=STRING</dt>
413                               <dd>Uses a different certificate for downloading conf files
414                                                                                                                         from repository. the default is
415                                                                                                                         /usr/local/stork/var/certificates/nr06.certificate
416                               </dd>
417                               <dt>--repositorypath=STRING</dt>
418                               <dd>Uses a different repository to download configuration
419                                                                                                                         files from. the default is https://nr06.cs.arizona.edu
420                                                                                                                         /user-upload/ </dd>
421                               <dt>--keytype=KEYTYPE</dt>
422                               <dd>Use this technique to sign files (default is rsa)
423                               </dd>
424                               <dt>--keygen=GENTYPE </dt>
425                               <dd>Use this option to use openssl to generate your
426                                                                                                                         public/private keypair (default is genrsa)
427                               </dd>
428                               <dt>--hashtype=HASHTYPE</dt>
429                               <dd>Use this algorithm to generate hashes (default is
430                                                                                                                         -sha1) </dd>
431                               <dt>-u USERNAME, --username=USERNAME</dt>
432                               <dd>Use this username for configuration files </dd>
433                               <dt>--publickeyfile=file</dt>
434                               <dd>Use this public key file to determine which
435                                                                                                                         configuration files to use.  Recommended:
436                                                                                                                         /usr/local/stork/var/keys/[username].publickey
437                               </dd>
438                               <dt>--lockdir=dir</dt>
439                               <dd>Use the specified mutex lock directory (default
440                                                                                                                         /var/lock) </dd>
441                               <dd>&nbsp;</dd>
442                               <dd>&nbsp;</dd>
443                             </dl>
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464                                                         <center><a href = "index.html">Home</a>     <a href = "#top">Top</a></center>
465
466
467
468
469                                                 </td>
470                                         </tr>
471                                 </table>
472                         </td>
473                 </tr>
474
475
476        </table>
477        </td>
478
479
480      </tr>
481      <tr>
482         <td></td>
483         <td>
484                 <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>
485
486
487                                         <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>
488
489
490
491
492
493
494
495
496
497
498         </td>
499      </tr>
500
501
502 </table>
503
504
505 </div>
506
507
508
509
510 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
511 </script>
512 <script type="text/javascript">
513 _uacct = "UA-1868232-1";
514 urchinTracker();
515 </script>
516 </body>
517 </html>