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 geniclient Module</title>
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.
13 TODO: Investigate ways to combine this with existing PLC API?</p>
15 <dt><b>GeniClient(url, key_file, cert_file)</b> (class) [<a href='#geniclient.GeniClient-class'>#</a>]</dt>
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>
20 <dt><b>GeniTransport</b> (class) [<a href='#geniclient.GeniTransport-class'>#</a>]</dt>
22 <p>For more information about this class, see <a href='#geniclient.GeniTransport-class'><i>The GeniTransport Class</i></a>.</p>
24 <dt><b>ServerException</b> (class) [<a href='#geniclient.ServerException-class'>#</a>]</dt>
26 <p>ServerException, ExceptionUnmarshaller
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>
32 <h2><a id='geniclient.GeniClient-class' name='geniclient.GeniClient-class'>The GeniClient Class</a></h2>
34 <dt><b>GeniClient(url, key_file, cert_file)</b> (class) [<a href='#geniclient.GeniClient-class'>#</a>]</dt>
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.
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>
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>
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>
53 credential of caller</dd>
59 unique identifier for new GID</dd>
60 <dt><i>pkey_string</i></dt>
62 public-key string (TODO: why is this a string and not a keypair object?)</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>
70 <p>Delete a slice.</p>
74 a credential identifying the caller (callerGID) and the slice
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>
80 <p>Retrieve a credential for an object.
82 If cred==None, then the behavior reverts to get_self_credential()</p>
86 credential object specifying rights of the caller</dd>
89 type of object (user | slice | sa | ma | node)</dd>
92 human readable name of object</dd>
95 a credental object</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>
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>
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>
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,...).
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>
126 type of object (user | slice | sa | ma | node</dd>
129 human readable name of object</dd>
132 a credential object</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>
137 <p>Retrieve a ticket. This operation is currently implemented on the
138 registry (see SFA, engineering decisions), and is not implemented on
141 The ticket is filled in with information from the PLC database. This
142 information includes resources, and attributes such as user keys and
147 credential object</dd>
150 name of the slice to retrieve a ticket for</dd>
151 <dt><i>rspec</i></dt>
153 resource specification dictionary</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>
161 <p>List the records in an authority. The objectGID in the supplied credential
162 should name the authority that will be listed.</p>
166 credential object specifying rights of the caller</dd>
169 list of record objects</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>
174 <p>List the slices on a component.</p>
178 credential object that authorizes the caller</dd>
181 a list of slice names</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>
186 <p>Redeem a ticket. This operation is currently implemented on the
189 The ticket is submitted to the node manager, and the slice is instantiated
190 or updated as appropriate.
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>
196 <dt><i>ticket</i></dt>
198 a ticket object containing the ticket</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>
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
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.
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>
215 credential object specifying rights of the caller</dd>
218 record to register</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>
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>
228 credential object specifying rights of the caller</dd>
229 <dt><i>record</i></dt>
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>
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>
239 <p>Reset a slice.</p>
243 a credential identifying the caller (callerGID) and the slice
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>
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>
256 credential object specifying rights of the caller</dd>
259 human readable name of object</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>
264 <p>Start a slice.</p>
268 a credential identifying the caller (callerGID) and the slice
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>
278 a credential identifying the caller (callerGID) and the slice
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>
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,
288 The record is expected to have the pl_info field filled in with the data
289 that should be updated.
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>
296 credential object specifying rights of the caller</dd>
297 <dt><i>record</i></dt>
299 a record object to be updated</dd>
303 <h2><a id='geniclient.GeniTransport-class' name='geniclient.GeniTransport-class'>The GeniTransport Class</a></h2>
305 <dt><b>GeniTransport</b> (class) [<a href='#geniclient.GeniTransport-class'>#</a>]</dt>
309 A transport for XMLRPC that works on top of HTTPS</p>
312 <h2><a id='geniclient.ServerException-class' name='geniclient.ServerException-class'>The ServerException Class</a></h2>
314 <dt><b>ServerException</b> (class) [<a href='#geniclient.ServerException-class'>#</a>]</dt>
316 <p>ServerException, ExceptionUnmarshaller
318 Used to convert server exception strings back to an exception.
319 from usenet, Raghuram Devarakonda</p>