Parallels Virtual Automation - 6.1 User Guide
PVA Agent
XML API Reference
Copyright © 1999-2014 Parallels IP Holdings GmbH and its affiliates. All rights reserved.
Parallels IP Holdings GmbH.
c/o Parallels International Gm
Parallels International GmbH
Vordergasse 49
CH8200 Schaffhausen
Switzerland
Tel: + 41 526
Fax: + 41 52672 2010
www.parallels.com
opyright © 1999-2013 Parallels IP Holdings GmbH and its affiliates. All rights reserved.
C
his product is protected by United States and international copyright laws. The product’s underlying technology,
T
patents, and trademarks are listed at http://www.parallels.com/trademarks.
icrosoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are registered trademarks of Microsoft
M
Corporation.
Apple, Mac, th
Inc., registered in the US and other countries.
Linux is a registered trademark of Linus Torvald
All other marks and names mentioned herein may
320 411
e Mac logo, Mac OS, iPad, iPhone, iPod touch, FaceTime HD camera and iSight are trademarks of Apple
bH.
s.
be trademarks of their respective owners.
Contents
Preface....................................................................................................................... 6
About This Guide .............................................................................................................. 6
Who Should Read This Guide ...........................................................................................6
Organization of This Guide ................................................................................................ 7
How to Use This Guide ..................................................................................................... 8
Documentation Conventions ............................................................................................. 8
Typographical Conventions ..................................................................................................... 9
Shell Prompts in Command Examples................................................................................... 10
General Conventions .............................................................................................................10
Feedback........................................................................................................................11
Reference Format....................................................................................................12
XML Message Specifications........................................................................................... 13
XML Code Samples ........................................................................................................ 16
Agent Messages......................................................................................................18
Message Header............................................................................................................. 19
Message Body................................................................................................................ 24
Base Types and Interfaces .....................................................................................26
Common Types ..............................................................................................................26
Primitive Types ...................................................................................................................... 27
Simple Types......................................................................................................................... 27
Complex Types ..................................................................................................................... 30
Interfaces ........................................................................................................................ 72
alertm .................................................................................................................................... 72
authm.................................................................................................................................... 81
backup_storagem ............................................................................................................... 120
backupm............................................................................................................................. 120
server_group ....................................................................................................................... 161
computerm.......................................................................................................................... 177
data_storagem .................................................................................................................... 195
devm ................................................................................................................................... 198
Contents
sample_manager................................................................................................................. 232
envm ................................................................................................................................... 237
event_log............................................................................................................................. 275
filer ...................................................................................................................................... 280
firewallm .............................................................................................................................. 306
licensem.............................................................................................................................. 315
mailer .................................................................................................................................. 331
relocator .............................................................................................................................. 340
networkm ............................................................................................................................ 364
op_log ................................................................................................................................. 384
perf_mon............................................................................................................................. 389
packagem ........................................................................................................................... 399
proc_info ............................................................................................................................. 436
processm ............................................................................................................................ 445
res_log ................................................................................................................................ 452
ip_poolm ............................................................................................................................. 465
scheduler ............................................................................................................................ 478
servicem.............................................................................................................................. 495
sessionm............................................................................................................................. 506
userm.................................................................................................................................. 524
Events........................................................................................................................... 551
Types .................................................................................................................................. 551
Elements ............................................................................................................................. 553
System Interface and Special Packets........................................................................... 562
system................................................................................................................................. 562
The progress packet ........................................................................................................... 616
Container (CT) Types and Interfaces ....................................................................620
Common Types ............................................................................................................620
Simple Types....................................................................................................................... 620
Complex Types ................................................................................................................... 621
Interfaces ...................................................................................................................... 632
vzadevm.............................................................................................................................. 632
vzaenvm.............................................................................................................................. 633
vzarelocator......................................................................................................................... 658
vzanetworkm....................................................................................................................... 661
Contents
vzapackagem ...................................................................................................................... 668
vzaproc_info........................................................................................................................ 669
vzaprocessm....................................................................................................................... 676
vzaup2date ......................................................................................................................... 678
vzasupport .......................................................................................................................... 685
Virtual Machine (VM) Types and Interfaces ..........................................................694
Common Types ............................................................................................................694
Complex Types ................................................................................................................... 694
Interfaces ...................................................................................................................... 716
vzpenvm.............................................................................................................................. 716
vzpdevm.............................................................................................................................. 724
vzpnetworkm....................................................................................................................... 726
vzprelocator......................................................................................................................... 727
vzpsample_manager ........................................................................................................... 728
Appendix A: Performance Counters .....................................................................732
Appendix B: States and Transitions .....................................................................742
Appendix C: Error Codes ......................................................................................744
Index ......................................................................................................................759
C HAPTER 1
Preface
In This Chapter
About This Guide ..................................................................................................... 6
Who Should Read This Guide................................................................................... 6
Organization of This Guide ....................................................................................... 7
How to Use This Guide............................................................................................. 8
Documentation Conventions .................................................................................... 8
Feedback ................................................................................................................. 11
About This Guide
This guide is a complete Parallels Agent XML API reference. The XML API consists of interfaces to
the Parallels Virtuozzo Containers, Parallels Cloud Server, Parallels Server Bare Metal, and Parallels
Server for Mac management functions. An interface provides calls (similar to functions or methods
in traditional programming languages) that allow to interact with the Virtuozzo Containers software,
Parallels Cloud Server, Parallels Server Bare Metal, and Parallels Server for Mac on the server side.
Using the XML API, you can build reliable tools for remote management and monitoring of the
physical servers and virtual environments.
Who Should Read This Guide
This guide is intended for the developers who are writing their own Parallels Agent applications
using XML API. This guide should also be used by the developers using Parallels Agent SOAP API.
The proxy classes that you will generate using Parallels Agent WSDL specifications will have the
same basic structure as the interfaces and calls described in this guide. By examining an XML API
documentation, you can get a clear understanding of how to use a corresponding method of a
proxy class in your SOAP-based application.
Preface
Organization of This Guide
This guide is organized into the following chapters:
Chapter 1, Preface. Provides information about this guide.
Chapter 2, Reference Format. Explains how to use the specifications presented in this guide.
Chapter 3, Agent Messages. Provides a description of the Parallels Agent XML message
structure.
Chapter 4, Base Types and Interfaces. Describes the base data types and interfaces. The
chapter is divided into sections. The Common Types section (p. 26) describes the base data types
that are used throughout the API. The Interfaces section (p. 72) describes the base interfaces and
the available API calls. Each API call documentation consists of the XML request and response
specifications, the description of the parameters, and one or more XML code samples.
Chapter 5, Virtuozzo Containers Types and Interfaces. This chapter is organized similarly to the
Base Types and Interfaces chapter but describes the types and interfaces that are specific to the
Virtuozzo Containers management only. Some of these interfaces and types are derived from the
base interfaces and types. If a call is not overridden in the derived interface, it will be documented in
the base interface only. However, the Virtuozzo Containers specifics will still be documented and
the appropriate examples will be provided.
Chapter 5, Parallels Server Types and Interfaces. This chapter describes the types and
interfaces that are specific to the Parallels Server virtual machiens management only. Some of
these interfaces and types are derived from the base interfaces and types.
Appendix A: Performance Counters. Provides a complete list of the available performance
classes and counters which are used for performance monitoring.
Appendix B: States and Transitions. Provides a complete list of the available server states and
transitions.
Appendix C: Error Codes. Provides a complete list of the Parallels Agent error codes, grouped by
the interface or the category to which they apply.
7
Preface
How to Use This Guide
You don't have to read the entire XML reference guide from cover to cover, but you should read at
least the Preface chapter (you are reading it now), the Reference Format chapter, and the Agent
Messages chapter. The information provided in these chapters is essential to understanding the
rest of the reference material. To get a better understanding of Parallels Agent and to learn how to
write your own client programs using the provided API, you should also read the Parallels Agent
Programmer's Guide which is a companion book to this one.
Each XML API interface provides calls to perform operations of a particular type. For example, the
vzaenvm interface (p. 633) allows you to manage Virtuozzo Containers, the perf_mon interface
(p. 389) allows you to monitor the performance of a Virtuozzo Container or the Hardware Node,
etc. In this respect, the interfaces in the Agent XML API are similar to classes in traditional OOP
languages, and the calls are similar to methods. The names of the interfaces are abbreviations
based on the name of the functionality that they provide. For example, vzaenvm and vzpenvm
stands for Virtuozzo Containers and Parallels virtual machine management, respectively;
perf_mon stands for Performance Monitoring, etc. To find the specifications for a particular
operation, browse the Interfaces sections of the Base Types and Interfaces chapter or the
Virtuozzo Containers Types and Interfaces and Parallels Server Types and Interfaces chapter.
Find the interface that interests you and read the introductory section which gives a brief
description about the functionality that the interface provides. After that, proceed to the Calls
subsection which lists the available calls that the interface provides. Select the call that interests
you and proceed to the subsection describing it. In the subsection, you will find the request
specifications, the response specifications, the description of the call, and an XML code sample.
This should provide you with enough information to use the call in your client application to perform
the desired operation. You may also search the guide using keywords.
Documentation Conventions
Before you start using this guide, it is important to understand the documentation conventions used
in it.
Formatting conventions used in this guide:
Font Meaning Example
Special Bold
8
Selectable entities such as menu
options, buttons, or list items.
Titles of chapters, sections and
subsections.
Go to the Resources tab.
Read the Basic Administration chapter.
Preface
Italics
Monospace
Preformatted
Preformatted Bold
Key+Key Key combinations. Ctrl+P, Alt+F4
Important points, terms, guide
titles, command variables.
Names of commands, files, and
directories.
On-screen console output in
command line sessions, source
code.
What you type as contrasted with
on-screen console output.
These are the so-called EZ templates.
To destroy a Container, type vzctl
destroy CT_ID.
Use vzctl start to start a Container.
Saves parameters for Container
101
# rpm -V virtuozzo-release
Besides the formatting conventions, you should also know about the common document structure
shared by all guides for Parallels products: chapters consist of sections, which, in turn, consist of
subsections. For example, About This Guide is a section, and Documentation Conventions is a
subsection.
Typographical Conventions
The following kinds of formatting in the text identify special information.
Formatting
convention
Type of Information Example
Triangular Bullet(¾) Step-by-step procedures. You can follow
the instructions below to complete a
specific task.
Special Bold
Items you must select, such as menu
options, command buttons, or items in a
list.
Titles of chapters, sections, and
subsections.
To create a Container:
Go to the Resources tab.
Read the Basic Administration chapter.
9
Preface
Italics
Monospace
Preformatted
Monospace Bold
CAPITALS Names of keys on the keyboard. SHIFT, CTRL, ALT
KEY+KEY Key combinations for which the user must
Used to emphasize the importance of a
point, to introduce a term or to designate
a command line placeholder, which is to
be replaced with a real name or value.
The names of commands, files, and
directories.
On-screen computer output in your
command-line sessions; source code in
XML, C++, or other programming
languages.
What you type, contrasted with on-screen
computer output.
press and hold down one key and then
press another.
These are the so-called EZ templates.
To destroy a Conainer, type vzctl destroy
ctid.
Use vzctl start to start a Container.
Saved parameters for Container 101
# rpm –V virtuozzo-release
CTRL+P, ALT+F4
Shell Prompts in Command Examples
Command line examples throughout this guide presume that you are using the Bourne-again shell
(bash). Whenever a command can be run as a regular user, we will display it with a dollar sign
prompt. When a command is meant to be run as root, we will display it with a hash mark prompt:
Bourne-again shell prompt
Bourne-again shell root prompt
$
#
General Conventions
Be aware of the following conventions used in this book.
• Chapters in this guide are divided into sections, which, in turn, are subdivided into subsections.
For example, Documentation Conventions is a section, and General Conventions is a
subsection.
• When following steps or using examples, be sure to type double-quotes ("), left single-quotes
(`), and right single-quotes (') exactly as shown.
• The key referred to as RETURN is labeled ENTER on some keyboards.
The root path usually includes the /bin, /sbin, /usr/bin and /usr/sbin directories, so the
steps in this book show the commands in these directories without absolute path names. Steps
that use commands in other, less common, directories show the absolute paths in the examples.
10
Preface
Feedback
If you want to report typos, share comments, suggestions or ideas on improving this guide, please
use the Parallels documentation feedback page (http://www.parallels.com/en/support/usersdoc/).
11
C HAPTER 2
Reference Format
This chapter explains how to use the specifications presented in this guide.
In This Chapter
XML Message Specifications .................................................................................... 13
XML Code Samples ................................................................................................. 16
Reference Format
XML Message Specifications
The XML message specifications in this guide are described using tables, similar to the following
example:
Name Min/Max Type Description
login
{
name 0..1 base64Binary
domain 0..1 base64Binary
realm 1..1 guid_type
password 0..1 base64Binary
expiration 0..1 int
}
The information in a table is based on a corresponding XML Schema and describes the format of a
request or response message, or the format of a data type.
User name.
Domain.
Realm ID.
User password.
Custom timeout value.
Each row in a table represents an XML element. The elements are displayed in the order they are
defined in the XML Schema.
The definitions for the table columns are as follows:
Name. Specifies an XML element name. The curly brackets represent the standard XML Schema
xs:sequence element. This means that the elements inside the brackets are the child elements of
the element that precedes the opening bracket. In our example, the name, domain, realm,
password, and expiration elements are children of the login element. The following is a
sample XML code, built according to this specification:
<login>
<name>bXluYW1l</name>
<domain>bXlkb21haW4=</domain>
<realm>bXlyZWFsbQ==</realm>
<password>bXlwYXNz</password>
<expiration>1000</expiration>
</login>
In addition, we use square brackets to represent the standard XML Schema xs:choice element,
as shown in the following example:
Name Min/Max Type Description
status
[
up 1..1 none
Device status,
Denotes a choice between the <up> and the
<down> elements.
Enabled.
13
Reference Format
down 1..1 none
]
This means that the elements inside the brackets are the child elements of the element that precedes the opening
bracket but the elements are mutually exclusive -- only one of them can be present in the request.
Disabled.
Min/Max. Specifies the cardinality of an element (the number of its minimum and maximum
occurrences) in the following format:
minOccurs..maxOccurs
• 0 in the first position indicates that the element is optional.
• 1 in the first position indicates that the element is mandatory and must occur at least once.
• A number in the second position indicates the maximum number of occurrences.
• The [] (square brackets) in the second position indicate that the number of the element
occurrences is unbounded, meaning that the element may occur as many times as necessary
in the same XML document at the specified position.
The following examples demonstrate how an element cardinality may be specified:
• 0..1 The element is optional and may occur only once if included in the document.
• 1..1 The element is mandatory. One, and only one, occurrence is expected in the
document.
• 0..[] The element is optional but may occur an unlimited number of times if needed.
• 1..[] The element is mandatory. At least one occurrence is expected but the element may
occur an unlimited number of times if needed.
Type. Specifies the element type. The following element types are used in the schema:
• Standard simple types: int, string, base64Binary, etc.
• Custom simple types. These types are usually derived from standard simple types with
additional restrictions imposed on them.
• Custom complex types.
Description. The description column contains the element description and provides information
about its usage.
Let's now use the schema example from the beginning of this section and build the Agent request
message from it. We already built the message body from it earlier. To make it a fully qualified
Agent request message, we must also add the interface name to it and the message header. The
following example is a complete Agent message that can be sent to the Agent and be processed
by it:
<?xml version="1.0" encoding="utf-8"?>
<packet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/types" version="4.0.0" id="2">
<data>
<system>
14
<login xsi:type="ns2:auth_nameType">
<name>QWRtaW5pc3RyYXRvcg==</name>
<realm>00000000-0000-0000-0000-000000000000</realm>
<password>MXEydzNl</password>
</login>
</system>
</data>
</packet>
Reference Format
15
Reference Format
XML Code Samples
Most of the XML API call descriptions have one or more XML code samples. The samples are
provided at the end of the section describing a call. You may copy an entire example and paste it
into your program to quick-test the call. More than one samples may be provided for calls where
different invocation scenarios must be considered. Please note that some values used in the
samples may not be suitable for your particular situation and must be substituted with the values
appropriate to your setup. The following is a typical XML code sample:
Example:
Retrieving Parallels Agent version number.
Input
<packet version="4.0.0" id="2">
<data>
<system>
<get_version/>
</system>
</data>
</packet>
Output
<packet id="2c446af2aet18be" time="2006-05-17T09:54:00+0000" priority="0"
version="4.0.0">
<session>vzl.30100.ba7be334-4804-4494-a9c8-15149a0438a5.8c446ae612t2cd6</session>
<target>vzclient4</target>
<dst>
<director>gend</director>
</dst>
<data>
<system>
<version>pvaagent-4.0.0</version>
</system>
</data>
<src>
<director>gend</director>
</src>
</packet>
The Input section contains a complete XML response message built according to the schema
definition.
The Output section contains the actual response message received from Agent.
Note: Some of the elements and attributes common to all response messages will be omitted from the
Output examples for brevity. These attributes and elements may include time, priority from the
<packet> element, and <session>, <target>, <dst>, <src> from the message header, and
possibly some other elements and attributes that are not essential to a particular example. The <data>
element containing the output data will be included in its entirety, unless noted otherwise in the example
itself.
16
Reference Format
17
C HAPTER 3
Agent Messages
In order to build XML messages correctly and to take full advantage of the available options, it is
important to understand the basic building blocks of a message. This section describes how an
Agent message is organized, and provides the necessary specifications and examples.
In This Chapter
Message Header ...................................................................................................... 19
Message Body ......................................................................................................... 24
Agent Messages
Message Header
The two main sections of any Agent XML message is the header and the body. The header
provides message routing and control information. The body of the message contains the actual
request (or response) parameters and data. The packet element is the root element of every
message. Both the header and the body of a message reside within the same parent packet
element.
The following table contains the Agent message header specification, as defined in XML Schema.
Message header specification:
Name Min..Max Type Description
packet
{
cookie 0..1 string
target 0..[] string
The root element of an Agent XML message.
User-defined information describing the
message, or any other type of information.
The data specified here remains unchanged
during the request/response operation, i.e. if
you put some data into this element in the
request message, the response message
will contain the same data.
In request messages, this element must
contain the name of the operator to which
the request should be sent for processing.
origin 0..1 string
Note: When using the system
operator, do not include the
target element. The system
operator is the only exception. All
other operators require this element.
The name of the operator is always the
same as the name of the corresponding
interface that you are using. For example, if
you are using a call from the vzaenvm
interface, the name of the target operator is
also vzaenvm.
Multiple targets may be specified if you are
including multiple calls in a single request.
In response messages, this element
contains the name of the client that
originated the request (the value is
generated and used internally by Agent).
The name of the operator that generated the
response. Included in response messages
only.
19
Agent Messages
src 0..1 routeType
{
director 0..1 string
host 0..1 string
index 0..1 string
target 0..1 string
}
dst
routeType
The source routing information. This field is
automatically populated by the director on
the server side when a message is routed
from the corresponding operator to it. The
same information is also duplicated in the
dst element (described below) when a
response is generated and is sent back to
the client.
The name of the director to which the target
operator belongs.
The Agent host ID. Used by Agent to
determine the host address. Should be
either contained in the Agent configuration
(global mapping) or be a result of exclusive
connect.
For on-demand operators, specifies a
particular target.
Contains the origin information when a
packet is sent remotely.
The destination routing information.
In request messages, use this structure to
specify the server to which you want to
forward the request. For example, if you are
sending a request to the Agent on the host
server but would like the request to be
processed inside a virtual environments,
specify the EID for the virtual environment
using the dst/host parameter.
{
director 0..1 string
host 0..1 string
index 0..1 string
target 0..1 string
}
20
In the response messages, this information
is automatically populated by the director on
the server side.
The name of the director to which the target
operator belongs. Populated automatically
by the director.
Destination server EID. When using the
message forwarding feature, it is used for
specifying the ID of the target server.
For on-demand operators, specifies a
particular target. Populated automatically by
the director.
Contains the origin information when a
packet is sent remotely. Populated
automatically by Agent.
Agent Messages
session
}
string
Session ID.
In the request messages, this field is used to
specify the session that should be used to
process the request.
In the response messages, the ID indicates
the session that was used to process the
request.
The session ID is obtained from the
response message of the system/login
(p. 606) API call after a successful login.
The packet element may optionally contain attributes described in the following table.
Attributes of the <packet> element:
Attribute Type Description
version string
Parallels Agent protocol version number.
The current protocol version number is
4.0.0. The older 3.0.3 protocol is also
supported in Virtuozzo Containers 4.0.
id string
Packet ID. If included in a request message, the
response will contain the same ID. This allows the
response to be correlated with the original request.
The attribute must also be included if you want to be
notified in case of the request timeout, or if the
packet was dropped on the server side for any
reason. As a rule of thumb, you should always
include this element in all of your outgoing packets.
The value should normally be a string containing an
integer value, but it can also contain other characters
if needed.
21
Agent Messages
priority string
time datetime_type
progress string
Specifies the packet priority in the message queue.
The lower the number, the higher the queue priority
level for the packet, the sooner it is selected from the
queue to run.The default value is 0 (zero).
Packets are placed into queue priority pools defined
by priority value intervals:
• -10000 or smaller — emergency
messages.
• -10000 to -2000 — urgent messages.
• -2000 to 2000 — normal messages.
• 2000 or greater — heavy messages
(tasks that take a long time to
complete, such as a backup operation).
Each priority pool has a timeout value associated
with it. Therefore, by specifying the queue priority for
a packet, you are also specifying the timeout value
for it.
The time when the packet was sent; in the ISO-8601
format: (e.g. "2007-02-04T08:55:51+0000").
Use this attribute to enable the progress reporting for
long operations if you would like to receive
intermediate results and to keep track of the request
processing. Please note that not all operations
actually generate progress reports.
The possible values are:
on -- the progress reporting is on.
log string
22
off (default if the attribute is omitted) -- the
progress reporting is off.
When you turn the progress reporting on, you must
also include the id attribute (above) specifying the
message ID.
When present, the automatic progress reporting is
logged for the operations supporting it. Switch this
to “on” if you're planning to start an operation and
disconnect from Agent before the operation is
completed. By doing so, you'll be able to reconnect
later and check the log files for the results of your
operation.
The requests marked as Logged Operation in the
XML API Reference support this feature.
Possible values are:
on -- the logging is turned on.
off (default) -- the logging is off.
Agent Messages
type int
timeout int
timeout_limit int
uid int
*** INTERNAL ***
Bit field for the internal type of the message.
#define UNFINISHED 0x00000001
#define RESPONSE 0x00000002
#define RESCHEDULE 0x00000004
#define TIMEOUT 0x00000008
The timeout value which will be used for handling
this request. The value can be specified in the
incoming packet or it can be sent back from the
operator, notifying the director about the time it is
going to handle it. The value is set in seconds.
*** INTERNAL ***
Timeout limit for message processing. Used by an
operator in determining the validity of its timeout.
*** INTERNAL ***
UID of the user sending this packet.
Example:
The following is an example of an Agent message header, built according to the specifications
above. In a real message, the values of the XML elements would be substituted with the
appropriate names, IDs, etc.
<packet version="4.0.0" id="500">
<cookie>I'm a cookie holding some text</cookie>
<target>operator_name</target>
<dst>
Hosttarget_server_EID</host>
</dst>
<session>session_id</session>
</packet>
23
Agent Messages
Message Body
Message body contains the actual request or response parameters and data. The data element is
the root element of the message body tree. It is followed by the name of the interface that you
would like to use, the name of the call, and the call parameters.
Note: There must be one and only one data element in any given message.
The request message:
The following XML code example is a complete Agent request message. As you already know, the
packet element is the root element of every Agent message. The target element specifies the
name of the target operator. The message body begins with the data element. The envm element
specifies the name of the interface. The available interfaces are documented in the Parallels Agent
XML API Reference documentation. The get_info element is the name of the call. The config
element specifies that the information about the host configuration is requested.
<packet version="4.0.0" id="2">
<target>envm</target>
<data>
<envm>
<get_info>
<config/>
</get_info>
</envm>
</data>
</packet>
The response message:
The following example demonstrates a complete response message. The body of the message
begins with the data element which is followed by the name of the interface that was used in the
corresponding request message, and the return parameters.
<?xml version="1.0" encoding="UTF-8"?><packet
xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"
xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"
xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/envm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"
id="ac49b7e2c8t6784r580" time="2009-03-11T16:09:33+0000">
<ns1:origin>envm</ns1:origin>
<ns1:target>vzclient4-b1e6bc1e-4231-b541-819a-191cd7fec5fb</ns1:target>
<ns1:dst>
<director>gend</director>
</ns1:dst>
<ns1:data>
<ns2:envm>
<ns2:env xsi:type="ns3:envType">
<ns3:parent_eid>00000000-0000-0000-0000-000000000000</ns3:parent_eid>
<ns3:eid>b1e6bc1e-4231-b541-819a-191cd7fec5fb</ns3:eid>
<ns3:status xsi:type="ns3:env_statusType">
<ns3:state>6</ns3:state>
</ns3:status>
24
Agent Messages
<ns3:alert>0</ns3:alert>
<ns3:config xsi:type="ns3:env_configType">
<ns3:name>mccp40.qa.sw.ru</ns3:name>
<ns3:hostname>mccp40.qa.sw.ru</ns3:hostname>
<ns3:address>
<ns3:ip>10.27.1.174</ns3:ip>
</ns3:address>
<ns3:address>
<ns3:ip>10.37.130.2</ns3:ip>
</ns3:address>
<ns3:address>
<ns3:ip>10.37.131.2</ns3:ip>
</ns3:address>
<ns3:architecture>x86_64</ns3:architecture>
<ns3:os xsi:type="ns3:osType">
<ns3:platform>Linux</ns3:platform>
<ns3:kernel>2.6.18-028stab061.6</ns3:kernel>
<ns3:name>Parallels Server Bare Metal 5.0</ns3:name>
</ns3:os>
<ns3:type>generic</ns3:type>
<ns3:nameserver>10.27.0.1</ns3:nameserver>
<ns3:child_type>parallels</ns3:child_type>
<ns3:child_type>virtuozzo</ns3:child_type>
</ns3:config>
<ns3:virtual_config xsi:type="ns3:venv_configType"/>
</ns2:env>
</ns2:envm>
</ns1:data>
<src>
<director>gend</director>
</src>
</packet>
The body of a response message may, in general, contain one of the following types of information:
• The actual information requested, as shown in the example above.
• The <OK/> element if the call doesn't return any data by definition. The <OK/> means that the
operation completed successfully.
• An error information, in case of a failure.
A complete XML Schema specification exists for every possible response of every Agent XML API
call, and is described in the corresponding section of the Parallels Agent XML API Reference
guide.
25
C HAPTER 4
Base Types and Interfaces
This chapter describes the base XML API types and interfaces. They can be used to perform
operations on physical servers (Hardware Nodes),virtual machines, and Virtuozzo Containers. In
addition, the Virtuozzo Containers Types and Interfaces chapter (p. 620) contains specifications
of the types and interfaces that are specific to the Virtuozzo Containers only; the Parallels Server
Types and Interfaces chapter (p. 694) contains specifications of the types and interfaces that are
specific to virtual machines only.
In This Chapter
Common Types........................................................................................................ 26
Interfaces ................................................................................................................. 72
Events ...................................................................................................................... 551
System Interface and Special Packets...................................................................... 562
Common Types
This chapter describes the common data types. There are three main categories of common types:
• Primitive Types are the most basic data types. These are built-in types, which are defined in the
W3C XML Schema Data Types specification.
• Simple Types are custom types that are usually derived from primitive types with additional
restrictions imposed on them.
• Complex Types are custom types that can contain attributes and elements.
Each category is described in detail in the following sections.
Base Types and Interfaces
Primitive Types
Primitive types are the basic building blocks of an XML Schema. The following table describes the
most common primitive types used in the Agent XML Schema.
Name Description
boolean
int
long
double
string
base64Binary
Boolean type. Legal values for boolean are true, false, 1 (which indicates
true), and 0 (which indicates false).
A signed 32-bit integer.
A signed 64-bit integer
A 64-bit floating point.
A string. Note that unlike char arrays in C, XML strings are NOT null-terminated.
Base64-encoded binary data.
Simple Types
Simple types are custom types that can contain a value but cannot contain attributes or elements.
Most of the custom simple types have restrictions added to them in order to limit their content. A
restriction can limit the type to a specific primitive data type, it can also define a list of enumerated
values, or it can define a string pattern that the value must adhere to.
27
Base Types and Interfaces
datetime_type
Summary:
Holds a datetime value.
Type specification:
datetime_type is derived from string
The type complies with ISO-8601, the International Standard for the representation of dates and
times. The format is as follows.
YYYY-MM-DDThh:mm:ssZ
where:
YYYY -- four-digit year.
MM -- two-digit month (01 = January, etc.).
DD -- two-digit day of month (01 through 31).
The letter T in DDThh must literally be present to indicate the beginning of the time element.
hh -- two digits of hour (00 through 23, am/pm is NOT allowed).
mm -- two digits of minute (00 through 59).
ss -- two digits of second (00 through 59).
Z -- GMT/UTC offset (+hhmm or -hhmm).
Example:
2006-05-28T19:05:30-0500 corresponds to May 28, 2006, 19:05:30 (or 7:05:30 pm), US Eastern
Standard Time.
28
Base Types and Interfaces
eid_type
Summary:
Holds a Server ID value. Server ID is a globally unique identifier that is assigned to every computer
(physical or virtual) that has Parallels Agent installed on it. The ID is assigned to a physical server as
soon as Parallels Virtual Automation software is installed on it. The ID is assigned to a virtual
environment at the time of creation.
Type specification:
Restriction: guid_type (p. 29)
guid_type
Summary:
A globally unique identifier.
Type specification:
guid_type is derived from string
ip_type
Summary:
IP (Internet Protocol) address expressed as four decimal numbers separated by periods, such as
192.168.1.10
Type specification:
ip_type is derived from string
privilegeType
Summary:
A security privilege identification.
Type specification:
Restriction: string
29
Base Types and Interfaces
sidType
Summary:
Security ID.
Type specification:
Restriction: base64Binary
transport_type
Summary:
Transport type enumeration.
Type specification:
The enumeration has the following enumerators:
TCP -- Transmission Control Protocol.
UDP -- User Datagram Protocol.
Complex Types
Complex types are custom types that can contain text, attributes and other elements. This section
describes the types that are common to the entire Parallels Agent XML API.
30
Loading...