1 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
4 <meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
5 <title>The registry Module</title>
8 <h1>The registry Module</h1>
9 <p>Geni Registry Wrapper
11 This wrapper implements the Geni Registry.
13 There are several items that need to be done before starting the registry.
15 1) Update util/config.py to match the parameters of your PLC installation.
17 2) Import the existing planetlab database, creating the
18 appropriate geni records. This is done by running the "import.py" tool.
20 3) Create a "trusted_roots" 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 "planetlab.gid". For example,
24 mkdir trusted_roots; cp authorities/planetlab.gid trusted_roots/</p>
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>
28 <p>Convert geni fields to PLC fields for use when registering up updating
29 registry record in the PLC database</p>
33 type of record (user, slice, ...)</dd>
36 human readable name</dd>
37 <dt><i>geni_fields</i></dt>
39 dictionary of geni fields</dd>
40 <dt><i>pl_fields</i></dt>
42 dictionary of PLC fields (output)</dd>
45 <dt><b>Registry(ip, port, key_file, cert_file)</b> (class) [<a href='#registry.Registry-class'>#</a>]</dt>
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>
51 <h2><a id='registry.Registry-class' name='registry.Registry-class'>The Registry Class</a></h2>
53 <dt><b>Registry(ip, port, key_file, cert_file)</b> (class) [<a href='#registry.Registry-class'>#</a>]</dt>
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>
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>
61 <p>Connect to a local shell via local API functions</p>
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>
65 <p>Connect to a remote shell via XMLRPC</p>
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>
69 <p>GENI_API: Create_gid
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>
77 credential of caller</dd>
83 unique identifier for new GID</dd>
84 <dt><i>pkey_string</i></dt>
86 public-key string (TODO: why is this a string and not a keypair object?)</dd>
89 the string representation of a GID object</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>
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 "refresh", "resolve", and "info".</p>
100 the type of the object (user | sa | ma | slice | node)</dd>
103 human readable name of the object (not used at this time)</dd>
106 RightList object containing rights</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>
111 <p>Fill in the geni-specific fields of the record.
113 Note: It is assumed the fill_record_pl_info() has already been performed
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>
118 <p>Given a Geni record, fill in the PLC-specific and Geni-specific fields
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>
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
127 PLC data is filled into the pl_info field of the record.</p>
129 <dt><i>record</i></dt>
131 record to fill in fields (in/out param)</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>
136 <p>Given an authority name, return the information for that authority. This
137 is basically a stub that calls the hierarchy module.</p>
139 <dt><i>auth_hrn</i></dt>
141 human readable name of authority</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>
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
150 <dt><i>auth_name</i></dt>
152 human readable name of authority</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>
157 <p>GENI API: Get_credential
159 Retrieve a credential for an object.
161 If cred==None, then the behavior reverts to get_self_credential()</p>
165 credential object specifying rights of the caller</dd>
168 type of object (user | slice | sa | ma | node)</dd>
171 human readable name of object</dd>
174 the string representation of a credental object</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>
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>
190 the string representation of a GID object</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>
195 <p>GENI API: Get_self_credential
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,...).
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>
209 type of object (user | slice | sa | ma | node</dd>
212 human readable name of object</dd>
215 the string representation of a credential object</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>
220 <p>GENI API: get_ticket
222 Retrieve a ticket. This operation is currently implemented on the
223 registry (see SFA, engineering decisions), and is not implemented on
226 The ticket is filled in with information from the PLC database. This
227 information includes resources, and attributes such as user keys and
232 credential string</dd>
235 name of the slice to retrieve a ticket for</dd>
236 <dt><i>rspec</i></dt>
238 resource specification dictionary</dd>
241 the string representation of a ticket object</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>
246 <p>List the records in an authority. The objectGID in the supplied credential
247 should name the authority that will be listed.
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>
255 credential string specifying rights of the caller</dd>
258 list of record dictionaries</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="*")</b></a> [<a href='#registry.Registry.lookup_users-method'>#</a>]</dt>
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>
266 <dt><i>auth_table</i></dt>
268 database table for the authority that holds the user records</dd>
269 <dt><i>user_id_list</i></dt>
271 list of user ids</dd>
274 either "*" or a string describing the role to look for ("pi", "user", ...)
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>
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>
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
288 Attributes are non-resource items, such as keys and the initscript
289 RSpec is a set of resource specifications</p>
291 <dt><i>record</i></dt>
296 a tuple (attrs, rspec) of dictionaries</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>
301 <p>GENI API: register
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
309 credential string</dd>
310 <dt><i>record_dict</i></dt>
312 dictionary containing record fields</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>
317 <p>Register the server RPCs for the registry</p>
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>
323 Remove an object from the registry. If the object represents a PLC object,
324 then the PLC records will also be removed.</p>
328 credential string</dd>
329 <dt><i>record_dict</i></dt>
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>
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>
341 This is a wrapper around resolve_raw that converts records objects into
342 dictionaries before returning them to the user.</p>
346 credential string authorizing the caller</dd>
349 human readable name to resolve</dd>
352 a list of record dictionaries, or an empty list</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>
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>
363 type of record to resolve (user | sa | ma | slice | node)</dd>
366 human readable name of object</dd>
367 <dt><i>must_exist</i></dt>
369 if True, throw an exception if no records are found</dd>
372 a list of record objects, or an empty list []</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>
377 <p>GENI API: Register
379 Update an object in the registry. Currently, this only updates the
380 PLC information associated with the record. The Geni fields (name, type,
383 The record is expected to have the pl_info field filled in with the data
384 that should be updated.
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>
391 credential string specifying rights of the caller</dd>
392 <dt><i>record</i></dt>
394 a record dictionary to be updated</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>
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>
404 <dt><i>auth_name</i></dt>
406 human readable name of authority</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>
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>
417 human readable name of object</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>
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>
429 human readable name to test</dd>