creating tag sfa-0.9-11
[sfa.git] / 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>