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>