pva agent xml api reference
Post on 04-Jun-2018
258 Views
Preview:
TRANSCRIPT
-
8/13/2019 PVA Agent XML API Reference
1/736
Copyright 1999-2012 Parallels Holdings, Ltd. and its affiliates. All rights reserved.
PVA AgentXML API Reference
Copyright 1999-2012 Parallels, Inc.
-
8/13/2019 PVA Agent XML API Reference
2/736
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.parallels.com
Copyright 1999-2012 Parallels IP Holdings GmbH and its affiliates. All rights reserved.
This product is protected by United States and international copyright laws. The products underlying technology,
patents, and trademarks are listed at http://www.parallels.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.
-
8/13/2019 PVA Agent XML API Reference
3/736
Contents
Preface.......................................................................................................................6About This Guide ..............................................................................................................6Who Should Read This Guide ...........................................................................................6Organization of This Guide ................................................................................................ 7How to Use This Guide .....................................................................................................8Documentation Conventions ............................................................................................. 8
Typographical Conventions ..................................................................................................... 9Shell Prompts in Command Examples................................................................................... 10General Conventions ............................................................................................................. 10
Feedback........................................................................................................................11Reference Format....................................................................................................12
XML Message Specifications...........................................................................................13XML Code Samples ........................................................................................................16
Agent Messages......................................................................................................18Message Header.............................................................................................................19Message Body................................................................................................................24
Base Types and Interfaces .....................................................................................26Common Types ..............................................................................................................26
Primitive Types ...................................................................................................................... 27Simple Types......................................................................................................................... 27Complex Types ..................................................................................................................... 30
Interfaces ........................................................................................................................ 71alertm.................................................................................................................................... 71authm.................................................................................................................................... 80backup_storagem ............................................................................................................... 119backupm............................................................................................................................. 119server_group ....................................................................................................................... 160computerm.......................................................................................................................... 177data_storagem .................................................................................................................... 195devm................................................................................................................................... 198
-
8/13/2019 PVA Agent XML API Reference
4/736
Contents
vzasample_manager............................................................................................................ 231envm ................................................................................................................................... 236event_log............................................................................................................................. 274filer ...................................................................................................................................... 279firewallm .............................................................................................................................. 305licensem.............................................................................................................................. 314mailer .................................................................................................................................. 330relocator.............................................................................................................................. 339networkm ............................................................................................................................ 363op_log ................................................................................................................................. 383perf_mon............................................................................................................................. 388packagem ........................................................................................................................... 398proc_info ............................................................................................................................. 435processm ............................................................................................................................ 444res_log ................................................................................................................................ 451ip_poolm ............................................................................................................................. 464scheduler ............................................................................................................................ 477servicem.............................................................................................................................. 494sessionm............................................................................................................................. 505userm.................................................................................................................................. 523
Events...........................................................................................................................550Types .................................................................................................................................. 550Elements ............................................................................................................................. 552
System Interface and Special Packets...........................................................................561system................................................................................................................................. 561
The progress packet ........................................................................................................... 615Virtuozzo Containers Types and Interfaces..........................................................619
Common Types ............................................................................................................619Simple Types....................................................................................................................... 619Complex Types ................................................................................................................... 620
Interfaces ......................................................................................................................630vzadevm.............................................................................................................................. 631vzaenvm.............................................................................................................................. 632vzarelocator......................................................................................................................... 657vzanetworkm....................................................................................................................... 660
-
8/13/2019 PVA Agent XML API Reference
5/736
Contents
vzapackagem...................................................................................................................... 667vzaproc_info........................................................................................................................ 668vzaprocessm....................................................................................................................... 675vzaup2date ......................................................................................................................... 677vzasupport .......................................................................................................................... 684
Parallels Server Types and Interfaces ..................................................................693Common Types ............................................................................................................693
Complex Types ................................................................................................................... 693Interfaces ......................................................................................................................701
vzpenvm.............................................................................................................................. 701vzprelocator......................................................................................................................... 705
Appendix A: Performance Counters.....................................................................707
Appendix B: States and Transitions .....................................................................715Appendix C: Error Codes ......................................................................................717Index ......................................................................................................................732
-
8/13/2019 PVA Agent XML API Reference
6/736
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 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
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.
C H A P T E R 1
Preface
-
8/13/2019 PVA Agent XML API Reference
7/736
7
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 Typessection(p. 26) describes the base data types
that are used throughout the API. The Interfacessection(p. 71) describes the base interfaces and
the available API calls. Each API call documentation consists of the XML request and responsespecifications, 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 Interfaceschapter 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.
-
8/13/2019 PVA Agent XML API Reference
8/736
8
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 atleast the Prefacechapter (you are reading it now), the Reference Formatchapter, and theAgent
Messageschapter. 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 Guidewhich is a companion book to this one.
Each XML API interface provides calls to perform operations of a particular type. For example, the
vzaenvminterface(p. 632) allows you to manage Virtuozzo Containers, the per f _moninterface(p. 388) 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, vzaenvmand vzpenvmstands for Virtuozzo Containers and Parallels virtual machine management, respectively;
per f _monstands for Performance Monitoring, etc. To find the specifications for a particularoperation, browse the Interfacessections of the Base Types and Interfaceschapter or the
Virtuozzo Containers Types and Interfacesand Parallels Server Types and Interfaceschapter.
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.
The table below presents the existing formatting conventions:
Formatting Conventions Type of information Example
Items you must select, such asmenu options, command buttons
or items in a list.
Go to the Resourcestab.Special Bold
Titles of chapters, sections andsubsections.
Read the Basic Administrationchapter.
-
8/13/2019 PVA Agent XML API Reference
9/736
9
Preface
Italics Used to emphasize the
importance of a point, tointroduce a term or to designate a
command line placeholder, whichis to be replaced with a real name
or value.
These are the so-called EZ templates.
To destroy a Container, type vzct l
dest r oyCT_ID.
Monospace The names of commands, filesand directories.
Use vzct l start to start a Container.
Pref ormatt ed On-screen computer output inyour command line sessions;
source code in XML, C++, orother programming languages.
Saves par ameters f or Cont ai ner101
Monospace BoldWhat you type as contrasted withon-screen computer output.
# rpm -V virtuozzo-release
Key+Key Key combinations for which theuser should press and hold down
one key and then press another.
Ctrl+P, Alt+F4
Besides the formatting conventions, you should also know about the document organization
convention applied to Parallels documents: chapters in all guides are divided into sections, which,
in turn, are subdivided into subsections. For example,About This Guideis a section, and
Documentation Conventionsis a subsection.
Typographical Conventions
The following kinds of formatting in the text identify special information.
Formattingconvention
Type of Information Example
Triangular Bullet() Step-by-step procedures. You can follow
the instructions below to complete aspecific task.
To create a Container:
Special Bold Items you must select, such as menuoptions, command buttons, or items in a
list.
Go to the Resourcestab.
Titles of chapters, sections, and
subsections.
Read the Basic Administrationchapter.
-
8/13/2019 PVA Agent XML API Reference
10/736
10
Preface
Italics Used to emphasize the importance of a
point, to introduce a term or to designatea command line placeholder, which is to
be replaced with a real name or value.
These are the so-called EZ templates.
To destroy a Conainer, type vzctl dest r oy
ctid.
Monospace The names of commands, files, and
directories.
Use vzct l start to start a Container.
Pref ormatt ed On-screen computer output in yourcommand-line sessions; source code in
XML, C++, or other programminglanguages.
Saved par ameters f or Cont ai ner 101
Monospace BoldWhat you type, contrasted with on-screencomputer output.
# rpm V virtuozzo-release
CAPITALS Names of keys on the keyboard. SHIFT, CTRL, ALT
KEY+KEY Key combinations for which the user mustpress and hold down one key and thenpress another.
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 Conventionsis a section, and General Conventionsis 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 / bi n, / sbi n, / us r / bi nand / us r / sbi ndirectories, so thesteps 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.
-
8/13/2019 PVA Agent XML API Reference
11/736
11
Preface
Feedback
If you want to report typos, share comments, suggestions or ideas on improving this guide, pleaseuse the Parallels documentation feedback page(http://www.parallels.com/en/support/usersdoc/).
http://www.parallels.com/en/support/usersdoc/http://www.parallels.com/en/support/usersdoc/ -
8/13/2019 PVA Agent XML API Reference
12/736
This chapter explains how to use the specifications presented in this guide.
In This Chapter
XML Message Specifications.................................................................................... 13
XML Code Samples ................................................................................................. 16
C H A P T E R 2
Reference Format
-
8/13/2019 PVA Agent XML API Reference
13/736
13
Reference Format
XML Message Specifications
The XML message specifications in this guide are described using tables, similar to the followingexample:
Name Min/Max Type Description
l ogi n
{
name 0. . 1 base64Bi nar y User name.
domai n 0. . 1 base64Bi nar y Domain.
r eal m 1. . 1 gui d_t ype Realm ID.
password 0. . 1 base64Bi nar y User password.
expi rati on 0. . 1 i nt Custom timeout value.
}
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
xs: sequenceelement. This means that the elements inside the brackets are the child elements ofthe element that precedes the opening bracket. In our example, the name, domai n, real m,
passwor d, and expi r at i onelements are children of the l ogi nelement. The following is asample XML code, built according to this specification:
bXl uYW1l bXl kb21haW4=bXl yZWFsbQ==bXl wYXNz1000
In addition, we use square brackets to represent the standard XML Schema xs: choi ceelement,
as shown in the following example:
Name Min/Max Type Description
status Device status,
[ Denotes a choice between the and the elements.
up 1. . 1 none Enabled.
-
8/13/2019 PVA Agent XML API Reference
14/736
14
Reference Format
down 1. . 1 none Disabled.
]
This means that the elements inside the brackets are the child elements of the element that precedes the openingbracket 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:
mi nOccur s. . maxOccur s
0in the first position indicates that the element is optional. 1in 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: i nt , st r i ng, base64Bi nar y, 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 qualifiedAgent 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:
-
8/13/2019 PVA Agent XML API Reference
15/736
15
Reference Format
QWRt aW5pc3RyYXRvcg==00000000- 0000- 0000- 0000- 000000000000MXEydzNl
-
8/13/2019 PVA Agent XML API Reference
16/736
16
Reference Format
XML Code Samples
Most of the XML API call descriptions have one or more XML code samples. The samples areprovided 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
Output
vzl . 30100. ba7be334- 4804- 4494- a9c8- 15149a0438a5. 8c446ae612t2cd6vzcl i ent 4
gend
pvaagent - 4. 0. 0
gend
The Inputsection contains a complete XML response message built according to the schema
definition.
The Outputsection 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
Outputexamples for brevity. These attributes and elements may include t i me, pr i or i tyfrom the
element, and , , , from the message header, and
possibly some other elements and attributes that are not essential to a particular example. The element containing the output data will be included in its entirety, unless noted otherwise in the example
itself.
-
8/13/2019 PVA Agent XML API Reference
17/736
17
Reference Format
-
8/13/2019 PVA Agent XML API Reference
18/736
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
C H A P T E R 3
Agent Messages
-
8/13/2019 PVA Agent XML API Reference
19/736
19
Agent Messages
Message Header
The two main sections of any Agent XML message is theheaderand thebody. The headerprovides 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 The root element of an Agent XML message.
{
cooki e 0. . 1 s t r i ng User-defined information describing themessage, or any other type of information.
The data specified here remains unchangedduring the request/response operation, i.e. if
you put some data into this element in therequest message, the response messagewill contain the same data.
t arget 0. . [ ] s t r i ng In request messages, this element mustcontain the name of the operator to whichthe request should be sent for processing.
Note:When using the system
operator, do not include the
t ar get element. The systemoperator is the only exception. All
other operators require this element.
The name of the operator is always thesame as the name of the corresponding
interface that you are using. For example, if
you are using a call from the vzaenvminterface, 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 elementcontains the name of the client thatoriginated the request (the value isgenerated and used internally by Agent).
or i gi n 0. . 1 s t r i ng The name of the operator that generated theresponse. Included in response messagesonly.
-
8/13/2019 PVA Agent XML API Reference
20/736
20
Agent Messages
sr c 0. . 1 r out eType The source routing information. This field isautomatically populated by the director onthe server side when a message is routed
from the corresponding operator to it. Thesame information is also duplicated in the
dst element (described below) when aresponse is generated and is sent back tothe client.
{
di r ector 0. . 1 s t r i ng The name of the director to which the targetoperator belongs.
host 0. . 1 s t r i ng The Agent host ID. Used by Agent todetermine the host address. Should be
either contained in the Agent configuration(global mapping) or be a result of exclusive
connect.
i ndex 0. . 1 s t r i ng For on-demand operators, specifies a
particular target.
t arget 0. . 1 s t r i ng Contains the origin information when apacket is sent remotely.
}
dst r out eType The destination routing information.
In request messages, use this structure tospecify the server to which you want toforward the request. For example, if you are
sending a request to the Agent on the hostserver but would like the request to be
processed inside a virtual environments,specify the EID for the virtual environment
using the dst / host parameter.
In the response messages, this informationis automatically populated by the director onthe server side.
{
di r ector 0. . 1 s t r i ng The name of the director to which the targetoperator belongs. Populated automaticallyby the director.
host 0. . 1 s t r i ng Destination server EID. When using themessage forwarding feature, it is used for
specifying the ID of the target server.
i ndex 0. . 1 s t r i ng For on-demand operators, specifies aparticular target. Populated automatically bythe director.
t arget 0. . 1 s t r i ng Contains the origin information when apacket is sent remotely. Populatedautomatically by Agent.
}
-
8/13/2019 PVA Agent XML API Reference
21/736
21
Agent Messages
sessi on s t r i ng Session ID.
In the request messages, this field is used to
specify the session that should be used toprocess the request.
In the response messages, the ID indicatesthe session that was used to process therequest.
The session ID is obtained from the
response message of the syst em/ l ogi n(p. 605) API call after a successful login.
}
The packet element may optionally contain attributes described in the following table.
Attributes of the element:
Attribute Type Description
versi on s t r i ngParallels 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.
i d s t r i ng Packet ID. If included in a request message, theresponse will contain the same ID. This allows theresponse 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 thepacket was dropped on the server side for anyreason. 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 charactersif needed.
pr i or i t y s t r i ng Packet priority. Specifies the significance of themessage when it is placed into a message queue.
The higher the priority value, the less significant thepacket is. The value of zero is the default priority.
Priorities range from -3000 to 3000.
-3000 to -1000 for heavy messages.
-999 to 999 for normal messages.
1000 to 3000 for urgent messages.
t i me datet i me_t ype The time when the packet was sent; in the ISO-8601format: (e.g. "2007-02-04T08:55:51+0000").
-
8/13/2019 PVA Agent XML API Reference
22/736
22
Agent Messages
pr ogr ess s t r i ng Use this attribute to enable the progress reporting forlong operations if you would like to receiveintermediate results and to keep track of the request
processing. Please note that not all operationsactually generate progress reports.
The possible values are:
on-- the progress reporting is on.
of f(default if the attribute is omitted) -- theprogress reporting is off.
When you turn the progress reporting on, you must
also include the i dattribute (above) specifying themessage ID.
l og s t r i ng When present, the automatic progress reporting islogged for the operations supporting it. Switch this
to on if you're planning to start an operation anddisconnect from Agent before the operation is
completed. By doing so, you'll be able to reconnectlater and check the log files for the results of youroperation.
The requests marked as Logged Operationin theXML API Reference support this feature.
Possible values are:
on-- the logging is turned on.
of f(default) -- the logging is off.
t ype i nt *** INTERNAL ***
Bit field for the internal type of the message.
#define UNFINISHED 0x00000001
#define RESPONSE 0x00000002
#define RESCHEDULE 0x00000004
#define TIMEOUT 0x00000008
t i meout i nt The timeout value which will be used for handlingthis request. The value can be specified in the
incoming packet or it can be sent back from theoperator, notifying the director about the time it isgoing to handle it. The value is set in seconds.
t i meout _l i mi t i nt *** INTERNAL ***
Timeout limit for message processing. Used by anoperator in determining the validity of its timeout.
ui d i nt *** 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.
-
8/13/2019 PVA Agent XML API Reference
23/736
23
Agent Messages
I'm a cookie holding some textoperator_name
Hosttarget_server_EID
session_id
-
8/13/2019 PVA Agent XML API Reference
24/736
24
Agent Messages
Message Body
Message body contains the actual request or response parameters and data. The dataelement isthe 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 dat aelement 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 t ar get element specifies the
name of the target operator. The message body begins with the dataelement. The envmelementspecifies the name of the interface. The available interfaces are documented in the Parallels Agent
XML API Referencedocumentation. The get _i nf oelement is the name of the call. The conf i gelement specifies that the information about the host configuration is requested.
envm
The response message:
The following example demonstrates a complete response message. The body of the message
begins with the dataelement which is followed by the name of the interface that was used in thecorresponding request message, and the return parameters.
envmvzcl i ent 4-b1e6bc1e- 4231-b541- 819a- 191cd7f ec5f b
gend
00000000- 0000- 0000- 0000- 000000000000b1e6bc1e- 4231- b541- 819a- 191cd7f ec5f b
6
-
8/13/2019 PVA Agent XML API Reference
25/736
25
Agent Messages
0
mccp40. qa. sw. r umccp40. qa. sw. r u
10. 27. 1. 174
10. 37. 130. 2
10. 37. 131. 2x86_64
Li nux2. 6. 18- 028st ab061. 6Paral l el s Ser ver Bare Metal 5. 0
gener i c10. 27. 0. 1
paral l el svi r t uozzo
gend
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 element if the call doesn't return any data by definition. The 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.
-
8/13/2019 PVA Agent XML API Reference
26/736
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, theVirtuozzo Containers Types and Interfaceschapter(p. 619) contains specifications
of the types and interfaces that are specific to the Virtuozzo Containers only; the Parallels Server
Types and Interfaceschapter(p. 693) contains specifications of the types and interfaces that are
specific to virtual machines only.
In This Chapter
Common Types........................................................................................................ 26
Interfaces ................................................................................................................. 71
Events ...................................................................................................................... 550
System Interface and Special Packets ...................................................................... 561
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 theW3C XML Schema Data Types specification.
Simple Types are custom types that are usually derived from primitive types with additionalrestrictions imposed on them.
Complex Types are custom types that can contain attributes and elements.Each category is described in detail in the following sections.
C H A P T E R 4
Base Types and Interfaces
-
8/13/2019 PVA Agent XML API Reference
27/736
27
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
bool ean Boolean type. Legal values for boolean are true, f al se, 1(which indicates
true), and 0(which indicates false).
i nt A signed 32-bit integer.
l ong A signed 64-bit integer
doubl e A 64-bit floating point.
s t r i ng A string. Note that unlike char arrays in C, XML strings are NOT null-terminated.
base64Bi nar y 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.
-
8/13/2019 PVA Agent XML API Reference
28/736
28
Base Types and Interfaces
datetime_type
Summary:
Holds a datetime value.
Type specification:
dat et i me_t ypeis derived from st r i ng
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 letterTin DDThhmust 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.
-
8/13/2019 PVA Agent XML API Reference
29/736
29
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:
gui d_t ypeis derived from st r i ng
ip_type
Summary:
IP (Internet Protocol) address expressed as four decimal numbers separated by periods, such as
192.168.1.10
Type specification:
i p_t ypeis derived from s t r i ng
privilegeType
Summary:
A security privilege identification.
Type specification:
Restriction: st r i ng
-
8/13/2019 PVA Agent XML API Reference
30/736
30
Base Types and Interfaces
sidType
Summary:
Security ID.
Type specification:
Restriction: base64Bi nar y
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.
-
8/13/2019 PVA Agent XML API Reference
31/736
31
Base Types and Interfaces
aceType
Summary:
Access control entry.
Type specification:
Name Min/Max Type Description
t ype 1. . 1 i nt Type of ACE:
0-- allow
1-- deny
si d 1. . 1 si dType(p. 30) Security identifier of a user or a group.
r i ght s 1. . 1 base64Bi nar y Access rights.
Description:
The access control entry (ACE) is an individual record in a DACL (Discretionary Access Control List).
It includes the SID (security ID) of a single user or a group along with an access mask that specifies
the permissions being granted or denied.
At the time of this writing, you can only set permissions to the entire object (not the individual
operations that can be performed on it). This means that the r i ght sparameter is not currently
used. Simply include an empty r i ght selement when setting permissions.
See also:
secur i t y_descri pt or Type(p. 62)
-
8/13/2019 PVA Agent XML API Reference
32/736
32
Base Types and Interfaces
alert_dataType
Summary:
Contains alert information.
Type specification:
Extends event_dat aType(p. 40)
Adds the following elements:
Name Min/Max Type Description
t ype 1. . 1 i nt 0-- green alert.
1-- yellow alert.
2-- red alert.
Description:
The alert type denotes the severity level. There are four alert levels:
Green alert-- Normal operation. This alert type is normally silent but can still trigger when one of the
higher alert levels is canceled and the situation returns to normal.
Yellow alert-- Warning. For a resource allocation alert it means that at least 90% of the specified
soft limit was reached.
Red alert -- Critical situation. For a resource alert it means that the current resource usage is above
the soft limit and further allocation can be refused at any moment.
The subtypes of al er t _dat aTypeare used to handle different alert categories, such as resourceallocation alerts and cluster-wide alerts.
Subtypes:
r esour ce_al er t Type(p. 72)
server _gr oup_al er t Type(p. 73)
-
8/13/2019 PVA Agent XML API Reference
33/736
33
Base Types and Interfaces
auth_nameType
Summary:
User login information.
Type specification:
Name Min/Max Type Description
name 0. . 1 base64Bi nar y The name of a user or a group.
When working with LDAP directory
entries, the name can be specified asa fully qualified distinguished name oras a plain name (as in "John" forinstance). If the name contains a full
DN then the entry is assumed to belocated in the container specified. If
the name is a plain name (as in "John"for instance), the entry is assumed tobe located in the default container for
users and groups for this realm. Tofind out what the default DN is, use the
get _real mcall(p. 111).
domai n 0. . 1 base64Bi nar y Domain name. Currently, this filed isonly used to specify the Server ID (eid)
when logging into Agent as a userfrom the Virtuozzo Container Realm(the OS user registry inside the
Container).
r eal m 1. . 1 gui d_t ype(p. 29) Realm ID. When adding a user or a
group to a realm, specify the targetrealm ID here.
-
8/13/2019 PVA Agent XML API Reference
34/736
34
Base Types and Interfaces
connection_infoType
Summary:
Contains parameters necessary to connect to a remote computer.
Type specification:
Extends connect i vi t y_i nf oType(p. 34)
Adds the following elements:
Name Min/Max Type Description
l ogi n 0. . 1 aut h_nameType(p. 33) Login information.
passwor d 0. . 1 base64Bi nar y Password.
connectivity_infoType
Summary:
Contains the network connectivity information.
Type specification:
Adds the following elements:
Name Min/Max Type Description
pr otocol 0. . 1 s t r i ng Communication protocol:
SSL-- SSL over TCP/IP.
TCP-- plain TCP/IP.
NamedPi pe-- named pipe.
address 1. . 1 s t r i ng IP address.
por t 0. . 1 unsi gnedI nt Port number.
-
8/13/2019 PVA Agent XML API Reference
35/736
35
Base Types and Interfaces
cpu_loadType
Summary:
Contains CPU load values.
Type specification:
Name Min/Max Type Description
syst em 1. . 1 l ong CPU used by system processes.
user 1. . 1 l ong CPU used by user processes.
ni ce 1. . 1 l ong CPU used by "nice" processes.
i dl e 1. . 1 l ong CPU idle.
cpuType
Summary:
Contains common CPU characteristics.
Type specification:
Name Min/Max Type Description
mhz 1. . 1 i nt CPU Frequency, in MegaHertz.
name 1. . 1 st r i ng CPU name.
number 1. . 1 i nt Number of CPUs in the system.
cores 1. . 1 i nt Number of cores per CPU.
hyper t hreads 1. . 1 i nt Number of hyper-threads per CPU core.The value of 1indicates that no hyper-threading is available.
uni t s 1. . 1 i nt CPU unit value.
f ami l y 1. . 1 st r i ng CPU family.
model 1. . 1 st r i ng CPU model.
bogomi ps 1. . 1 i nt BogoMIPS value.
-
8/13/2019 PVA Agent XML API Reference
36/736
36
Base Types and Interfaces
credentialType
Summary:
Describes the security attributes of a security principle.
Type specification:
Name Min/Max Type Description
i d 1. . 1 st r i ng The ID of the node in thecredentials hierarchy.
pol i cy 0. . 1 i nt Policy:
1-- allow (default)
0-- deny
descri pt i on 0. . 1 base64Bi nar y Credential description.
cred 0. . [ ] credent i al Type(p.36)
Nested credentials.
eid_listType
Summary:
Holds a list of Server ID values. See ei d_t ype(p. 29) for the explanation on what a Server ID is.
Type specification:
Name Min/Max Type Description
ei d 0. . [ ] ei d_t ype(p.29)
Server IDs.
-
8/13/2019 PVA Agent XML API Reference
37/736
37
Base Types and Interfaces
env_configType
Summary:
Contains server configuration information. This is a base type. It has only the attributes that arecommon to the systems of all types (physical and virtual). The subtypes of this type extend it
adding more attributes that are specific to their respective server types.
Type specification:
Name Min/Max Type Description
name 0. . 1 s t r i ng Server name.
descri pt i on 0. . 1 base64Bi nar y Server description.
domai n 0. . 1 s t r i ng Domain name.
host name 0. . 1 s t r i ng Hostname.
address 0. . [ ] i p_addressType(p.46)
List of IP addresses.
Do not use this field whenadding or modifying IPaddresses of VirtuozzoContainers. Use net_deviceelement of venv_configType(p. 626) instead.
ar chi t ecture 0. . 1 s t r i ng CPU architecture.
os 0. . 1 osType(p. 55) Operating system.
t ype 0. . 1 s t r i ng Server type.
nameser ver 0. . [ ] s t r i ng Name servers.
Use this element whensetting nameserverinformation for a LinuxVirtuozzo Container.
For Windows Containers, use element ofvenv_configType (p. 626)
instead.
sear ch_domai n 0. . [ ] s t r i ng Search domains.
base_sampl e_i d 0. . 1 gui d_t ype(p. 29) Base sample config ID.
base_snapshot _i d 0. . 1 gui d_t ype(p. 29) Base snapshot ID.
Subtypes:
venv_conf i gType(p. 69)
-
8/13/2019 PVA Agent XML API Reference
38/736
38
Base Types and Interfaces
env_resourceType
Summary:
Contains a list of IP addresses allocated to a server.
Type specification:
Name Min/Max Type Description
ei d 1. . 1 ei d_t ype(p. 29) Server ID.
i p_pool 0. . 1 i p_pool Type(p. 47) Allocated IP pool.
env_security_objectType
Summary:
A security object of type "server".
Type specification:
Extends secur i t y_obj ect Type(p. 62)
Adds the following elements:
Name Min/Max Type Description
ei d 1. . 1 ei d_t ype(p. 29) Server ID.
-
8/13/2019 PVA Agent XML API Reference
39/736
39
Base Types and Interfaces
env_statusType
Summary:
Contains a server status information.
Type specification:
Name Min/Max Type Description
state 0. . 1 i nt The server state code.
t r ans i t i on 0. . 1 i nt The server transition code.
Description:
A server can be either in a stable state (running, stopped, etc.) or it can be in transition to another
stable state (starting, stopping, etc.). For the list of states and transitions, seeAppendix B: States
and Transitions(p. 715).
envType
Summary:
Contains server information. This type is used for any server type, virtual or physical. However, the
conf i gand vi rt ual _conf i gelements may be instantiated using the server type-specificsubtypes of their respective types.
Type specification:
Name Min/Max Type Description
par ent _ei d 1. . 1 ei d_t ype(p. 29) Parent server ID.
ei d 1. . 1 ei d_t ype(p. 29) Server ID.
status 0. . 1 env_st atusType(p. 39) Server status.
al ert 0. . 1 i nt If any alerts are currentlyraised on the server then this
field will contain the highestexisting alert level. See
al ert _dataType(p. 32)for the list of alert levels.
conf i g 0. . 1 env_conf i gType(p. 37) Regular configuration
information.
vi r t ual _conf i g 0. . 1 env_conf i gType(p. 37) Virtual configurationinformation.
-
8/13/2019 PVA Agent XML API Reference
40/736
-
8/13/2019 PVA Agent XML API Reference
41/736
41
Base Types and Interfaces
eventType
Summary:
Contains a system event information.
Type specification:
Name Min/Max Type Description
ei d 1. . 1 ei d_t ype(p. 29) The ID of the server thatgenerated the event.
t i me 1. . 1 datet i me_t ype(p. 28) The time at which the event wasgenerated.
sour ce 1. . 1 st r i ng The name of the event source --a plug-in or an operator name.
category 1. . 1 st r i ng The category of the event.
si d 0. . 1 si dType(p. 30) The user SID (security ID).Identifies the active user at thetime the event was generated.
count 1. . 1 i nt Message counter. Countsmessages received from the
same source from the last serverrestart.
i d 1. . 1 gui d_t ype(p. 29) A universally unique message ID.
i nf o 1. . 1 i nf oType(p. 43) Event description.
data 0. . 1 Event type-specific data.
{
event dat a 1. . 1 event_dat aType
event _dat a 1. . 1 event_dat aType(p.40)
Depending on the event type,
the actual data type returned willbe one of the descendants of
event _dat aType(p. 40). Thedata type can be determined bycomparing the value of the
categoryelement (above) andthe event category described inthe descendants of
event _dat aType(p. 40).
}
Description:
-
8/13/2019 PVA Agent XML API Reference
42/736
42
Base Types and Interfaces
This structure is returned by the calls that provide information about system events and alerts. The
elements in the beginning of the structure are common to all event types and provide the basic
event information. The dataelement contains the event or alert type-specific data. Depending on
the type of the event or alert, the data type of the event _dat aelement will be one of the
descendants of event_dat aType(p. 40). Since you might not know in advance the type of theevent, you will have to determine the data type before you can parse the message and handle it
properly. Consider the following example.
Let's say that your client program receives an event Typestructure from Agent as a result of
subscription or an on-demand request. Let's also say that the cat egoryelement contains the"env_status" value. If you look at the event type definitions(p. 550), you'll see that "env_status" is
the category of the env_st atus_event _dat aType(note the env_st at usentry in the Eventtypesubsection). What this means is that in this particular XML response, the data type of the
event _dat aelement (see table above) is env_st at us_event _dat aType(p. 550), not the
base event _dat aTypeas shown in the table above.
groupType
Summary:
User group information structure.
Type specification:
Name Min/Max Type Description
user 0. . [ ] userType(p. 68) User info.
{
name 1. . 1 st r i ng User name.
}
member _gr oup 0. . [ ] groupType Member group info.
{
name 0. . 1 st r i ng Group name.
}
name 0. . 1 st r i ng Group name.
gi d 0. . 1 i nt Group ID.
-
8/13/2019 PVA Agent XML API Reference
43/736
43
Base Types and Interfaces
infoType
Summary:
The i nf oTypestructure is used as a generic container for name/value pairs, and for the textmessages that may require localization.
Type specification:
Name Min/Max Type Description
message 1. . 1 base64Bi nar y The original message in the officiallanguage of the developer.
The text may contain references to
parameters in the following format:%param_name%.
The parameter name always begins
and ends with a percent sign. Thevalues of the parameters are not
included in this element but supplied in
the paramet er element.
t ransl at e 0. . 1 none If present, indicates that the messagecontains words in a natural languageand, as such, may require a
translation to the language of the user.
paramet er 0. . [ ] i nf oType(p. 43) The values of the parameters specifiedin the messageelement.
The value is linked to the parameter
using the nameelement in such a way
that the value of the nameelement ofthis structure will be the same as thename of the parameter
(%param_name%) in the messageelement (see example below).
The parameter may also be used as asimple name/value container.
name 1. . 1 s t r i ng Parameter name.
Example:
T3Bl cmF0b3I gJ W9wZXJ hdG9yJ SBhdCAl ZWl kJ SBzdGFydGVk
ODQ5Yzl i ZTkt NWZi Yi 00ZTdkLWI xMDAtZj g0MWY4NmMxNTBl ei d
dnphX2NvbmY=oper at or
-
8/13/2019 PVA Agent XML API Reference
44/736
44
Base Types and Interfaces
In order to decode the message above, you first have to decode the base64-encoded values that
the message contains. The following is the same message with the values decoded to plain text.
Operat or %oper at or % at %ei d% st ar t ed
849c9be9- 5f bb- 4e7d- b100- f 841f 86c150eei d
vzl _conf oper at or
To process this message, you have to take the following steps:
1 Check if the message possibly requires a translation to the language of the user of yourapplication. For that, you have to check if the t ransl at eelement is present in the packet. Inour case, the element is present (which makes sense because the message contains words in
a natural language, English in our example), so depending on the target locale, you might want
to translate the text portion of it.
2 The second step is to see if the message contains any parameters (the parameter names arepreceded by the percent sign %). If there are parameters in the packet, get their values by
matching a parameter name to the corresponding name in one of the par amet er elements
that follow the messageelement. In the packet listed above, the first parameter is
%operat or%and its name (operat or) is contained in the second (from the top) paramet er
element. The value of the parameter is contained in the paramet er / messageelement and is
vzl _conf. The next parameter (%ei d%) is processed in the same exact manner. If you
substitute the parameter references in the original message with their values now, the messagewill read as follows:
Operator vzl _conf at 849c9be9- 5f bb- 4e7d- b100- f 841f 86c150e st ar t ed.
So, the original message that we received essentially means that the vzl _confAgent operator
has been started on the server with the Server ID 849c9be9- 5f bb- 4e7d- b100-
f 841f 86c150e.
Sometimes the structure is used as a simple generic container for the name/value pairs. For
example, the following XML fragment contains information about a server from a backup archive.
As you can see, the messageelement in the beginning of the structure does not contain any value,
which means that the packet does not contain any message. The underlying parameters simplydescribe the different properties of a server such as hostname, IP address, operating system, etc.
-
8/13/2019 PVA Agent XML API Reference
45/736
45
Base Types and Interfaces
SG9zdC0xMDY=
host name
MTAuMTMwLj EuNg==i p
VGVzdC1WRTY=name
os
TGl udXg=pl at f or m
ODl l Mj c5Nj AtOTdi OC00Nj FmLTkwMmYt NTU3Yj Ri MTY3ODRi parent _ei d
interfaceType
Summary:
Describes a network interface.
Type specification:
Name Min/Max Type Description
name 1. . 1 s t r i ng Interface name.
bandwi dth 0. . 1 i nt Bandwidth.
t r ansf er 0. . 1 t r ansf erType(p.67)
Transfer rate.
i paddr ess 0. . 1 i p_t ype(p. 29) IP address.
f l ags 0. . 1 i nt Network adapter flags:
Bit 0 -- loopback flag.
Bit 1 -- no ARP flag.
-
8/13/2019 PVA Agent XML API Reference
46/736
46
Base Types and Interfaces
intervalType
Summary:
A basic date interval structure.
Type specification:
Name Min/Max Type Description
st ar t _t i me 1. . 1 datet i me_t ype(p. 28) Start time.
end_t i me 1. . 1 datet i me_t ype(p. 28) End time.
ip_addressType
Summary:
IP address and netmask.
Type specification:
Name Min/Max Type Description
i p 1. . 1 i p_t ype(p. 29) IP address.
net mask 0. . 1 i p_t ype(p. 29) Netmask.
-
8/13/2019 PVA Agent XML API Reference
47/736
-
8/13/2019 PVA Agent XML API Reference
48/736
48
Base Types and Interfaces
load_avg_statsType
Summary:
Contains load average statistics.
Type specification:
Name Min/Max Type Description
l 1 1. . 1 st at sType 1 minute Load Average values.
{
avg 0. . 1 l ong Average value.
mi n 0. . 1 l ong Minimum value.
max 0. . 1 l ong Maximum value.
cur 0. . 1 l ong Current value.}
l 2 0. . 1 st at sType 5 minute Load Average values.
{
avg 0. . 1 l ong Average value.
mi n 0. . 1 l ong Minimum value.
max 0. . 1 l ong Maximum value.
cur 0. . 1 l ong Current value.
}
l 3 0. . 1 st at sType 15 minute Load Average values.
{
avg 0. . 1 l ong Average value.
mi n 0. . 1 l ong Minimum value.
max 0. . 1 l ong Maximum value.
cur 0. . 1 l ong Current value.
}
-
8/13/2019 PVA Agent XML API Reference
49/736
49
Base Types and Interfaces
load_avgType
Summary:
Load average values.
Type specification:
Name Min/Max Type Description
l 1 1. . 1 doubl e 1 minute Load Average value.
l 2 0. . 1 doubl e 5 minute Load Average value.
l 3 0. . 1 doubl e 15 minute Load Average value.
log_options_baseTypeSummary:
Base type.
Type specification:
The type has no elements.
Subtypes:
l og_opt i onsType
l og_opt i onsType(p. 620)
log_optionsType
Summary:
The type for logging options.
Type specification:
Extends l og_opt i ons_baseType(p. 49)
The type has no additional elements.
-
8/13/2019 PVA Agent XML API Reference
50/736
50
Base Types and Interfaces
modType
Summary:
The modTypetype is used when modifying a user or a group. It is populated with the list of theuser/group attributes and the type of the modification to perform on them.
Type specification:
Extends named_l i st Type(p. 50)
Adds the following elements:
Name Min/Max Type Description
op 0. . 1 i nt Modification type:
0-- Add the specified attribute values (default).
1-- Delete the specified attribute values.
2-- Replace the existing attribute values with the valuesspecified. If an attribute has more than one value, all ofthose values will be removed and the new values will beused in their place.
named_listType
Summary:
Attribute name/value pair.
Type specification:
Name Min/Max Type Description
name 1. . 1 st r i ng Attribute name.
val ue 0. . [ ] base64Bi nar y Attribute value(s).
-
8/13/2019 PVA Agent XML API Reference
51/736
-
8/13/2019 PVA Agent XML API Reference
52/736
52
Base Types and Interfaces
net_classType
Summary:
Network class.
Type specification:
Name Min/Max Type Description
i d 0. . 1 st r i ng Class ID.
t r ansf er 0. . 1 t r ansf erType(p. 67) Transfer statistics.
-
8/13/2019 PVA Agent XML API Reference
53/736
53
Base Types and Interfaces
net_deviceType
Summary:
Holds a generic network device information. A networks device can be a network interface card, anetwork bridge, or a virtual local area network. The subtypes of this type extend it adding additional
functionality.
Type specification:
Name Min/Max Type Description
i d 0. . 1 st r i ng Device ID (e.g. interfacename eth0, eth1, br 2,
et c).
i p_addr ess 0. . [ ] i p_addr essType(p. 46) The list of IP addressesassigned to this device.
dhcp 0. . 1 none DHCP flag. If present, thedevice uses DHCP to receive
TCP/IP settings.
network_i d 0. . 1 base64Bi nar y The ID of the virtual networkthis device belongs to.
status 0. . 1 Network device status.
[ Denotes a choice betweenthe upand the downelements.
up 1. . 1 none The device is up (enabled).
down 1. . 1 none The device is down(disabled).
]
Subtypes:
net _ni cType(p. 54)
net _vet hType(p. 621)
net _vl anType(p. 364)
net _br i dgeType(p. 364)
-
8/13/2019 PVA Agent XML API Reference
54/736
54
Base Types and Interfaces
net_nicType
Summary:
Contains a physical network adapter information.
Type specification:
Extends net _devi ceType(p. 53)
Adds the following elements:
Name Min/Max Type Description
mac_address 0. . 1 st r i ng MAC address.
operator_functionalType
Summary:
Agent Operators are represented in the front-end API byinterfaces. Each interface provides
methods for accessing a corresponding operator functionality. Each interface is identified by an
XML element to be used in the XML request sent to Agent server. Each such element is derived
from type oper at or _f unct i onal Type. The type defines the basic input and outputparameters. Interfaces extend it with their own input and output parameters.
Type specification:
Name Min/Max Type Description
ok 1. . 1 This element is returned tothe client when a requestcompletes successfully butdoes not return any
information by definition.
error 1. . 1 This element is returnedwhen a request results infailure.
{
code 1. . 1 i nt Error code.
message 0. . 1 st r i ng Text message describing theerror.
}
-
8/13/2019 PVA Agent XML API Reference
55/736
55
Base Types and Interfaces
osType
Summary:
Contains the operating system information.
Type specification:
Name Min/Max Type Description
pl at f or m 0. . 1 s t r i ng OS platform (Windows, Linux, etc.).
name 1. . 1 s t r i ng OS name (Windows XP, Red Hat 9, etc.).
versi on 0. . 1 s t r i ng OS version.
kernel 0. . 1 s t r i ng Kernel ID.
-
8/13/2019 PVA Agent XML API Reference
56/736
56
Base Types and Interfaces
packageType
Summary:
A generic software package information. Agent supports different types of software packages,including different varieties of the Linux specific packages, and Virtuozzo Containers specific
packages. When the packageTypetype is used as an input parameter, use one of theappropriate subtypes depending on the type of the software package. When it is used as an
output, expect the appropriate subtype in the response packet.
Type specification:
Name Min/Max Type Description
name 1. . 1 st r i ng Package name.
summar y 0. . 1 st r i ng Summary description.
os 0. . 1 osType(p. 55) Target OS and platform.
descri pt i on 0. . 1 st r i ng Description.
arch 0. . 1 st r i ng Package architecture -- x86, x86_64,etc.
versi on 0. . 1 st r i ng Package version.
Subtypes:
package_l i nuxType(p. 399)
package_r pmType(p. 399)
package_debType(p. 399)
package_vzt empl at eType(p. 624)
package_st d_vzt empl at eType(p. 623)
-
8/13/2019 PVA Agent XML API Reference
57/736
57
Base Types and Interfaces
perf_dataType
Summary:
Contains data returned by the performance monitor.
Type specification:
Name Min/Max Type Description
ei d 1. . 1 ei d_t ype(p. 29) Server ID.
cl ass 0. . [ ] none A list of performance classes thatwere selected for monitoring.
{
name 1. . 1 s t r i ng Class name.
i nst ance 1. . [ ] none A list of class instances that were
selected for monitoring.
{
name 0. . 1 s t r i ng Instance name.
count er 1. . [ ] none A list of performance counters thatwere selected for monitoring.
{
name 1. . 1 s t r i ng Counter name.
val ue 1. . 1 per f _st at Type(p.58)
Values.
}
}
}
i nt er val 1. . 1 i nt er val Type(p. 46) The time interval over which the datawas collected.
-
8/13/2019 PVA Agent XML API Reference
58/736
58
Base Types and Interfaces
perf_statType
Summary:
Performance statistics.
Type specification:
Name Min/Max Type Description
cur 1. . 1 anySi mpl eType Current value.
avg 1. . 1 anySi mpl eType Average value.
max 1. . 1 anySi mpl eType Maximum value.
mi n 1. . 1 anySi mpl eType Minimum value.
processesType
Summary:
Contains information about system processes.
Type specification:
Name Min/Max Type Description
run 1. . 1 i nt Number of processes in a "running" state.
zombi e 1. . 1 i nt Number of processes in a "zombie" state.
sl eep 1. . 1 i nt Number of processes in a "sleep" state.
uni nt err upt 1. . 1 i nt Number of processes in a "uninterrupt"state.
st opped 1. . 1 i nt Number of processes in a "stopped" state.
total 1. . 1 i nt Total number of processes.
-
8/13/2019 PVA Agent XML API Reference
59/736
59
Base Types and Interfaces
ps_infoType
Summary:
Contains information about system processes.
Type specification:
Name Min/Max Type Description
process 1. . [ ] none Process information
{
pi d 1. . 1 i nt Process identifier (PID).
par am 0. . [ ] base64Bi nar y A list of process parameter values inthe order indicated by the list
contained in the par am_i d
element.}
par am_i d 1. . [ ] s t r i ng A list of the included processparameters in the order in which
their values appear in the par amelement.
qosType
Summary:
Contains QoS (quality of service) limits.
Type specification:
Name Min/Max Type Description
i d 1. . 1 st r i ng QoS counter ID.
sof t 0. . 1 l ong Soft limit.
har d 0. . 1 l ong Hard limit.
cur 0. . 1 l ong Current value.
-
8/13/2019 PVA Agent XML API Reference
60/736
60
Base Types and Interfaces
realmType
Summary:
The base type defining a Realm. A Realm is an authentication database containing ParallelsInfrastructure Management user and group information. Agent supports a number of different
databases, including operating system user registries and LDAP-compliant directories. Realm
definitions are stored in the Agent configuration and can be retrieved using the get _r eal m call(p.111).
Type specification:
Name Min/Max Type Description
i d 0. . 1 gui d_t ype(p.29)
Globally unique Realm ID. The ID isautomatically generated by Agent when a
Realm definition is added to the Agent
configuration. The ID is guaranteed to beunique across different computers andnetworks.
t ype 1. . 1 i nt Realm type:
0-- System Realm. This is the operatingsystem user registry on the Hardware Node.
1-- LDAP directory Realm. This is an LDAP-compliant directory such as AD or ADAM on
Windows, or OpenLDAP on Linux. Thedirectory can be located locally or anywhere
on the network.
1000-- Virtuozzo Container Realm. This is
the operating system user registry inside aVirtuozzo Container.
name 1. . 1 s t r i ng The name of the Realm (user defined).
bui l t i n 0. . 1 If present, indicates that this is a built-inRealm. A built-in Realms is a preinstalledauthentication database. It can be an LDAP
directory or an operating system user registry.Built-in Realms contain Parallels InfrastructureManagement authentication and authorizationinformation, including built-in security roles,
permissions, users, and groups used byVirtuozzo Tools.
Subtypes:
di r _r eal mType(p. 81)
-
8/13/2019 PVA Agent XML API Reference
61/736
61
Base Types and Interfaces
resourceType
Summary:
A generic type for specifying a resource information.
Type specification:
Name Min/Max Type Description
total 0. . 1 l ong Total units available.
used 0. . 1 l ong Number of units currently used.
f ree 0. . 1 l ong Number if units currently available.
avg 0. . 1 l ong Average usage.
mi n 0. . 1 l ong Minimum units used.
max 0. . 1 l ong Maximum units used.
sample_confType
Summary:
Sample configuration information.
Type specification:
Name Min/Max Type Description
i d 0. . 1 gui d_t ype(p. 29) Sample configuration ID.
name 1. . 1 st r i ng Sample configuration name.
comment 0. . 1 base64Bi nar y Comment.
env_conf i g 1. . 1 env_conf i gType(p. 37) Configuration parameters.
vt _ver si on 0. . 1 Virtualization technologyinformation.
{
pl at f or m 1. . 1 st r i ng Platform (WIndows, Linux,etc.).
ar chi t ecture 1. . 1 st r i ng Architecture.
vt_ t echnol ogy 1. . 1 st r i ng Virtualization technologyname.
}
-
8/13/2019 PVA Agent XML API Reference
62/736
62
Base Types and Interfaces
security_descriptorType
Summary:
Security descriptor.
Type specification:
Name Min/Max Type Description
owner 1. . 1 si dType(p. 30) Security ID of a security object owner. Theowner is the user that is always allowed to
control the DACL of the object.
group 1. . 1 si dType(p. 30) Group security ID. It is used as a way oftracking a group for each object providing
support for Linux permissions.
dacl 0. . 1 Discretionary Access Control List (DACL).
{
ace 0. . [ ] aceType(p. 31) Access control entry.
}
Description:
Each object protected by the Agent access control system must have a state associated with it to
track its security settings. This state is calledsecurity descriptor.
The discretionary access control list (DACL) contains a list of permissions granted or denied to
various users and groups. The owner of the object is always allowed to control the DACL contents.
The access control entry (ACE) is an individual record in a DACL. It includes the SID of a single user
or a group along with an access mask that specifies the permissions being granted or denied.
security_objectType
Summary:
Base type describing a security object. Implemented in descendants.
Type specification:
The type has no elements.
-
8/13/2019 PVA Agent XML API Reference
63/736
63
Base Types and Interfaces
statsType
Summary:
Holds QoS data.
Type specification:
Name Min/Max Type Description
avg 0. . 1 l ong Average value
mi n 0. . 1 l ong Minimum value
max 0. . 1 l ong Maximum value
total 0. . 1 l ong Total value
cur 0. . 1 l ong Current value
sof t 0. . 1 l ong Soft limithar d 0. . 1 l ong Hard limit
-
8/13/2019 PVA Agent XML API Reference
64/736
64
Base Types and Interfaces
sys_infoType
Summary:
System information.
Type specification:
Name Min/Max Type Description
l oad_avg 1. . 1 l oad_avgType(p. 49) Load averages
processes 1. . 1 processesType(p. 58) Processes statistics
cpu_l oad 1. . 1 cpu_l oadType(p. 35) CPU load statistics.
cpu_st ates 1. . 1 cpu_l oadType(p. 35) CPU load statistics (percentage).
users 1. . 1 i nt Number of users.
upt i me 1. . 1 l ong Uptime.
memor y 0. . 1 r esour ceType(p. 61) Memory statistics. Provided onlyfor Hardware Node.
{
total 0. . 1 l ong Total memory available
used 1. . 1 l ong Memory used.
}
swap 0. . 1 r esour ceType(p. 61) Swap statistics. Provided only forHardware Node.
{
total 0. . 1 l ong Total.
used 1. . 1 l ong Used.
}
-
8/13/2019 PVA Agent XML API Reference
65/736
65
Base Types and Interfaces
system_nodeType
Summary:
Contains computer access parameters.
Type specification:
Name Min/Max Type Description
address 1. . 1 IP address.
{
i p 1. . 1 i p_t ype(p. 29) IP address.
}
l ogi n 0. . 1 Login info.
{user 1. . 1 st r i ng User name.
password 1. . 1 base64Bi nar y Password.
}
-
8/13/2019 PVA Agent XML API Reference
66/736
66
Base Types and Interfaces
tokenType
Summary:
Security token.
Type specification:
Name Min/Max Type Description
user 1. . 1 si dType(p. 30) SID of the token owner.
groups 0. . 1 The list of SIDs of the groups towhich the token owner belongs.
{
si d 1. . [ ] si dType(p. 30) SIDs.
}
deny_onl y_si ds 0. . 1 The list of deny-only SIDs.
{
si d 1. . [ ] SIDs.
}
pri vi l eges 0. . 1 These fields are not currently used.
{
pr i vi l ege 1. . [ ] pr i vi l egeType(p.29)
}
sour ce 1. . 1 These fields are not currently used.
{
name 1. . 1 st r i ng
i d 1. . 1 gui d_t ype
}
-
8/13/2019 PVA Agent XML API Reference
67/736
-
8/13/2019 PVA Agent XML API Reference
68/736
68
Base Types and Interfaces
userType
Summary:
User information.
Type specification:
Name Min/Max Type Description
i ni t i al _group 0. . 1Initial group
{
name 0. . 1 st r i ng Group name
gi d 0. . 1 i nt Group ID
}
group 0. . [ ] Other groups.
{
name 0. . 1 st r i ng Group name.
gi d 0. . 1 i nt Group ID.
}
ui d 0. . 1 i nt User ID.
shel l 0. . 1 st r i ngShell.
passwor d 0. . 1 base64Bi nar y Password.
home_di r 0. . 1 st r i ng Home directory.
name 0. . 1 st r i ng User name.
comment 0. . 1 st r i ng Comment.
-
8/13/2019 PVA Agent XML API Reference
69/736
69
Base Types and Interfaces
venv_configType
Summary:
Virtual server configuration. Virtuozzo-specific structure is derived from this type and containsadditional parameters.
Type specification:
Extends env_conf i gType(p. 37)
Adds the following elements:
Name Min/Max Type Description
qos 0. . [ ] qosType(p. 59) QoS parameters.
Subtypes:
vzat : venv_conf i gType(p. 626)
voc_parameterType
Summary:
Contains an Agent vocabulary entry information.
Type specification:
Name Min/Max Type Descriptioni d 1. . 1 s t r i ng Vocabulary entry ID.
t ype 0. . 1 s t r i ng Data type (int, string, etc.)
mi n 0. . 1 s t r i ng Minimum possible value.
max 0. . 1 s t r i ng Maximum possible value.
l ong 0. . 1 s t r i ng Long description.
shor t 0. . 1 s t r i ng Short description.
category 0. . [ ] s t r i ng Category.
compl ex 0. . 1 s t r i ng Entry type-specific value. May havedifferent meaning for different types ofentries.
def aul t 0. . 1 s t r i ng Default value.
measur e 0. . 1 s t r i ng Units of measure.
data 0. . 1 Data (entry-type specific value).
-
8/13/2019 PVA Agent XML API Reference
70/736
70
Base Types and Interfaces
vocabularyType
Summary:
Contains the Agent vocabulary data.
Type specification:
Name Min/Max Type Description
name 1. . 1 s t r i ng The name of Agent plug-in thatthis vocabulary is describing.
paramet er 0. . [ ] voc_paramet erType(p.562)
The vocabulary parameters.
category 0. . [ ] voc_paramet erType(p.562)
The vocabulary categories.
vt_infoType
Summary:
Virtualization technology-specific read-only settings.
Type specification:
Name Min/Max Type Description
xs: any
vt_settingsType
Summary:
A base type defining virtualization technology-specific settings. See subtypes for implementations.
Type specification:
Name Min/Max Type Description
defaul t _sampl e_i d 0. . 1 gui d_t ype(p.29)
The default sample configuration ID.
Subtypes:
vzat . vt _set t i ngsType(p. 630)
-
8/13/2019 PVA Agent XML API Reference
71/736
71
Base Types and Interfaces
Interfaces
The material in this section describes the base Agent XML API interfaces. The terminterface, as weuse it, is somewhat similar to a class in object-oriented programming. We use interfaces to group
related data types (structures) and calls (methods). The data types and calls are defined using XML
Schema language (XSD). The body of an Agent XML request always begins with the name of an
interface followed by the name of a call. The rest of the request body is composed according to the
call specifications.
The base interfaces described in this chapter form a foundation for the Agent XML API and
currently provide functionality for the Hardware Node and Virtuozzo Containers management.
Some of the Virtuozzo-specific functionality exists as a plug-in consisting of additional interfaces,
some of which are derived from the base interfaces. Virtuozzo Containers plug-in is described in
theVirtuozzo Containers Types and Interfaceschapter(p. 619).
alertm
Purpose:
The al er t minterface allows the user to receive notifications on critical system events via e-mailand to retrieve the list of currently raised alerts.
-
8/13/2019 PVA Agent XML API Reference
72/736
72
Base Types and Interfaces
Types
resource_alertType
Summary:
Resource allocation alert data.
Type specification:
Extends al er t _dat aType(p. 32)
Adds the following elements:
Name Min/Max Type Description
ei d 0. . 1 ei d_t ype(p. 29) Server ID.
cl ass 1. . 1 st r i ng Performance class (seeperf _mon(p. 388) for more infoon this and the followingparameters).
i nst ance 1. . 1 st r i ng Class instance.
count er 1. . 1 st r i ng Performance counter.
cur 1. . 1 anySi mpl eType Current value.
har d 1. . 1 anySi mpl eType Hard value.
sof t 1. . 1 anySi mpl eType Soft value.
-
8/13/2019 PVA Agent XML API Reference
73/736
-
8/13/2019 PVA Agent XML API Reference
74/736
74
Base Types and Interfaces
get_alerts
Summary:
Returns current alert states for specified servers.
Request specification:
Name Min/Max Type Description
get _al ert s
{
ei d_ l i s t 0. . 1 ei d_l i stType(p. 36) Server list.
category 0. . 1 s t r i ng Categories of the alerts to return. Ifthis element is omitted, the call willreturn alerts of all known types. The
available alert categories are:
r esour ce_al er t ser ver _gr oup_al er t
env_t ype 0. . 1 s t r i ng Return alerts only for the servers ofthe specified type (generi c,
vi r t uozzo).
}
Returns:
Name Min/Max Type Description
al ert 0. . [ ] event Type(p. 41) Alert information.
Description:
A server may have multiple alerts of different types raised at any given time. You can use
subscriptions to receive alert notifications in real time (see subscr i be(p. 611) and
subscri be_al er t (p. 77)), or you can retrieve all alerts that are currently raised on any given
server using the get _al er t scall.
Example:
The following sample shows how to obtain states of alerts for the specified server(s).
Input
al ert m
ccc794ad- cc5d- 49f 2- 8d84- 6631263c81be
-
8/13/2019 PVA Agent XML API Reference
75/736
75
Base Types and Interfac
top related