import repository from arizona
[raven.git] / 2.0 / docs / storkdoc.txt
1 ****Stork****\r
2 **Installing Stork**\r
3 - Prerequisites (root access, only works on Planetlab nodes)\r
4 - Obtain InitScript\r
5 - Run InitScript\r
6 \r
7 ***Using Stork***\r
8 *Installing a Package using stork\r
9 Command: stork PACKAGENAME\r
10 Example: stork gnuchess\r
11 \r
12 *Uninstalling package\r
13 Command: stork --remove PACKAGENAME\r
14 Example: stork --remove gnuchess\r
15 \r
16 \r
17 *** Creating a Tarball Package ***\r
18         Creating a tarball package can be a great way to distribute your own applications.  With Stork, you can easily distribute your software to every node that needs it.  Stork also allows you to execute scripts before and after you install or uninstall, making tarballs even more powerful.\r
19 \r
20         Including scripts in your tarball is very simple.  Just package '.preinstall', '.postinstall', '.preremove', and/or '.postremove' scripts along with your own files.  Stork will automatically execute the script when the user decides to install or uninstall your package.  The scripts will run from the same directory the tarball is unpacked (typically '/root/' or what ever is defined to be the home directory).\r
21 \r
22         (Include example, tar and gzip a simple application with a simple script?)\r
23 \r
24 \r
25 ****Storkutil****\r
26         Stork's Enduser Utilities will help you manage your nodes more easily and efficiently.  It can help you organize your nodes, as well as perform installations and upgrades across all your nodes in a few simple steps.\r
27 \r
28         To start using Stork's Enduser Utilities, so first need to create an identity for yourself.  You can do this using the 'genpair' function.  This will create a private key and a public key, which will identify you and the software you wish to distribute.  The privatekey is used to sign the files that stork uses to install your software, so be sure to keep it in safe.  The public key is distributed to all your nodes (and all others that wish to use your software).  To create your keys, just run 'storkutil.py genpair USERNAME', using any username you desire.  If this is your first time using stork, it is best to set this key as your default.  If you've already created keys and would like to use those, you can use the 'storkutil.py setdefault USERNAME' command.\r
29 \r
30         storkutil.py genpair foo\r
31         y\r
32 \r
33 Be sure that the privatekey and publickey are in your current directory while using storkutil.  The publickey can be distributed to all your nodes through the upload website. (Link to upload instructions)\r
34 \r
35 \r
36 ***Configuration File***\r
37         You will need to change the stork configuration file to match the identity you created in storkutil.  Simple open up the file '/usr/local/stork/etc/stork.conf' and simple change the 'username = ' line to match the username you chose for your keys\r
38 \r
39         username = foo\r
40 \r
41         You can distribute this configuration file to all your nodes through the upload website. (Link to upload instructions)\r
42 \r
43 \r
44 ***Trusted Packages File***\r
45         The Trusted Packages File (TPFILE) defines which files you will allow your nodes to download and install.  This helps your nodes stay safe and secure, as files will be verified through a set of hash codes.  Even if two files share the same name, your nodes will only recieve the one that matches the hash obtained when the Trusted Packages File was created (preventing your nodes from downloading maliciously modified packages in the repository).  You are also allowed to trust other users, allowing your nodes to accept packages from those users exclusively.  This will let your nodes download and install applications created by other users.\r
46 \r
47         To add a package to your TPFile, use the command 'storkutil.py addfile FILE [FILE]...', where FILE is the location of the package you would like to trust. If the TPFILE does not exist, storkutil will create one for you.\r
48 \r
49         example (one package)\r
50         example (multiple packages)\r
51 \r
52 Storkutil will look at the file, create a hash, and write it to your TPFile.  If you upload the package to the repository and run stork to install the package, your node will select your specific file and install it.        If you want to view the contents of your TPFILE, just use the view command in storkutil.\r
53 \r
54         storkutil.py view tpfile\r
55         \r
56 You can remove a file from your TPFile, just use the 'removefile' command.\r
57         \r
58         removefile example\r
59         view\r
60 \r
61 \r
62 To trust users, you can use the adduser command:  \r
63 \r
64         storkutil adduser USER USER.pubkey (allow|deny|any) AFFECTEDPACKAGES\r
65 \r
66         USER is the name of the user you want to trust, followed by the public key that user has made available.  AFFECTEDPACKAGES can be a pattern that defines the packages you want to accept.  If the TPFILE does not exist, storkutil will create one for you.\r
67 \r
68         example: storkutil.py adduser USER1 USER1.publickey allow user-4-2.tar.gz\r
69         example: storkutil.py adduser USER2 USER2.publickey deny java\*\r
70         example: storkutil.py adduser PlanetLab PlanetLab.publickey allow \*\r
71 \r
72         The first example shows how to accept a single package from the user USER1.  The second example will deny all files from USER2 that have the pattern java*.  The third example shows how to accept all packages from the user PlanetLab (be sure to shell escape your use of *).  You can use the view to see the contents of your TPFILE.\r
73 \r
74         view\r
75 \r
76         You can remove users using the remove user command.\r
77 \r
78 When you are done, you can upload the file to your nodes through the upload website (link to upload instructions)\r
79 \r
80 \r
81 \r
82 ****Pacman****\r
83         Stork's package Manager (pacman) can help you manage your packages across all your nodes.  Rather than installing or uninstalling packages on each of your nodes individually, you can assign your nodes to groups and instruct stork to install or remove packages on those groups.  Pacman uses two files; groups and packages.  Using StorkUtil, you can create these two files and upload them.  Stork will then distribute these files to your nodes and perform the tasks you assigned.\r
84 \r
85 ***Pacman Groups***\r
86         Your pacman groups file allows you organize your nodes into separate groups.  You are allowed to include a node into a group or exclude a node from a group.  You can also include, exclude, or intersect groups with each other.  To define our groups, we can use:\r
87 \r
88         storkutil pacgroups (include|exclude|intersect|remove) GROUP NAME [NAME...]\r
89 \r
90 Let's start by adding a node to a group. If a pacman group file for your username does not exist, then storkutil will create a new one.\r
91 \r
92         storkutil pacgroups include myGroup planetlab.foo.edu\r
93 \r
94 Storkutil will automatically sign the file using your default private key\r
95 file, which you created when you generated your first key pairs (link).  If you want to use a username that is not your default, you can use the --username option to work on a different file.\r
96 \r
97 We can continue adding more data into our group definitions.  If you want to view the contents of the group file, you can use the “view” command in StorkUtil.\r
98 \r
99         storkutil pacgroups include __  (multiple nodes)\r
100         storkutil pacgroups exclude __\r
101         storkutil view groups\r
102 \r
103 As well as remove entries\r
104 \r
105         storkutil pacgroups remove __\r
106         storkutil view groups\r
107 \r
108 When you are done, you can upload your file to the Stork repository.  (LINK to upload instructions).\r
109 \r
110 \r
111 \r
112 ***Pacman Packages***\r
113         The pacman packages file allows you to manage which packages to install on which nodes.  With the pacman packages file, you can tell a node or group (as defined by your pacman groups file (LINK)) to install or uninstall a package.  To create and modify our packages file, we will use:\r
114 \r
115         storkutil pacpackages (node|group) NAME (install|remove|upgrade) PACKAGE [PACKAGE]\r
116 \r
117 We can start by assigning a node to install a package.  Be sure your filename follows the pattern <name>.packages.pacman, where the name is the one your configured in your stork.conf file (possible link?).  This will aid your nodes in finding the correct group file to use.  If the file you specified does not exist, then storkutil will create a new one.\r
118 \r
119         storkutil pacpackages node planetlab.foo.edu install gnuchess\r
120 \r
121 We can also assign groups to install or remove packages.  You can also list a\r
122 \r
123         storkutil pacpackages group MyGroup install lynx man gnuchess\r
124 \r
125 Storkutil will automatically sign the file using your default private key file, which you created when you generated your first key pairs (link).  If you want to work using a different set of keys and files, you can use the --username option.\r
126 \r
127 You can view the contents of your package file using the view command in Storkutil. (view to be coded)\r
128 \r
129         storkutil view packages\r
130 \r
131 When you are done, you can upload your file to the Stork repository.  (LINK).\r
132 \r