Added debug code.
[nodemanager.git] / api_calls.py
1 #
2 """Sliver manager API.
3
4 This module exposes an XMLRPC interface that allows PlanetLab users to
5 create/destroy slivers with delegated instantiation, start and stop
6 slivers, make resource loans, and examine resource allocations.  The
7 XMLRPC is provided on a localhost-only TCP port as well as via a Unix
8 domain socket that is accessible by ssh-ing into a delegate account
9 with the forward_api_calls shell.
10 """
11
12 import SimpleXMLRPCServer
13 import SocketServer
14 import errno
15 import os
16 import pwd
17 import socket
18 import struct
19 import threading
20 import xmlrpclib
21 import slivermanager
22
23 try:
24     from PLC.Parameter import Parameter, Mixed
25 except:
26     def Parameter(a = None, b = None): pass
27     def Mixed(a = None, b = None, c = None): pass
28
29
30 import account
31 import logger
32
33 # TODO: These try/excepts are a hack to allow doc/DocBookLocal.py to
34 # import this file in order to extract the documentation from each
35 # exported function.
36 # A better approach will involve more extensive code splitting, I think.
37 try: import database
38 except: import logger as database
39 import ticket as ticket_module
40 import tools
41
42 deliver_ticket = None  # set in slivermanager.start()
43
44 api_method_dict = {}
45 nargs_dict = {}
46
47 def export_to_api(nargs):
48     def export(method):
49         nargs_dict[method.__name__] = nargs
50         api_method_dict[method.__name__] = method
51         return method
52     return export
53
54 def export_to_docbook(**kwargs):
55
56     keywords = {
57         "group" : "NMAPI",
58         "status" : "current",
59         "name": None,
60         "args": None,
61         "roles": [],
62         "accepts": [],
63         "returns": [],
64     }
65     def export(method):
66         def args():
67             # Inspect method. Remove self from the argument list.
68             max_args = method.func_code.co_varnames[0:method.func_code.co_argcount]
69             defaults = method.func_defaults
70             if defaults is None:
71                 defaults = ()
72             min_args = max_args[0:len(max_args) - len(defaults)]
73
74             defaults = tuple([None for arg in min_args]) + defaults
75             return (min_args, max_args, defaults)
76
77         keywords['name'] = method.__name__
78         keywords['args'] = args
79         for arg in keywords:
80             method.__setattr__(arg, keywords[arg])
81
82         for arg in kwargs:
83             method.__setattr__(arg, kwargs[arg])
84         return method
85
86     return export
87
88
89 # status
90 # roles,
91 # accepts,
92 # returns
93
94 @export_to_docbook(roles=['self'],
95                    accepts=[],
96                    returns=Parameter([], 'A list of supported functions'))
97 @export_to_api(0)
98 def Help():
99     """Get a list of functions currently supported by the Node Manager API"""
100     names=api_method_dict.keys()
101     names.sort()
102     return ''.join(['**** ' + api_method_dict[name].__name__ + '\n' + api_method_dict[name].__doc__ + '\n'
103                     for name in names])
104
105 @export_to_docbook(roles=['self'],
106                    accepts=[Parameter(str, 'A ticket returned from GetSliceTicket()')],
107                    returns=Parameter(int, '1 if successful'))
108 @export_to_api(1)
109 def Ticket(ticket):
110     """The Node Manager periodically polls the PLC API for a list of all
111     slices that are allowed to exist on the given node. Before
112     actions are performed on a delegated slice (such as creation),
113     a controller slice must deliver a valid slice ticket to NM.
114
115     This ticket is the value retured by PLC's GetSliceTicket() API call."""
116     try:
117         data = ticket_module.verify(ticket)
118         name = data['slivers'][0]['name']
119         if data != None:
120             deliver_ticket(data)
121         logger.log('api_calls: Ticket delivered for %s' % name)
122         Create(database.db.get(name))
123     except Exception, err:
124         raise xmlrpclib.Fault(102, 'Ticket error: ' + str(err))
125
126 @export_to_docbook(roles=['self'],
127                    accepts=[Parameter(str, 'A ticket returned from GetSlivers()')],
128                    returns=Parameter(int, '1 if successful'))
129 @export_to_api(1)
130 def AdminTicket(ticket):
131     """Admin interface to create slivers based on ticket returned by GetSlivers()."""
132     try:
133         data, = xmlrpclib.loads(ticket)[0]
134         name = data['slivers'][0]['name']
135         if data != None:
136             deliver_ticket(data)
137         logger.log('api_calls: Admin Ticket delivered for %s' % name)
138         Create(database.db.get(name))
139     except Exception, err:
140         raise xmlrpclib.Fault(102, 'Ticket error: ' + str(err))
141
142
143 @export_to_docbook(roles=['self'],
144                    accepts=[],
145                    returns={'sliver_name' : Parameter(int, 'the associated xid')})
146 @export_to_api(0)
147 def GetXIDs():
148     """Return an dictionary mapping Slice names to XIDs"""
149     return dict([(pwent[0], pwent[2]) for pwent in pwd.getpwall() if pwent[6] == slivermanager.sliver_password_shell])
150
151 @export_to_docbook(roles=['self'],
152                    accepts=[],
153                    returns={ 'sliver_name' : Parameter(str, 'the associated SSHKey')})
154 @export_to_api(0)
155 def GetSSHKeys():
156     """Return an dictionary mapping slice names to SSH keys"""
157     keydict = {}
158     for rec in database.db.itervalues():
159         if 'keys' in rec:
160             keydict[rec['name']] = rec['keys']
161     return keydict
162
163
164 @export_to_docbook(roles=['nm-controller', 'self'],
165                     accepts=[Parameter(str, 'A sliver/slice name.')],
166                    returns=Parameter(int, '1 if successful'))
167 @export_to_api(1)
168 def Create(sliver_name):
169     """Create a non-PLC-instantiated sliver"""
170     rec = sliver_name
171     if rec['instantiation'] == 'delegated':
172         account.get(rec['name']).ensure_created(rec)
173         logger.log("api_calls: Create %s"%rec['name'])
174     else:
175         raise Exception, "Only PLC can create non delegated slivers."
176
177
178 @export_to_docbook(roles=['nm-controller', 'self'],
179                     accepts=[Parameter(str, 'A sliver/slice name.')],
180                    returns=Parameter(int, '1 if successful'))
181 @export_to_api(1)
182 def Destroy(sliver_name):
183     """Destroy a non-PLC-instantiated sliver"""
184     rec = sliver_name
185     if rec['instantiation'] == 'delegated':
186         account.get(rec['name']).ensure_destroyed()
187         logger.log("api_calls: Destroy %s"%rec['name'])
188     else:
189         raise Exception, "Only PLC can destroy non delegated slivers."
190
191
192 @export_to_docbook(roles=['nm-controller', 'self'],
193                     accepts=[Parameter(str, 'A sliver/slice name.')],
194                    returns=Parameter(int, '1 if successful'))
195 @export_to_api(1)
196 def Start(sliver_name):
197     """Configure and start sliver."""
198     rec = sliver_name
199     account.get(rec['name']).start(rec)
200     logger.log("api_calls: Start %s"%rec['name'])
201
202
203 @export_to_docbook(roles=['nm-controller', 'self'],
204                     accepts=[Parameter(str, 'A sliver/slice name.')],
205                    returns=Parameter(int, '1 if successful'))
206 @export_to_api(1)
207 def Stop(sliver_name):
208     """Kill all processes belonging to the specified sliver"""
209     rec = sliver_name
210     account.get(rec['name']).stop()
211     logger.log("api_calls: Stop %s"%rec['name'])
212
213
214 @export_to_docbook(roles=['nm-controller', 'self'],
215                     accepts=[Parameter(str, 'A sliver/slice name.')],
216                    returns=Parameter(int, '1 if successful'))
217 @export_to_api(1)
218 def ReCreate(sliver_name):
219     """Stop, Destroy, Create, Start sliver in order to reinstall it."""
220     rec = sliver_name
221     account.get(rec['name']).stop()
222     account.get(rec['name']).ensure_created(rec)
223     account.get(rec['name']).start(rec)
224     logger.log("api_calls: ReCreate %s"%rec['name'])
225
226 @export_to_docbook(roles=['nm-controller', 'self'],
227                     accepts=[Parameter(str, 'A sliver/slice name.')],
228                    returns=Parameter(dict, "A resource specification"))
229 @export_to_api(1)
230 def GetEffectiveRSpec(sliver_name):
231     """Return the RSpec allocated to the specified sliver, including loans"""
232     rec = sliver_name
233     return rec.get('_rspec', {}).copy()
234
235
236 @export_to_docbook(roles=['nm-controller', 'self'],
237                     accepts=[Parameter(str, 'A sliver/slice name.')],
238                     returns={"resource name" : Parameter(int, "amount")})
239 @export_to_api(1)
240 def GetRSpec(sliver_name):
241     """Return the RSpec allocated to the specified sliver, excluding loans"""
242     rec = sliver_name
243     return rec.get('rspec', {}).copy()
244
245
246 @export_to_docbook(roles=['nm-controller', 'self'],
247                     accepts=[Parameter(str, 'A sliver/slice name.')],
248                     returns=[Mixed(Parameter(str, 'recipient slice name'),
249                              Parameter(str, 'resource name'),
250                              Parameter(int, 'resource amount'))])
251
252 @export_to_api(1)
253 def GetLoans(sliver_name):
254     """Return the list of loans made by the specified sliver"""
255     rec = sliver_name
256     return rec.get('_loans', [])[:]
257
258 def validate_loans(loans):
259     """Check that <obj> is a list of valid loan specifications."""
260     def validate_loan(loan):
261         return (type(loan)==list or type(loan)==tuple) and len(loan)==3 \
262             and type(loan[0])==str and type(loan[1])==str and loan[1] in database.LOANABLE_RESOURCES and type(loan[2])==int and loan[2]>=0
263     return type(loans)==list and False not in [validate_loan(load) for loan in loans]
264
265
266 @export_to_docbook(roles=['nm-controller', 'self'],
267                    accepts=[ Parameter(str, 'A sliver/slice name.'),
268                              [Mixed(Parameter(str, 'recipient slice name'),
269                                     Parameter(str, 'resource name'),
270                                     Parameter(int, 'resource amount'))], ],
271                    returns=Parameter(int, '1 if successful'))
272 @export_to_api(2)
273 def SetLoans(sliver_name, loans):
274     """Overwrite the list of loans made by the specified sliver.
275
276     Also, note that SetLoans will not throw an error if more capacity than the
277     RSpec is handed out, but it will silently discard those loans that would
278     put it over capacity.  This behavior may be replaced with error semantics
279     in the future.  As well, there is currently no asynchronous notification
280     of loss of resources."""
281     rec = sliver_name
282     if not validate_loans(loans):
283         raise xmlrpclib.Fault(102, 'Invalid argument: the second argument must be a well-formed loan specification')
284     rec['_loans'] = loans
285     database.db.sync()
286
287 @export_to_docbook(roles=['nm-controller', 'self'],
288                    returns=Parameter(dict, 'Record dictionary'))
289 @export_to_api(0)
290 def GetRecord(sliver_name):
291     """Return sliver record"""
292     rec = sliver_name
293     return rec