ABSTRACT[1]

This paper describes the Application Programming Interface (X-Bone API) version 2.0 of the current X-Bone Version 3.2 release. It covers both syntax and semantics of the API. X-Bone is a Virtual Internet system that dynamically deploys and manages Internet overlays. The X-Bone API, written in XML (Extensible Markup Language), is the method by which the X-Bone system receives commands and returns responses from/to users to determine these overlays and their properties.

Keywords

Virtual network, Virtual Internet, overlay network, application programming interface (API), extensible markup language (XML).

1. Introduction

An X-Bone Virtual Internet system [5][6] is a collection of Resource Daemons (RD) managed by one or more Overlay Managers (OM). The X-Bone API enables users to communicate with an OM, over an assigned TCP port 265, to configure the RDs (over another assigned TCP port 2165) in the X-Bone VI system on the user’s behalf. A “user” here can be a human at a web-based GUI or a text console, or an external program that acts as one, exchanging API messages with the OM. The API messages carry user commands and OM replies for overlay creation, destruction, monitoring, and resource discovery.

An overlay network in the X-Bone VI system consists of a connected graph of virtual nodes interconnected by a number of point-to-point virtual links. A virtual node here is an abstraction; it may denote a simple node of a single RD, or a meta node of a lower-layer, recursed overlay network. A virtual link connects pairs of virtual nodes with unique endpoint addresses within the overlay network. Each virtual link incorporates two layers of tunneling to emulate both link and network layers for complete virtualization.

The role of the X-Bone API in the management of an X-Bone VI system can be illustrated in Figure 1. The user initiates the command-execute-reply process by issuing commands as API messages to the OM over an SSL-protected stream on TCP port 265 in a particular, desired X-Bone VI system [3]. The OM translates the API message into configuration instructions and dispatches them to reachable RDs via a separate protocol: xb-ctl. The RDs evaluate these instructions, deciding whether to accept and perform them, decline them, or ignore them, and send appropriate responses back to the OM. The OM collects responses and packs them into a reply message also defined by the X-Bone API. The message is then sent back to the user.

Figure 1 Structure of an X-Bone Virtual Internet.

This report focuses on the design and structure of the X-Bone API. Section 2 lists keywords and conventions used throughout this document; Section 3 describes the syntax and Section 4 explains the semantics of all the elements in the API except the X-Bone Overlay Language (XOL), whose syntax and semantics are explained separately in Section 5. Section 6 descibes network recursion support, with security issues in Section 7 and future work in Section 8. This document supersedes and obsoletes ISI-TR-2001-549 [2].

2. Reserved Tokens and Conventions

This section describes the fundamental properties of the X-Bone API XML-based syntax. Before proceeding to the complete language description in Section 3, this section lists the reserved tokens and conventions of other user tokens in the language.

2.1 Reserved Tokens

The element and attribute names are the reserved tokens used by the API. Use of these tokens, except as indicated by the language, must be avoided.

`argstring`	`node_def`
`create_overlay*`	`overlay`
`credential`	`overlay_status`
`destroyall_overlays*`	`property`
`destroy_overlay*`	`renames`
`discover_daemons*`	`synonym`
`endpoint`	`tag`
`define_prop`	`tunnel`
`ident`	`value`
`iface`	`version`
`link`	`vnode`
`list_overlays*`	`xol_program`
`node`

Table 1 Reserved Tokens

In Table 1, tokens with a star (*) have a corresponding token with “_reply” appended, e.g., “create_overlay_reply”. These entries are omitted for clarity and brevity.

Further, some of reserved tokens are part of the conventional XML DTDs, and are not specific to the X-Bone, but are listed there as well; shown in bold.

2.2 String Conventions

User-supplied strings in the API follow the CDATA syntax restriction of XML. Strings are delimited by double quotes, “…”. Some special characters (&, <, >, ', ") inside a CDATA string must be quoted in their escaped form, as shown in Table 2.

Where the semantic nature of a string is more restrictive, as in E-mail or DNS names, those particular restrictions are applied as well. All strings and tokens are verified for such restrictions.

Character	Escaped Quotation
`&`	`&`
`<`	`<`
`>`	`>`
`'`	`'`
`"`	`"`

Table 2 Escape characters

2.3 Presentation Conventions

2.3.1 Property Elements

For convenience and simplicity, in this document the property elements are referred to by their tag attributes. For example, the property element with tag attribute “user_name” is referred to as the “user_name property.”

2.3.2 Message Naming

Every message in the API is either a command message (sent from user to OM) or a reply message (sent from OM to user). The core of a message is one of the 13 command-reply elements (Sec. 3.3). Every API message must contain exactly one command-reply element. The purpose of a message is specified by the command-reply element it contains.

For this reason and for simplicity, in this document an API message is named by the type of command-reply element it possesses. For example, an API message containing the list_overlays_reply element is called a “list_overlays_reply message.” Also, an API message containing a command-carrying element is called a “command message,” while a message containing a reply-carrying element is called a “reply message.”

2.3.3 Element Naming

Many elements have an ident attribute that uniquely identifies them without their containing parents. Specifically, the following XOL elements have this kind of ident attribute:

· Node_def

· Iface

· Vnode

· Link

For simplicity, these elements are named by their respective ident attribute values. For example, the vnode element with “router_0” as its ident attribute value is called the “router_0” vnode element.

3. X-Bone API Syntax

The X-Bone API syntax consists of grammar rules governing message exchanges across a well-known, privileged TCP port (265) used by X-Bone OMs, where the stream is protected by SSL [3]. All messages in the API adapt a unified XML structure, starting with the sequence of XML Declaration, a Document Type Declaration (DTD), and one xbone element, in that order. The current X-Bone (release 3.2) implements X-Bone API version 2.0 (api-2.0.dtd) [1].

The XML elements in X-Bone API can be divided conceptually into four element categories: common-purpose elements, command-reply elements, overlay-description elements, and XOL elements. This section steps through the syntax of the first 3 element categories. Syntax of the XOL elements is described in Section 5.1.

3.1 Document Type Definition

Below is the DTD of X-Bone API version 2.0 [1].

<?xml version="2.0" ?>

<!ELEMENT xbone (credential?, command)>

<!ATTLIST xbone

    version CDATA #REQUIRED

    release CDATA #REQUIRED>

<!ELEMENT credential (property+)>

<!ELEMENT command

         (create_overlay_reply |

          create_overlay |

          list_overlays_reply |

          list_overlays |

          overlay_status_reply |

          overlay_status |

          discover_daemons_reply |

          discover_daemons |

          destroy_overlay_reply |

          destroy_overlay |

          destroyall_overlays_reply |

          destroyall_overlays |

          error_reply)>

<!ELEMENT create_overlay

         (property+, xol_program)>

<!ELEMENT create_overlay_reply

         (property+, node*)>

<!ELEMENT list_overlays EMPTY>

<!ELEMENT list_overlays_reply

         (property?, argstring*)>

<!ELEMENT overlay_status (property+)>

<!ELEMENT overlay_status_reply

         (property+, node*)>

<!ELEMENT discover_daemons_reply

         (property+, node*)>

<!ELEMENT discover_daemons (property+)>

<!ELEMENT destroy_overlay (property+)>

<!ELEMENT destroy_overlay_reply

         (property+)>

<!ELEMENT destroyall_overlays EMPTY>

<!ELEMENT destroyall_overlays_reply

         (property+)>

<!ELEMENT error_reply (property+)>

<!ELEMENT argstring EMPTY>

<!ATTLIST argstring

    value CDATA #REQUIRED>

<!ELEMENT node (property+, tunnel*)>

<!ELEMENT tunnel (property+)>

<!ELEMENT xol_program

         (define_prop*,node_def+,vnode)>

<!ATTLIST xol_program

    version CDATA #REQUIRED>

<!ELEMENT define_prop (property)>

<!ATTLIST define_prop

    synonym CDATA #REQUIRED>

<!ELEMENT node_def

         (iface+, vnode*, link*,

          property*, application*)>

<!ATTLIST node_def

    ident CDATA #REQUIRED>

<!ELEMENT iface (renames|property*)>

<!ATTLIST iface

    ident CDATA #REQUIRED>

<!ELEMENT renames (endpoint, property*)>

<!ELEMENT vnode (property*)>

<!ATTLIST vnode

    ident CDATA #REQUIRED

    type  CDATA #REQUIRED>

<!ELEMENT link

         (endpoint, endpoint,

          property*)>

<!ATTLIST link

    ident CDATA #REQUIRED>

<!ELEMENT property EMPTY>

<!ATTLIST property

    tag CDATA #REQUIRED

    value CDATA #IMPLIED>

<!ELEMENT endpoint EMPTY>

<!ATTLIST endpoint

    node CDATA #REQUIRED

    iface CDATA #REQUIRED>

<!ELEMENT application EMPTY>

<!ATTLIST application

    program  CDATA #REQUIRED

    script   CDATA #REQUIRED

    checksum CDATA #IMPLIED

    suid     CDATA #IMPLIED

    nodes    CDATA #IMPLIED

    ifaces   CDATA #IMPLIED>

3.2 Common-Purpose Elements

The common-purpose elements (Table 3) are used to form the basic structure of any message in the API.

Element name	Attributes	Sub-elements
`xbone`	version, release	credential?, command
credential	(none)	property+
command	(none)	(One of the elements in Table 4.)
property	tag, value	EMPTY

Table 3 Common-purpose elements

The root of the API is the xbone element, which is described by the version and release attributes. The xbone element contains an optional credential element and a single command element. The credential element contains at least one property. The command element contains one of the 13 command-reply elements (see the sub-section below).

The property element is used pervasively in almost all other elements in the API to associate a tag with a value, with both tag and value as its attributes. The tag and value attribute pair can be either a command parameter or a return value; it usually describes a semantic aspect of the property’s parent element.

3.3 Command-Reply Elements

There are 13 different command-reply elements, each of which may be the sole child of the enclosing command element (see the sub-section above). There are six command-carrying elements and six corresponding reply-carrying elements plus one error_reply element, shown in Table 4.

Except for the