PVA Agent XML API Reference

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.


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.


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


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


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


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


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/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.


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.


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.


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/


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


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:


status Device status,

[ Denotes a choice between the and the elements.

up 1. . 1 none Enabled.


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:


15/736

15

Reference Format

QWRt aW5pc3RyYXRvcg==00000000- 0000- 0000- 0000- 000000000000MXEydzNl


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.


17/736

17

Reference Format


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


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.


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.

}


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").


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.


23/736

23

Agent Messages

I'm a cookie holding some textoperator_name

Hosttarget_server_EID

session_id


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


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.


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


27/736

27


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.


28/736

28


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.


29/736

29


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


30/736

30


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.


31/736

31


aceType

Summary:

Access control entry.

Type specification:


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)


32/736

32


alert_dataType

Summary:

Contains alert information.

Type specification:

Extends event_dat aType(p. 40)

Adds the following elements:


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)


33/736

33


auth_nameType

Summary:

User login information.

Type specification:


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.


34/736

34


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)



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:



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.


35/736

35


cpu_loadType

Summary:

Contains CPU load values.

Type specification:


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:


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.


36/736

36


credentialType

Summary:

Describes the security attributes of a security principle.

Type specification:


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:


ei d 0. . [ ] ei d_t ype(p.29)

Server IDs.


37/736

37


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 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)


38/736

38


env_resourceType

Summary:

Contains a list of IP addresses allocated to a server.

Type specification:


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)





39/736

39


env_statusType

Summary:

Contains a server status information.

Type specification:


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:


par ent _ei d 1. . 1 ei d_t ype(p. 29) Parent 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.


40/736


41/736

41


eventType

Summary:

Contains a system event information.

Type specification:


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:


42/736

42


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:


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.

}


gi d 0. . 1 i nt Group ID.


43/736

43


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:


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


44/736

44


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.


45/736

45


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 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.


46/736

46


intervalType

Summary:

A basic date interval structure.

Type specification:


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:


i p 1. . 1 i p_t ype(p. 29) IP address.

net mask 0. . 1 i p_t ype(p. 29) Netmask.


47/736


48/736

48


load_avg_statsType

Summary:

Contains load average statistics.

Type specification:


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.}


{




cur 0. . 1 l ong Current value.

}


{





}


49/736

49


load_avgType

Summary:

Load average values.

Type specification:


l 1 1. . 1 doubl e 1 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.


50/736

50


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)



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 1. . 1 st r i ng Attribute name.

val ue 0. . [ ] base64Bi nar y Attribute value(s).


51/736


52/736

52


net_classType

Summary:

Network class.

Type specification:


i d 0. . 1 st r i ng Class ID.

t r ansf er 0. . 1 t r ansf erType(p. 67) Transfer statistics.


53/736

53


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:


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)


54/736

54


net_nicType

Summary:

Contains a physical network adapter information.

Type specification:

Extends net _devi ceType(p. 53)



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:


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.

}


55/736

55


osType

Summary:

Contains the operating system information.

Type specification:


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.


56/736

56


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 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)


57/736

57


perf_dataType

Summary:

Contains data returned by the performance monitor.

Type specification:



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.


58/736

58


perf_statType

Summary:

Performance statistics.

Type specification:


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:


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.


59/736

59


ps_infoType

Summary:

Contains information about system processes.

Type specification:


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:


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.



60/736

60


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:


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)


61/736

61


resourceType

Summary:

A generic type for specifying a resource information.

Type specification:


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:


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.

}


62/736

62


security_descriptorType

Summary:

Security descriptor.

Type specification:


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.


63/736

63


statsType

Summary:

Holds QoS data.

Type specification:


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


64/736

64


sys_infoType

Summary:

System information.

Type specification:


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.

}


65/736

65


system_nodeType

Summary:

Contains computer access parameters.

Type specification:


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.

}


66/736

66


tokenType

Summary:

Security token.

Type specification:


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

}


67/736


68/736

68


userType

Summary:

User information.

Type specification:


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.

{


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.


69/736

69


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)



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).


70/736

70


vocabularyType

Summary:

Contains the Agent vocabulary data.

Type specification:


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:


xs: any

vt_settingsType

Summary:

A base type defining virtualization technology-specific settings. See subtypes for implementations.

Type specification:


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)


71/736

71


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.


72/736

72


Types

resource_alertType

Summary:

Resource allocation alert data.

Type specification:

Extends al er t _dat aType(p. 32)




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.


73/736


74/736

74


get_alerts

Summary:

Returns current alert states for specified servers.

Request specification:


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:


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


75/736

75

Base Types and Interfac

Documents

PVA Agent XML API Reference