1. Aggregate Manager (AM) API¶
Please refer to the OMF Glossary for a definition of an OMF Aggregate Manager.
The OMF Aggregate Manager (AM) manages all the resources that are provided by a given testbed. More specifically, the AM consists of a collection of services that allow external parties to request management actions on a set of resources, or query their status.
We highly discourage experimenters from invoking the AM API directly. The Experiment Controller (EC) is a far more efficient and convenient way to provision, manage and control experiments. However, the use of the EC is not mandatory.
The AM provides REST like interface to all the services that it provides. The URLs are organized in a tree like fashion, where calling an "inner" node will return a structured description of all this node's child services. Please see Issue #189 for some important limitations.
As we are migrating all control and management related communication to XMPP, the AM services will also be accessible through XMPP. In fact, it will become the preferred way to invoke them.
It should also be noted that this API currently does not include any access control capabilities as they are enforced at a different level. We will soon introduce access control at this level in order to better support federation, but we expect this to be first introduced in the XMPP-based messaging plane.
2. Command and Syntax¶
2.1. Listing all available AM Service Groups¶
Note that access to the AM might be restricted to the local control network of a given testbed, depending on the policy of the testbed owner.
To view a list of all the service groups offered by a specific AM server:
- Point your browser to the AM URL: http://hostname_or_ip_or_the_AM:port_of_the_AM/
- for example: http://mytestbed.net:5022/
- Or from any machine having access to the testbed's control network, use the command:
wget -O - "http://address_of_AM:5022/"
As a result, you should see an XML file listing all available service groups. Similar to this:
1 <serviceGroups>
2
3 <serviceGroup name="result" path="/result">
4 <info>Service to access and query experiment measurement databases</info>
5 </serviceGroup>
6
7 <serviceGroup name="cmc" path="/cmc">
8 <info>Information on available testbed resources and simple control functionality</info>
9 </serviceGroup>
10
11 <serviceGroup name="inventory" path="/inventory">
12 <info>Service to retrieve information about nodes or testbeds from the Inventory Database</info>
13 </serviceGroup>
14
15 <serviceGroup name="frisbee" path="/frisbee">
16 <info>Service to control frisbee servers to stream specific images</info>
17 </serviceGroup>
18
19 <serviceGroup name="pxe" path="/pxe">
20 <info>Service to facilitate PXE to boot into specific image</info>
21 </serviceGroup>
22
23 </serviceGroups>
In this example, the AM provides 5 different groups of management services: result, cmc, inventory, frisbee, pxe.
2.2. Lsting all available AM Services within a single Group¶
To view the full list of individual services offered by one of these groups, you should append the path name to the previous URL.
For example, to view the list the services available for the cmc group of AM services, issue the following command:
wget -O - "http://address_of_AM:5022/cmc"
Which should return a XML file similar to:
1 <services>
2
3 <serviceGroup name="cmc" prefix="/cmc">
4 <info>Information on available testbed resources and simple control functionality</info>
5
6 <service name="allOffSoft">
7 <info>Switch off ALL nodes SOFT (execute halt)</info>
8 <args>
9 <arg isRequired="false" name="domain" value="[domain]">
10 <info>domain for request.</info>
11 </arg>
12 </args>
13 </service>
14
15 <service name="allStatus">
16 <info>Returns the status of all nodes in the testbed</info>
17 <args>
18 <arg isRequired="false" name="domain" value="[domain]">
19 <info>domain for request.</info>
20 </arg>
21 </args>
22 </service>
23
24 ...
25
26 </serviceGroup>
27
28 </services>
2.3. Invoking a particular AM service¶
Now to invoke a particular AM service, append the service name to the previous URL, and add the required parameters.
For example, to instruct the AM to power OFF all the node of a given testbed 'MyTestbedAlpha', execute:
wget -O - "http://address_of_AM:5022/cmc/allOffSoft?domain=MyTestbedAlpha"
Which should return an HTTP 200 OK reply if the request was excepted and an HTTP error code with additional descriptions, otherwise.