From 0bdd5dcacea3b065ae4d888956e37ce439fb1229 Mon Sep 17 00:00:00 2001 From: Stephen Soltesz Date: Mon, 4 May 2009 20:10:15 +0000 Subject: [PATCH] add monitor documentation generation stubs. --- docs/DocBookLocal.py | 20 ++++++ docs/Makefile | 62 ++++++++++++++++ docs/Monitor.xml.in | 167 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 249 insertions(+) create mode 100755 docs/DocBookLocal.py create mode 100644 docs/Makefile create mode 100644 docs/Monitor.xml.in diff --git a/docs/DocBookLocal.py b/docs/DocBookLocal.py new file mode 100755 index 0000000..62853a8 --- /dev/null +++ b/docs/DocBookLocal.py @@ -0,0 +1,20 @@ +#!/usr/bin/env python + +# PATHS to be set by the build system +# this is in .. +import api_calls +# in PLCAPI/doc +from DocBook import DocBook + +def api_methods(): + api_function_list = [] + for func in dir(api_calls): + try: + f = api_calls.__getattribute__(func) + if 'group' in f.__dict__.keys(): + api_function_list += [api_calls.__getattribute__(func)] + except: + pass + return api_function_list + +DocBook(api_methods ()).Process() diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f3e6b76 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,62 @@ +# +# (Re)builds API documentation +# +# Mark Huang +# Copyright (C) 2006 The Trustees of Princeton University +# +# $Id: Makefile 5574 2007-10-25 20:33:17Z thierry $ +# + +all: Monitor.html + +# XML - as opposed to SGML - requires an identifier - see +# http://www.docbook.org/tdg/en/html/appb.html +# and, openjade opens http connections when using the official URL +# as an identifier; this is slow, and sometimes fails and breaks the build + +# locating locally installed docbook43 dtd - fedora-specific +remote-docbook-43 = http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd +local-docbook-43 = $(wildcard /usr/share/sgml/docbook/xml-dtd-4.3-*/docbookx.dtd) +docbook-43=$(if $(local-docbook-43),$(local-docbook-43),$(remote-docbook-43)) + +Monitor.xml: Monitor.xml.in + $(if $(local-docbook-43), \ + echo Using locally installed DTD $(local-docbook-43), \ + echo WARNING - could not locate local DTD - using remote $(remote-docbook-43)) + sed -e s:@DOCBOOK-43@:$(docbook-43): $< > $@ + +.Monitor.xml.valid: Methods.xml + +MONITOR_SOURCES = ../web/MonitorWeb/monitorweb/monitor_xmlrpc.py + +# path needs to mention PLCAPI/doc (for DocBook) and PLCAPI/ (for PLC.Parameter) +Methods.xml: DocBookLocal.py $(MONITOR_SOURCES) + PYTHONPATH=..:../../PLCAPI:../../PLCAPI/doc ./DocBookLocal.py > $@ + +# +# Documentation +# + +# Validate the XML +.%.xml.valid: %.xml + xmllint --valid --output $@ $< + +# Remove the temporary output file after compilation +.SECONDARY: .%.xml.valid + +# Compile it into other formats +FORMATS := dvi html man ps pdf rtf tex texi txt + +DOCBOOK2FLAGS := -V biblio-number=1 + +define docbook2 +%.$(1): %.xml .%.xml.valid + docbook2$(1) --nochunks $$(DOCBOOK2FLAGS) $$< +endef + +$(foreach format,$(FORMATS),$(eval $(call docbook2,$(format)))) + +clean: + rm -f $(patsubst %,*.%,$(FORMATS)) .*.xml.valid Methods.xml + +.PHONY: clean all diff --git a/docs/Monitor.xml.in b/docs/Monitor.xml.in new file mode 100644 index 0000000..dd38353 --- /dev/null +++ b/docs/Monitor.xml.in @@ -0,0 +1,167 @@ + + +]> + + + + PlanetLab Node Manager API Documentation + + + + Introduction + + The PlanetLab Node Manager API (NMAPI) is the interface through + which the slices access the Node API. + +
+ Authentication + + Authentication for NM operations is based on the identity of the + connecting slice. For slices whose roles are defined as + 'nm-controller', the target slice must be listed delegated and as + controlled by the calling slice. + +
+
+ Delegation + None +
+
+ Connection + + The NM XMLRPC server listens locally on every PlanetLab node at http://localhost:812. + The NM XMLRPC server can be accessed remotely using an SSH connection through the nm-controller account. Rather than a standard shell, a special command is run that forwards all standard input to the local XMLRPC server, essentially XML-RPC over ssh. +
+
+ An Example using the PLC and NM API + + The nm-controller slice is given a stub account such that it can + be accessed over ssh. So rather than logging into NM server listens + locally on every PlanetLab node at http://localhost:812. + + + +controller_slice_fields = {'name' : 'princeton_mycontroller', + 'instantiation' : 'nm-controller', + 'url' : 'http://www.yourhost.com', + 'description' : 'a brief description of this slice.', } +controller_slice_id = api.AddSlices(plauth, controller_slice_fields) + + + After this, the controller owner, should both add users and nodes to + this slice. As well, the controller slice is created using the standard + PlanetLab and NM mechanism. So, wait at least 15 minutes before attempting + to access the controller slice on any node. + + Subsequently, slices that will be delegated to this controller will + be registered at PLC. An example follows. + + + +delegated_slice_fields = {'name' : 'anothersite_mydelegated', + 'instantiation' : 'delegated', + 'url' : 'http://www.yourhost.com', + 'description' : 'a brief description of this slice.', } +delegated_slice_id = api.AddSlices(plauth, delegated_slice_fields) + +# Get ticket for this slice. +ticket = api.GetSliceTicket(plauth, "princetondsl_solteszdelegated") + + + After the slice is registered with PLC, and your application has the + Ticket, the last step is to redeem the ticket by presenting it to the NM + through the nm-controller account. The following code formats the message + correctly. + + +# generate an XMLRPC request. +print xmlrpclib.dumps((ticket,), 'Ticket') + + + Finally, this message must be sent to the NM using the controller + account. It should be possible to create a program that creates the ssh + connection or to use a library that does this automatically such as: + pyXMLRPCssh + + + + Or, you could use something much simpler. Assuming the output from + dumps() above, is saved to a file called + ticket.txt, you could run a command like: + + + +cat ticket.txt | ssh princeton_mycontroller@mynode.someuniversity.edu + + + Alternately, + + +p = subprocess.Popen(['/usr/bin/ssh', 'princeton_mycontroller@mynode.someuniversity.edu'], + stdin=subprocess.PIPE, stdout=subprocess.PIPE) +print >>p.stdin, xmlrpclib.dumps((ticket,), 'Ticket') +p.stdin.close() +print xmlrpclib.loads(p.stdout.read()) +p.wait() + + + The following is a stub to use as you would use the current + xmlrpclib.Server() object, but redirects the connection of SSH. + + +"""XML-RPC over SSH. + + To use, create an XmlRpcOverSsh object like so: + >>> api = XmlRpcOverSsh('princeton_deisenst@planetlab-1.cs.princeton.edu') + and call methods as with the normal xmlrpclib.ServerProxy interface. +""" + +from subprocess import PIPE, Popen +from xmlrpclib import Fault, dumps, loads + +__all__ = ['XmlRpcOverSsh'] + + +class XmlRpcOverSsh: + def __init__(self, userAtHost): + self.userAtHost = userAtHost + + def __getattr__(self, method): + return _Method(self.userAtHost, method) + + +class _Method: + def __init__(self, userAtHost, method): + self.userAtHost = userAtHost + self.method = method + + def __call__(self, *args): + p = Popen(['ssh', self.userAtHost], stdin=PIPE, stdout=PIPE) + stdout, stderr = p.communicate(dumps(args, self.method)) + if stderr: + raise Fault(1, stderr) + else: + return loads(stdout) + + +
+ + + + + PlanetLab API Methods + + + &Methods; + + + + + + + -- 2.43.0