fix ASAP duration
[sfa.git] / docs / pythondoc-registry.html
1 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
2 <html>
3 <head>
4 <meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
5 <title>The registry Module</title>
6 </head>
7 <body>
8 <h1>The registry Module</h1>
9 <p>Geni Registry Wrapper
10
11 This wrapper implements the Geni Registry.
12
13 There are several items that need to be done before starting the registry.
14
15 1) Update util/config.py to match the parameters of your PLC installation.
16
17 2) Import the existing planetlab database, creating the
18 appropriate geni records. This is done by running the &quot;import.py&quot; tool.
19
20 3) Create a &quot;trusted_roots&quot; directory and place the certificate of the root
21 authority in that directory. Given the defaults in import.py, this certificate
22 would be named &quot;planetlab.gid&quot;. For example,
23
24    mkdir trusted_roots; cp authorities/planetlab.gid trusted_roots/</p>
25 <dl>
26 <dt><a id='registry.geni_fields_to_pl_fields-function' name='registry.geni_fields_to_pl_fields-function'><b>geni_fields_to_pl_fields(type, hrn, geni_fields, pl_fields)</b></a> [<a href='#registry.geni_fields_to_pl_fields-function'>#</a>]</dt>
27 <dd>
28 <p>Convert geni fields to PLC fields for use when registering up updating
29 registry record in the PLC database</p>
30 <dl>
31 <dt><i>type</i></dt>
32 <dd>
33 type of record (user, slice, ...)</dd>
34 <dt><i>hrn</i></dt>
35 <dd>
36 human readable name</dd>
37 <dt><i>geni_fields</i></dt>
38 <dd>
39 dictionary of geni fields</dd>
40 <dt><i>pl_fields</i></dt>
41 <dd>
42 dictionary of PLC fields (output)</dd>
43 </dl><br />
44 </dd>
45 <dt><b>Registry(ip, port, key_file, cert_file)</b> (class) [<a href='#registry.Registry-class'>#</a>]</dt>
46 <dd>
47 <p>Registry is a GeniServer that serves registry requests.</p>
48 <p>For more information about this class, see <a href='#registry.Registry-class'><i>The Registry Class</i></a>.</p>
49 </dd>
50 </dl>
51 <h2><a id='registry.Registry-class' name='registry.Registry-class'>The Registry Class</a></h2>
52 <dl>
53 <dt><b>Registry(ip, port, key_file, cert_file)</b> (class) [<a href='#registry.Registry-class'>#</a>]</dt>
54 <dd>
55 <p>Registry is a GeniServer that serves registry requests. It also serves
56 component and slice operations that are implemented on the registry
57 due to SFA engineering decisions</p>
58 </dd>
59 <dt><a id='registry.Registry.connect_local_shell-method' name='registry.Registry.connect_local_shell-method'><b>connect_local_shell()</b></a> [<a href='#registry.Registry.connect_local_shell-method'>#</a>]</dt>
60 <dd>
61 <p>Connect to a local shell via local API functions</p>
62 </dd>
63 <dt><a id='registry.Registry.connect_remote_shell-method' name='registry.Registry.connect_remote_shell-method'><b>connect_remote_shell()</b></a> [<a href='#registry.Registry.connect_remote_shell-method'>#</a>]</dt>
64 <dd>
65 <p>Connect to a remote shell via XMLRPC</p>
66 </dd>
67 <dt><a id='registry.Registry.create_gid-method' name='registry.Registry.create_gid-method'><b>create_gid(cred, name, uuid, pubkey_str)</b></a> [<a href='#registry.Registry.create_gid-method'>#</a>]</dt>
68 <dd>
69 <p>GENI_API: Create_gid
70
71 Create a new GID. For MAs and SAs that are physically located on the
72 registry, this allows a owner/operator/PI to create a new GID and have it
73 signed by his respective authority.</p>
74 <dl>
75 <dt><i>cred</i></dt>
76 <dd>
77 credential of caller</dd>
78 <dt><i>name</i></dt>
79 <dd>
80 hrn for new GID</dd>
81 <dt><i>uuid</i></dt>
82 <dd>
83 unique identifier for new GID</dd>
84 <dt><i>pkey_string</i></dt>
85 <dd>
86 public-key string (TODO: why is this a string and not a keypair object?)</dd>
87 <dt>Returns:</dt>
88 <dd>
89 the string representation of a GID object</dd>
90 </dl><br />
91 </dd>
92 <dt><a id='registry.Registry.determine_rights-method' name='registry.Registry.determine_rights-method'><b>determine_rights(type, name)</b></a> [<a href='#registry.Registry.determine_rights-method'>#</a>]</dt>
93 <dd>
94 <p>Determine tje rights that an object should have. The rights are entirely
95 dependent on the type of the object. For example, users automatically
96 get &quot;refresh&quot;, &quot;resolve&quot;, and &quot;info&quot;.</p>
97 <dl>
98 <dt><i>type</i></dt>
99 <dd>
100 the type of the object (user | sa | ma | slice | node)</dd>
101 <dt><i>name</i></dt>
102 <dd>
103 human readable name of the object (not used at this time)</dd>
104 <dt>Returns:</dt>
105 <dd>
106 RightList object containing rights</dd>
107 </dl><br />
108 </dd>
109 <dt><a id='registry.Registry.fill_record_geni_info-method' name='registry.Registry.fill_record_geni_info-method'><b>fill_record_geni_info(record)</b></a> [<a href='#registry.Registry.fill_record_geni_info-method'>#</a>]</dt>
110 <dd>
111 <p>Fill in the geni-specific fields of the record.
112
113 Note: It is assumed the fill_record_pl_info() has already been performed
114 on the record.</p>
115 </dd>
116 <dt><a id='registry.Registry.fill_record_info-method' name='registry.Registry.fill_record_info-method'><b>fill_record_info(record)</b></a> [<a href='#registry.Registry.fill_record_info-method'>#</a>]</dt>
117 <dd>
118 <p>Given a Geni record, fill in the PLC-specific and Geni-specific fields
119 in the record.</p>
120 </dd>
121 <dt><a id='registry.Registry.fill_record_pl_info-method' name='registry.Registry.fill_record_pl_info-method'><b>fill_record_pl_info(record)</b></a> [<a href='#registry.Registry.fill_record_pl_info-method'>#</a>]</dt>
122 <dd>
123 <p>Fill in the planetlab-specific fields of a Geni record. This involves
124 calling the appropriate PLC methods to retrieve the database record for
125 the object.
126
127 PLC data is filled into the pl_info field of the record.</p>
128 <dl>
129 <dt><i>record</i></dt>
130 <dd>
131 record to fill in fields (in/out param)</dd>
132 </dl><br />
133 </dd>
134 <dt><a id='registry.Registry.get_auth_info-method' name='registry.Registry.get_auth_info-method'><b>get_auth_info(auth_hrn)</b></a> [<a href='#registry.Registry.get_auth_info-method'>#</a>]</dt>
135 <dd>
136 <p>Given an authority name, return the information for that authority. This
137 is basically a stub that calls the hierarchy module.</p>
138 <dl>
139 <dt><i>auth_hrn</i></dt>
140 <dd>
141 human readable name of authority</dd>
142 </dl><br />
143 </dd>
144 <dt><a id='registry.Registry.get_auth_table-method' name='registry.Registry.get_auth_table-method'><b>get_auth_table(auth_name)</b></a> [<a href='#registry.Registry.get_auth_table-method'>#</a>]</dt>
145 <dd>
146 <p>Given an authority name, return the database table for that authority. If
147 the database table does not exist, then one will be automatically
148 created.</p>
149 <dl>
150 <dt><i>auth_name</i></dt>
151 <dd>
152 human readable name of authority</dd>
153 </dl><br />
154 </dd>
155 <dt><a id='registry.Registry.get_credential-method' name='registry.Registry.get_credential-method'><b>get_credential(cred, type, name)</b></a> [<a href='#registry.Registry.get_credential-method'>#</a>]</dt>
156 <dd>
157 <p>GENI API: Get_credential
158
159 Retrieve a credential for an object.
160
161 If cred==None, then the behavior reverts to get_self_credential()</p>
162 <dl>
163 <dt><i>cred</i></dt>
164 <dd>
165 credential object specifying rights of the caller</dd>
166 <dt><i>type</i></dt>
167 <dd>
168 type of object (user | slice | sa | ma | node)</dd>
169 <dt><i>name</i></dt>
170 <dd>
171 human readable name of object</dd>
172 <dt>Returns:</dt>
173 <dd>
174 the string representation of a credental object</dd>
175 </dl><br />
176 </dd>
177 <dt><a id='registry.Registry.get_gid-method' name='registry.Registry.get_gid-method'><b>get_gid(name)</b></a> [<a href='#registry.Registry.get_gid-method'>#</a>]</dt>
178 <dd>
179 <p>GENI API: get_gid
180
181 Retrieve the GID for an object. This function looks up a record in the
182 registry and returns the GID of the record if it exists.
183 TODO: Is this function needed? It's a shortcut for Resolve()</p>
184 <dl>
185 <dt><i>name</i></dt>
186 <dd>
187 hrn to look up</dd>
188 <dt>Returns:</dt>
189 <dd>
190 the string representation of a GID object</dd>
191 </dl><br />
192 </dd>
193 <dt><a id='registry.Registry.get_self_credential-method' name='registry.Registry.get_self_credential-method'><b>get_self_credential(type, name)</b></a> [<a href='#registry.Registry.get_self_credential-method'>#</a>]</dt>
194 <dd>
195 <p>GENI API: Get_self_credential
196
197 Get_self_credential a degenerate version of get_credential used by a
198 client to get his initial credential when he doesn't have one. This is
199 the same as get_credential(..., cred=None,...).
200
201 The registry ensures that the client is the principal that is named by
202 (type, name) by comparing the public key in the record's GID to the
203 private key used to encrypt the client-side of the HTTPS connection. Thus
204 it is impossible for one principal to retrieve another principal's
205 credential without having the appropriate private key.</p>
206 <dl>
207 <dt><i>type</i></dt>
208 <dd>
209 type of object (user | slice | sa | ma | node</dd>
210 <dt><i>name</i></dt>
211 <dd>
212 human readable name of object</dd>
213 <dt>Returns:</dt>
214 <dd>
215 the string representation of a credential object</dd>
216 </dl><br />
217 </dd>
218 <dt><a id='registry.Registry.get_ticket-method' name='registry.Registry.get_ticket-method'><b>get_ticket(cred, name, rspec)</b></a> [<a href='#registry.Registry.get_ticket-method'>#</a>]</dt>
219 <dd>
220 <p>GENI API: get_ticket
221
222 Retrieve a ticket. This operation is currently implemented on the
223 registry (see SFA, engineering decisions), and is not implemented on
224 components.
225
226 The ticket is filled in with information from the PLC database. This
227 information includes resources, and attributes such as user keys and
228 initscripts.</p>
229 <dl>
230 <dt><i>cred</i></dt>
231 <dd>
232 credential string</dd>
233 <dt><i>name</i></dt>
234 <dd>
235 name of the slice to retrieve a ticket for</dd>
236 <dt><i>rspec</i></dt>
237 <dd>
238 resource specification dictionary</dd>
239 <dt>Returns:</dt>
240 <dd>
241 the string representation of a ticket object</dd>
242 </dl><br />
243 </dd>
244 <dt><a id='registry.Registry.list-method' name='registry.Registry.list-method'><b>list(cred)</b></a> [<a href='#registry.Registry.list-method'>#</a>]</dt>
245 <dd>
246 <p>List the records in an authority. The objectGID in the supplied credential
247 should name the authority that will be listed.
248
249 TODO: List doesn't take an hrn and uses the hrn contained in the
250    objectGid of the credential. Does this mean the only way to list an
251    authority is by having a credential for that authority?</p>
252 <dl>
253 <dt><i>cred</i></dt>
254 <dd>
255 credential string specifying rights of the caller</dd>
256 <dt>Returns:</dt>
257 <dd>
258 list of record dictionaries</dd>
259 </dl><br />
260 </dd>
261 <dt><a id='registry.Registry.lookup_users-method' name='registry.Registry.lookup_users-method'><b>lookup_users(auth_table, user_id_list, role=&quot;*&quot;)</b></a> [<a href='#registry.Registry.lookup_users-method'>#</a>]</dt>
262 <dd>
263 <p>Look up user records given PLC user-ids. This is used as part of the
264 process for reverse-mapping PLC records into Geni records.</p>
265 <dl>
266 <dt><i>auth_table</i></dt>
267 <dd>
268 database table for the authority that holds the user records</dd>
269 <dt><i>user_id_list</i></dt>
270 <dd>
271 list of user ids</dd>
272 <dt><i>role</i></dt>
273 <dd>
274 either &quot;*&quot; or a string describing the role to look for (&quot;pi&quot;, &quot;user&quot;, ...)
275
276 TODO: This function currently only searches one authority because it would
277 be inefficient to brute-force search all authorities for a user id. The
278 solution would likely be to implement a reverse mapping of user-id to
279 (type, hrn) pairs.</dd>
280 </dl><br />
281 </dd>
282 <dt><a id='registry.Registry.record_to_slice_info-method' name='registry.Registry.record_to_slice_info-method'><b>record_to_slice_info(record)</b></a> [<a href='#registry.Registry.record_to_slice_info-method'>#</a>]</dt>
283 <dd>
284 <p>Convert a PLC record into the slice information that will be stored in
285 a ticket. There are two parts to this information: attributes and
286 rspec.
287
288 Attributes are non-resource items, such as keys and the initscript
289 RSpec is a set of resource specifications</p>
290 <dl>
291 <dt><i>record</i></dt>
292 <dd>
293 a record object</dd>
294 <dt>Returns:</dt>
295 <dd>
296 a tuple (attrs, rspec) of dictionaries</dd>
297 </dl><br />
298 </dd>
299 <dt><a id='registry.Registry.register-method' name='registry.Registry.register-method'><b>register(cred, record_dict)</b></a> [<a href='#registry.Registry.register-method'>#</a>]</dt>
300 <dd>
301 <p>GENI API: register
302
303 Register an object with the registry. In addition to being stored in the
304 Geni database, the appropriate records will also be created in the
305 PLC databases</p>
306 <dl>
307 <dt><i>cred</i></dt>
308 <dd>
309 credential string</dd>
310 <dt><i>record_dict</i></dt>
311 <dd>
312 dictionary containing record fields</dd>
313 </dl><br />
314 </dd>
315 <dt><a id='registry.Registry.register_functions-method' name='registry.Registry.register_functions-method'><b>register_functions()</b></a> [<a href='#registry.Registry.register_functions-method'>#</a>]</dt>
316 <dd>
317 <p>Register the server RPCs for the registry</p>
318 </dd>
319 <dt><a id='registry.Registry.remove-method' name='registry.Registry.remove-method'><b>remove(cred, record_dict)</b></a> [<a href='#registry.Registry.remove-method'>#</a>]</dt>
320 <dd>
321 <p>GENI API: remove
322
323 Remove an object from the registry. If the object represents a PLC object,
324 then the PLC records will also be removed.</p>
325 <dl>
326 <dt><i>cred</i></dt>
327 <dd>
328 credential string</dd>
329 <dt><i>record_dict</i></dt>
330 <dd>
331 dictionary containing record fields. The only relevant
332     fields of the record are 'name' and 'type', which are used to lookup
333     the current copy of the record in the Geni database, to make sure
334     that the appopriate record is removed.</dd>
335 </dl><br />
336 </dd>
337 <dt><a id='registry.Registry.resolve-method' name='registry.Registry.resolve-method'><b>resolve(cred, name)</b></a> [<a href='#registry.Registry.resolve-method'>#</a>]</dt>
338 <dd>
339 <p>GENI API: Resolve
340
341 This is a wrapper around resolve_raw that converts records objects into
342 dictionaries before returning them to the user.</p>
343 <dl>
344 <dt><i>cred</i></dt>
345 <dd>
346 credential string authorizing the caller</dd>
347 <dt><i>name</i></dt>
348 <dd>
349 human readable name to resolve</dd>
350 <dt>Returns:</dt>
351 <dd>
352 a list of record dictionaries, or an empty list</dd>
353 </dl><br />
354 </dd>
355 <dt><a id='registry.Registry.resolve_raw-method' name='registry.Registry.resolve_raw-method'><b>resolve_raw(type, name, must_exist=True)</b></a> [<a href='#registry.Registry.resolve_raw-method'>#</a>]</dt>
356 <dd>
357 <p>Resolve a record. This is an internal version of the Resolve API call
358 and returns records in record object format rather than dictionaries
359 that may be sent over XMLRPC.</p>
360 <dl>
361 <dt><i>type</i></dt>
362 <dd>
363 type of record to resolve (user | sa | ma | slice | node)</dd>
364 <dt><i>name</i></dt>
365 <dd>
366 human readable name of object</dd>
367 <dt><i>must_exist</i></dt>
368 <dd>
369 if True, throw an exception if no records are found</dd>
370 <dt>Returns:</dt>
371 <dd>
372 a list of record objects, or an empty list []</dd>
373 </dl><br />
374 </dd>
375 <dt><a id='registry.Registry.update-method' name='registry.Registry.update-method'><b>update(cred, record_dict)</b></a> [<a href='#registry.Registry.update-method'>#</a>]</dt>
376 <dd>
377 <p>GENI API: Register
378
379 Update an object in the registry. Currently, this only updates the
380 PLC information associated with the record. The Geni fields (name, type,
381 GID) are fixed.
382
383 The record is expected to have the pl_info field filled in with the data
384 that should be updated.
385
386 TODO: The geni_info member of the record should be parsed and the pl_info
387 adjusted as necessary (add/remove users from a slice, etc)</p>
388 <dl>
389 <dt><i>cred</i></dt>
390 <dd>
391 credential string specifying rights of the caller</dd>
392 <dt><i>record</i></dt>
393 <dd>
394 a record dictionary to be updated</dd>
395 </dl><br />
396 </dd>
397 <dt><a id='registry.Registry.verify_auth_belongs_to_me-method' name='registry.Registry.verify_auth_belongs_to_me-method'><b>verify_auth_belongs_to_me(name)</b></a> [<a href='#registry.Registry.verify_auth_belongs_to_me-method'>#</a>]</dt>
398 <dd>
399 <p>Verify that an authority belongs to this registry. This is basically left
400 up to the implementation of the hierarchy module. If the specified name
401 does not belong to this registry, an exception is thrown indicating the
402 caller should contact someone else.</p>
403 <dl>
404 <dt><i>auth_name</i></dt>
405 <dd>
406 human readable name of authority</dd>
407 </dl><br />
408 </dd>
409 <dt><a id='registry.Registry.verify_object_belongs_to_me-method' name='registry.Registry.verify_object_belongs_to_me-method'><b>verify_object_belongs_to_me(name)</b></a> [<a href='#registry.Registry.verify_object_belongs_to_me-method'>#</a>]</dt>
410 <dd>
411 <p>Verify that an object belongs to this registry. By extension, this implies
412 that the authority that owns the object belongs to this registry. If the
413 object does not belong to this registry, then an exception is thrown.</p>
414 <dl>
415 <dt><i>name</i></dt>
416 <dd>
417 human readable name of object</dd>
418 </dl><br />
419 </dd>
420 <dt><a id='registry.Registry.verify_object_permission-method' name='registry.Registry.verify_object_permission-method'><b>verify_object_permission(name)</b></a> [<a href='#registry.Registry.verify_object_permission-method'>#</a>]</dt>
421 <dd>
422 <p>Verify that the object_gid that was specified in the credential allows
423 permission to the object 'name'. This is done by a simple prefix test.
424 For example, an object_gid for planetlab.us.arizona would match the
425 objects planetlab.us.arizona.slice1 and planetlab.us.arizona.</p>
426 <dl>
427 <dt><i>name</i></dt>
428 <dd>
429 human readable name to test</dd>
430 </dl><br />
431 </dd>
432 </dl>
433 </body></html>