docs/pythondoc-geniclient.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 geniclient Module</title>
   6 </head>
   7 <body>
   8 <h1>The geniclient Module</h1>
   9 <p>This module implements the client-side of the Geni API. Stubs are provided
  10 that convert the supplied parameters to the necessary format and send them
  11 via XMLRPC to a Geni Server.
  12
  13 TODO: Investigate ways to combine this with existing PLC API?</p>
  14 <dl>
  15 <dt><b>GeniClient(url, key_file, cert_file)</b> (class) [<a href='#geniclient.GeniClient-class'>#</a>]</dt>
  16 <dd>
  17 <p>The GeniClient class provides stubs for executing Geni operations.</p>
  18 <p>For more information about this class, see <a href='#geniclient.GeniClient-class'><i>The GeniClient Class</i></a>.</p>
  19 </dd>
  20 <dt><b>GeniTransport</b> (class)  [<a href='#geniclient.GeniTransport-class'>#</a>]</dt>
  21 <dd>
  22 <p>For more information about this class, see <a href='#geniclient.GeniTransport-class'><i>The GeniTransport Class</i></a>.</p>
  23 </dd>
  24 <dt><b>ServerException</b> (class)  [<a href='#geniclient.ServerException-class'>#</a>]</dt>
  25 <dd>
  26 <p>ServerException, ExceptionUnmarshaller
  27
  28 Used to convert server exception strings back to an exception.</p>
  29 <p>For more information about this class, see <a href='#geniclient.ServerException-class'><i>The ServerException Class</i></a>.</p>
  30 </dd>
  31 </dl>
  32 <h2><a id='geniclient.GeniClient-class' name='geniclient.GeniClient-class'>The GeniClient Class</a></h2>
  33 <dl>
  34 <dt><b>GeniClient(url, key_file, cert_file)</b> (class) [<a href='#geniclient.GeniClient-class'>#</a>]</dt>
  35 <dd>
  36 <p>The GeniClient class provides stubs for executing Geni operations. A given
  37 client object connects to one server. To connect to multiple servers, create
  38 multiple GeniClient objects.
  39
  40 The Geni protocol uses an HTTPS connection, and the client's side of the
  41 connection uses his private key. Generally, this private key must match the
  42 public key that is containing in the GID that the client is providing for
  43 those functions that take a GID.</p>
  44 </dd>
  45 <dt><a id='geniclient.GeniClient.create_gid-method' name='geniclient.GeniClient.create_gid-method'><b>create_gid(cred, name, uuid, pkey_string)</b></a> [<a href='#geniclient.GeniClient.create_gid-method'>#</a>]</dt>
  46 <dd>
  47 <p>Create a new GID. For MAs and SAs that are physically located on the
  48 registry, this allows a owner/operator/PI to create a new GID and have it
  49 signed by his respective authority.</p>
  50 <dl>
  51 <dt><i>cred</i></dt>
  52 <dd>
  53 credential of caller</dd>
  54 <dt><i>name</i></dt>
  55 <dd>
  56 hrn for new GID</dd>
  57 <dt><i>uuid</i></dt>
  58 <dd>
  59 unique identifier for new GID</dd>
  60 <dt><i>pkey_string</i></dt>
  61 <dd>
  62 public-key string (TODO: why is this a string and not a keypair object?)</dd>
  63 <dt>Returns:</dt>
  64 <dd>
  65 a GID object</dd>
  66 </dl><br />
  67 </dd>
  68 <dt><a id='geniclient.GeniClient.delete_slice-method' name='geniclient.GeniClient.delete_slice-method'><b>delete_slice(cred)</b></a> [<a href='#geniclient.GeniClient.delete_slice-method'>#</a>]</dt>
  69 <dd>
  70 <p>Delete a slice.</p>
  71 <dl>
  72 <dt><i>cred</i></dt>
  73 <dd>
  74 a credential identifying the caller (callerGID) and the slice
  75     (objectGID)</dd>
  76 </dl><br />
  77 </dd>
  78 <dt><a id='geniclient.GeniClient.get_credential-method' name='geniclient.GeniClient.get_credential-method'><b>get_credential(cred, type, name)</b></a> [<a href='#geniclient.GeniClient.get_credential-method'>#</a>]</dt>
  79 <dd>
  80 <p>Retrieve a credential for an object.
  81
  82 If cred==None, then the behavior reverts to get_self_credential()</p>
  83 <dl>
  84 <dt><i>cred</i></dt>
  85 <dd>
  86 credential object specifying rights of the caller</dd>
  87 <dt><i>type</i></dt>
  88 <dd>
  89 type of object (user | slice | sa | ma | node)</dd>
  90 <dt><i>name</i></dt>
  91 <dd>
  92 human readable name of object</dd>
  93 <dt>Returns:</dt>
  94 <dd>
  95 a credental object</dd>
  96 </dl><br />
  97 </dd>
  98 <dt><a id='geniclient.GeniClient.get_gid-method' name='geniclient.GeniClient.get_gid-method'><b>get_gid(name)</b></a> [<a href='#geniclient.GeniClient.get_gid-method'>#</a>]</dt>
  99 <dd>
 100 <p>Retrieve the GID for an object. This function looks up a record in the
 101 registry and returns the GID of the record if it exists.
 102 TODO: Is this function needed? It's a shortcut for Resolve()</p>
 103 <dl>
 104 <dt><i>name</i></dt>
 105 <dd>
 106 hrn to look up</dd>
 107 <dt>Returns:</dt>
 108 <dd>
 109 a GID object</dd>
 110 </dl><br />
 111 </dd>
 112 <dt><a id='geniclient.GeniClient.get_self_credential-method' name='geniclient.GeniClient.get_self_credential-method'><b>get_self_credential(type, name)</b></a> [<a href='#geniclient.GeniClient.get_self_credential-method'>#</a>]</dt>
 113 <dd>
 114 <p>Get_self_credential a degenerate version of get_credential used by a
 115 client to get his initial credential when he doesn't have one. This is
 116 the same as get_credential(..., cred=None,...).
 117
 118 The registry ensures that the client is the principal that is named by
 119 (type, name) by comparing the public key in the record's GID to the
 120 private key used to encrypt the client-side of the HTTPS connection. Thus
 121 it is impossible for one principal to retrieve another principal's
 122 credential without having the appropriate private key.</p>
 123 <dl>
 124 <dt><i>type</i></dt>
 125 <dd>
 126 type of object (user | slice | sa | ma | node</dd>
 127 <dt><i>name</i></dt>
 128 <dd>
 129 human readable name of object</dd>
 130 <dt>Returns:</dt>
 131 <dd>
 132 a credential object</dd>
 133 </dl><br />
 134 </dd>
 135 <dt><a id='geniclient.GeniClient.get_ticket-method' name='geniclient.GeniClient.get_ticket-method'><b>get_ticket(cred, name, rspec)</b></a> [<a href='#geniclient.GeniClient.get_ticket-method'>#</a>]</dt>
 136 <dd>
 137 <p>Retrieve a ticket. This operation is currently implemented on the
 138 registry (see SFA, engineering decisions), and is not implemented on
 139 components.
 140
 141 The ticket is filled in with information from the PLC database. This
 142 information includes resources, and attributes such as user keys and
 143 initscripts.</p>
 144 <dl>
 145 <dt><i>cred</i></dt>
 146 <dd>
 147 credential object</dd>
 148 <dt><i>name</i></dt>
 149 <dd>
 150 name of the slice to retrieve a ticket for</dd>
 151 <dt><i>rspec</i></dt>
 152 <dd>
 153 resource specification dictionary</dd>
 154 <dt>Returns:</dt>
 155 <dd>
 156 a ticket object</dd>
 157 </dl><br />
 158 </dd>
 159 <dt><a id='geniclient.GeniClient.list-method' name='geniclient.GeniClient.list-method'><b>list(cred)</b></a> [<a href='#geniclient.GeniClient.list-method'>#</a>]</dt>
 160 <dd>
 161 <p>List the records in an authority. The objectGID in the supplied credential
 162 should name the authority that will be listed.</p>
 163 <dl>
 164 <dt><i>cred</i></dt>
 165 <dd>
 166 credential object specifying rights of the caller</dd>
 167 <dt>Returns:</dt>
 168 <dd>
 169 list of record objects</dd>
 170 </dl><br />
 171 </dd>
 172 <dt><a id='geniclient.GeniClient.list_slices-method' name='geniclient.GeniClient.list_slices-method'><b>list_slices(cred)</b></a> [<a href='#geniclient.GeniClient.list_slices-method'>#</a>]</dt>
 173 <dd>
 174 <p>List the slices on a component.</p>
 175 <dl>
 176 <dt><i>cred</i></dt>
 177 <dd>
 178 credential object that authorizes the caller</dd>
 179 <dt>Returns:</dt>
 180 <dd>
 181 a list of slice names</dd>
 182 </dl><br />
 183 </dd>
 184 <dt><a id='geniclient.GeniClient.redeem_ticket-method' name='geniclient.GeniClient.redeem_ticket-method'><b>redeem_ticket(ticket)</b></a> [<a href='#geniclient.GeniClient.redeem_ticket-method'>#</a>]</dt>
 185 <dd>
 186 <p>Redeem a ticket. This operation is currently implemented on the
 187 component.
 188
 189 The ticket is submitted to the node manager, and the slice is instantiated
 190 or updated as appropriate.
 191
 192 TODO: This operation should return a sliver credential and indicate
 193 whether or not the component will accept only sliver credentials, or
 194 will accept both sliver and slice credentials.</p>
 195 <dl>
 196 <dt><i>ticket</i></dt>
 197 <dd>
 198 a ticket object containing the ticket</dd>
 199 </dl><br />
 200 </dd>
 201 <dt><a id='geniclient.GeniClient.register-method' name='geniclient.GeniClient.register-method'><b>register(cred, record)</b></a> [<a href='#geniclient.GeniClient.register-method'>#</a>]</dt>
 202 <dd>
 203 <p>Register an object with the registry. In addition to being stored in the
 204 Geni database, the appropriate records will also be created in the
 205 PLC databases.
 206
 207 The geni_info and/or pl_info fields must in the record must be filled
 208 out correctly depending on the type of record that is being registered.
 209
 210 TODO: The geni_info member of the record should be parsed and the pl_info
 211 adjusted as necessary (add/remove users from a slice, etc)</p>
 212 <dl>
 213 <dt><i>cred</i></dt>
 214 <dd>
 215 credential object specifying rights of the caller</dd>
 216 <dt>Returns:</dt>
 217 <dd>
 218 record to register</dd>
 219 </dl><br />
 220 </dd>
 221 <dt><a id='geniclient.GeniClient.remove-method' name='geniclient.GeniClient.remove-method'><b>remove(cred, record)</b></a> [<a href='#geniclient.GeniClient.remove-method'>#</a>]</dt>
 222 <dd>
 223 <p>Remove an object from the registry. If the object represents a PLC object,
 224 then the PLC records will also be removed.</p>
 225 <dl>
 226 <dt><i>cred</i></dt>
 227 <dd>
 228 credential object specifying rights of the caller</dd>
 229 <dt><i>record</i></dt>
 230 <dd>
 231 record to register. The only relevant
 232     fields of the record are 'name' and 'type', which are used to lookup
 233     the current copy of the record in the Geni database, to make sure
 234     that the appopriate record is removed.</dd>
 235 </dl><br />
 236 </dd>
 237 <dt><a id='geniclient.GeniClient.reset_slice-method' name='geniclient.GeniClient.reset_slice-method'><b>reset_slice(cred)</b></a> [<a href='#geniclient.GeniClient.reset_slice-method'>#</a>]</dt>
 238 <dd>
 239 <p>Reset a slice.</p>
 240 <dl>
 241 <dt><i>cred</i></dt>
 242 <dd>
 243 a credential identifying the caller (callerGID) and the slice
 244     (objectGID)</dd>
 245 </dl><br />
 246 </dd>
 247 <dt><a id='geniclient.GeniClient.resolve-method' name='geniclient.GeniClient.resolve-method'><b>resolve(cred, name)</b></a> [<a href='#geniclient.GeniClient.resolve-method'>#</a>]</dt>
 248 <dd>
 249 <p>Resolve an object in the registry. A given HRN may have multiple records
 250 associated with it, and therefore multiple records may be returned. The
 251 caller should check the type fields of the records to find the one that
 252 he is interested in.</p>
 253 <dl>
 254 <dt><i>cred</i></dt>
 255 <dd>
 256 credential object specifying rights of the caller</dd>
 257 <dt><i>name</i></dt>
 258 <dd>
 259 human readable name of object</dd>
 260 </dl><br />
 261 </dd>
 262 <dt><a id='geniclient.GeniClient.start_slice-method' name='geniclient.GeniClient.start_slice-method'><b>start_slice(cred)</b></a> [<a href='#geniclient.GeniClient.start_slice-method'>#</a>]</dt>
 263 <dd>
 264 <p>Start a slice.</p>
 265 <dl>
 266 <dt><i>cred</i></dt>
 267 <dd>
 268 a credential identifying the caller (callerGID) and the slice
 269     (objectGID)</dd>
 270 </dl><br />
 271 </dd>
 272 <dt><a id='geniclient.GeniClient.stop_slice-method' name='geniclient.GeniClient.stop_slice-method'><b>stop_slice(cred)</b></a> [<a href='#geniclient.GeniClient.stop_slice-method'>#</a>]</dt>
 273 <dd>
 274 <p>Stop a slice.</p>
 275 <dl>
 276 <dt><i>cred</i></dt>
 277 <dd>
 278 a credential identifying the caller (callerGID) and the slice
 279     (objectGID)</dd>
 280 </dl><br />
 281 </dd>
 282 <dt><a id='geniclient.GeniClient.update-method' name='geniclient.GeniClient.update-method'><b>update(cred, record)</b></a> [<a href='#geniclient.GeniClient.update-method'>#</a>]</dt>
 283 <dd>
 284 <p>Update an object in the registry. Currently, this only updates the
 285 PLC information associated with the record. The Geni fields (name, type,
 286 GID) are fixed.
 287
 288 The record is expected to have the pl_info field filled in with the data
 289 that should be updated.
 290
 291 TODO: The geni_info member of the record should be parsed and the pl_info
 292 adjusted as necessary (add/remove users from a slice, etc)</p>
 293 <dl>
 294 <dt><i>cred</i></dt>
 295 <dd>
 296 credential object specifying rights of the caller</dd>
 297 <dt><i>record</i></dt>
 298 <dd>
 299 a record object to be updated</dd>
 300 </dl><br />
 301 </dd>
 302 </dl>
 303 <h2><a id='geniclient.GeniTransport-class' name='geniclient.GeniTransport-class'>The GeniTransport Class</a></h2>
 304 <dl>
 305 <dt><b>GeniTransport</b> (class)  [<a href='#geniclient.GeniTransport-class'>#</a>]</dt>
 306 <dd>
 307 <p>GeniTransport
 308
 309 A transport for XMLRPC that works on top of HTTPS</p>
 310 </dd>
 311 </dl>
 312 <h2><a id='geniclient.ServerException-class' name='geniclient.ServerException-class'>The ServerException Class</a></h2>
 313 <dl>
 314 <dt><b>ServerException</b> (class)  [<a href='#geniclient.ServerException-class'>#</a>]</dt>
 315 <dd>
 316 <p>ServerException, ExceptionUnmarshaller
 317
 318 Used to convert server exception strings back to an exception.
 319    from usenet, Raghuram Devarakonda</p>
 320 </dd>
 321 </dl>
 322 </body></html>