XML API

619 Pages·2015·3.57 MB·English

PVA Agent
XML API Reference

Copyright © 1999-2015 Parallels IP Holdings GmbH and its affiliates. All rights reserved.
Parallels IP Holdings GmbH.
c/o Parallels International GmbH.
Parallels International GmbH
Vordergasse 49
CH8200 Schaffhausen
Switzerland
Tel: + 41 526320 411
Fax: + 41 52672 2010
www.odin.com

Copyright © 1999-2015 Parallels IP Holdings GmbH and its affiliates. All rights reserved.

This product is protected by United States and international copyright laws. The product’s underlying technology,
patents, and trademarks are listed at http://www.odin.com/trademarks.

Microsoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are registered trademarks of Microsoft
Corporation.
Apple, Mac, the Mac logo, Mac OS, iPad, iPhone, iPod touch, FaceTime HD camera and iSight are trademarks of Apple
Inc., registered in the US and other countries.
Linux is a registered trademark of Linus Torvalds.
All other marks and names mentioned herein may be trademarks of their respective owners.
Contents
Preface ....................................................................................................................... 6
About This Guide ............................................................................................................ 6
Who Should Read This Guide .......................................................................................... 6
Organization of This Guide............................................................................................... 6
How to Use This Guide ................................................................................................... 7
Feedback ........................................................................................................................ 8
Reference Format ...................................................................................................... 9
XML Message Specifications ........................................................................................... 9
XML Code Samples ...................................................................................................... 11
Agent Messages ...................................................................................................... 13
Message Header ........................................................................................................... 13
Message Body .............................................................................................................. 17
Base Types and Interfaces ..................................................................................... 19
Common Types ............................................................................................................ 19
Primitive Types ...................................................................................................................... 19
Simple Types ......................................................................................................................... 20
Complex Types ..................................................................................................................... 22
Interfaces ...................................................................................................................... 53
alertm .................................................................................................................................... 54
authm .................................................................................................................................... 61
backup_storagem ................................................................................................................. 89
backupm ............................................................................................................................... 89
server_group ....................................................................................................................... 121
computerm .......................................................................................................................... 136
data_storagem .................................................................................................................... 150
devm ................................................................................................................................... 152
sample_manager ................................................................................................................. 179
envm ................................................................................................................................... 184
event_log ............................................................................................................................. 216
filer ...................................................................................................................................... 219
Contents

firewallm .............................................................................................................................. 242
licensem .............................................................................................................................. 249
mailer .................................................................................................................................. 262
relocator .............................................................................................................................. 269
networkm ............................................................................................................................ 291
op_log ................................................................................................................................. 307
perf_mon ............................................................................................................................. 311
packagem ........................................................................................................................... 319
proc_info ............................................................................................................................. 352
processm ............................................................................................................................ 359
res_log ................................................................................................................................ 364
ip_poolm ............................................................................................................................. 374
scheduler ............................................................................................................................ 384
servicem .............................................................................................................................. 396
sessionm ............................................................................................................................. 405
userm .................................................................................................................................. 419
Events ........................................................................................................................ 438
Types .................................................................................................................................. 438
Elements ............................................................................................................................. 440
System Interface and Special Packets ......................................................................... 447
system................................................................................................................................. 447
The progress packet ........................................................................................................... 492
Container (CT) Types and Interfaces .................................................................... 496
Common Types .......................................................................................................... 496
Simple Types ....................................................................................................................... 496
Complex Types ................................................................................................................... 497
Interfaces .................................................................................................................... 505
vzadevm .............................................................................................................................. 505
vzaenvm .............................................................................................................................. 506
vzarelocator ......................................................................................................................... 528
vzanetworkm ....................................................................................................................... 531
vzapackagem ...................................................................................................................... 536
vzaproc_info ........................................................................................................................ 536
vzaprocessm ....................................................................................................................... 542
vzaup2date ......................................................................................................................... 544
Contents

vzasupport .......................................................................................................................... 549
Virtual Machine (VM) Types and Interfaces .......................................................... 556
Common Types .......................................................................................................... 556
Complex Types ................................................................................................................... 556
Interfaces .................................................................................................................... 574
vzpenvm .............................................................................................................................. 574
vzpdevm .............................................................................................................................. 580
vzpnetworkm ....................................................................................................................... 582
vzprelocator......................................................................................................................... 583
vzpsample_manager ........................................................................................................... 585
Appendix A: Performance Counters ..................................................................... 588
Appendix B: States and Transitions ..................................................................... 597
Appendix C: Error Codes ...................................................................................... 599
Index ...................................................................................................................... 614
C H A P T E R 1
Preface
In This Chapter
About This Guide ................................................................................................... 6
Who Should Read This Guide ................................................................................. 6
Organization of This Guide ...................................................................................... 6
How to Use This Guide ........................................................................................... 7
Documentation Conventions ................................................................................... 8
Feedback ............................................................................................................... 8

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.

Organization of This Guide
This guide is organized into the following chapters:
Chapter 1, Preface. Provides information about this guide.
Preface

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. 19) describes the base data types
that are used throughout the API. The Interfaces section (p. 53) 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.

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
interface (p. 506) allows you to manage Virtuozzo Containers, the interface
vzaenvm perf_mon
(p. 311) 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, and
vzaenvm vzpenvm
7
Preface

stands for Virtuozzo Containers and Parallels virtual machine management, respectively;
stands for Performance Monitoring, etc. To find the specifications for a particular
perf_mon
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.

Feedback
If you want to report typos, share comments, suggestions or ideas on improving this guide, please
use the Parallels documentation feedback page at http://www.parallels.com/en/support/usersdoc/.

8
C H A P T E R 2
Reference Format
This chapter explains how to use the specifications presented in this guide.
In This Chapter
XML Message Specifications .................................................................................. 9
XML Code Samples ............................................................................................... 11

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
{
User name.
name 0..1 base64Binary
Domain.
domain 0..1 base64Binary
Realm ID.
realm 1..1 guid_type
User password.
password 0..1 base64Binary
Custom timeout value.
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.
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
element. This means that the elements inside the brackets are the child elements of
xs:sequence
the element that precedes the opening bracket. In our example, the , , ,
name domain realm
, and elements are children of the element. The following is a
password expiration login
sample XML code, built according to this specification:
Reference Format

<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 element,
xs:choice
as shown in the following example:
Name Min/Max Type Description
status Device status,
[ Denotes a choice between the <up> and the <down>
elements.
Enabled.
up 1..1 none
Disabled.
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.
Min/Max. Specifies the cardinality of an element (the number of its minimum and maximum
occurrences) in the following format:

minOccurs..maxOccurs
in the first position indicates that the element is optional.
• 0
in the first position indicates that the element is mandatory and must occur at least once.
• 1
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:
The element is optional and may occur only once if included in the document.
• 0..1
The element is mandatory. One, and only one, occurrence is expected in the
• 1..1
document.
The element is optional but may occur an unlimited number of times if needed.
• 0..[]
The element is mandatory. At least one occurrence is expected but the element may
• 1..[]
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: etc.
• int, string, base64Binary,
Custom simple types. These types are usually derived from standard simple types with
•
additional restrictions imposed on them.
10