Resource Descriptor

The Resource Descriptor

The Resource Descriptor is an XML file that is used to inform OpenNaaS about all metadata related to a resource. It is required to add any new resource to OpenNaaS's resource repository. It describes the: Resource name Resource type Supported capabilities Required drivers

If a capability is supported by a device but not described in the resource descriptor, it will not be availble for use when the resource is loaded.

OpenNaaS must support a capability belonging to a resource in code. If OpenNaaS does not have a bundle that supports the capability for that type of resource, the capability can not be used.

A simple resource descriptor

This piece of XML shows the smallest valid resource descriptor possible.

<resourceDescriptor>
	<information>
		<type>router</type>
		<name>apollo</name>
	</information>
</resourceDescriptor> 

This file can be used to create a resource without any capabilities.

Adding a resource to OpenNaaS

Resources can be added to OpenNaaS's resource repository through the command line interface. After constructing a resource descriptor, use the following command to register the resource with OpenNaaS:

resource:create /path/to/descriptor/resource.descriptor 

Once added to the resource repository, resources are addressed through a combination of their type and name. This is of the form "resourceType:resourceName". In the case of the example above, that would become "router:apollo".

After a resource has been added, its state will initially be "initialized". In order to use it, it will have to be started. To do this, use the command:

resource:start router:apollo

Complete overview

The file below shows a complete overview of all possible tags and attribute that the resource descriptor file can contain. Legend of the annotations for the tags:

• (required): If the parent tag is added to the XML file, this tag must be present 
• (min-max): This tag must be used at least min times and at most max times.
• Text node: refers to the text <tag> inside a tag </tag>

<resourceDescriptor> (required) (1-1) 
	<id /> (0-1) 
	<capabilityDescriptors> (0-n) 
		<capabilityProperty name="name" value="value" /> (0-n) 
		<information> (required) (1-1) 
			<type /> (required) (1-1) 
			<description /> (0-1) 
		</information> 
	</capabilityDescriptors> 
	<information> (required) (1-1) 
		<type /> (required) (1-1) 
		<name /> (required) (1-1) 
		<description /> (0-1) 
	</information> 
	<properties /> (0-1) 
	<fileTopology /> (0-1) 
	<description /> (0-1) 
</resourceDescriptor> 

Identification

<resourceDescriptor>
	<id>resource_id</id>
	 ...
</resourceDescriptor>  

Text node: The unique ID assigned to this resource by OpenNaaS. This tag is only used in automatically generated files when exporting a resource from the command line.

capabilityDescriptor

<resourceDescriptor>
	...
	<capabilityDescriptors>
		<capabilityProperty name="name" value="value" />
		<information>
			<type>valid_type </type>
			<description>description_of_cap</description>
		</information>
	</capabilityDescriptors>
	...
</resourceDescriptor> 

A resource consists of information for identification, a network topology and a set of capabilities. The capability of a particular resource defines the features the resource supports at an operational level. A resource that requires at least one capability requires a capability descriptor. Every capability requires the selection of an actionset.

<capabilityDescriptors> 
	<capabilityProperty name="actionset.name" value="junos" /> 
	<capabilityProperty name="actionset.version" value="10.10" /> 
	<information> 
		<type>"ospfv3"</type> 
		<description>"Juniper Router running JunOS 10.10 with the capability OSPFv3"</description> 
	</information> 
</capabilityDescriptors> 

In order to select an ActionSet that can be used on the resource being defined in the resource descriptor, an actionset.capability, actionset.name and actionset.version is required. The actionset.name specifies the name of the ActionSet that is to be used. Every ActionSet has a number of capabilities each with a number of versions.

The actionset.capability is stored inside the type tag of the information section. The other two values, actionset.name and actionset.version are specified in capabilityProperty tags. If the actionSet requires a special protocol, the actionset.protocol can also be specified in a capabilityProperty tag.

Supported capabilities

Below is a list of supported combination of capabilities that can be used to specify capability descriptions.

Note that the queue capability is supported by almost all capabilities. The queue capability allows queueing of commands that can be applied as a batch or rolled back if need be.

Possible values of the actionset.protocol field:

Information (resourcedescriptor)

<resourceDescriptor>
	.... 
	<information> 
		<type>type_resource</type> 
		<name>name_of_resource</name> 
		<description>description_of_resource</description> 
	</information>
	... 
</resourceDescriptor>  

type

Text node: Specifies the type that OpenNaaS should consider the described resource to be. The resource type that OpenNaaS supports by default are:

name

A name that can be used to address the resource after its registration

desciption

Text node: An optional description of the resource. Its value will be shown when requesting more information about a particular registered resource on the OpenNaaS command line interface.

properties

<resourceDescriptor>
	...
	<properties>properties</properties> 
	... 
</resourceDescriptor>

Text node: properties

fileTopology

<resourceDescriptor>
	... 
	<fileTopology>path_to_network_topology</fileTopology> 
	... 
</resourceDescriptor>

Text node: the path to a network topology stored in an XML file. The path specified must be absolute.

description

<resourceDescriptor>
	... 
	<description>desc_of_resdesc</description>
	... 
</resourceDescriptor>

Text node: an optional description