Parallels Virtual Automation - 6.1 User Guide

PVA Agent

XML API Reference

Parallels IP Holdings GmbH. c/o Parallels International Gm Parallels International GmbH Vordergasse 49 CH8200 Schaffhausen Switzerland Tel: + 41 526 Fax: + 41 52672 2010 www.parallels.com

his product is protected by United States and international copyright laws. The product’s underlying technology,

T patents, and trademarks are listed at http://www.parallels.com/trademarks.

icrosoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are registered trademarks of Microsoft

M Corporation. Apple, Mac, th Inc., registered in the US and other countries. Linux is a registered trademark of Linus Torvald All other marks and names mentioned herein may

320 411

e Mac logo, Mac OS, iPad, iPhone, iPod touch, FaceTime HD camera and iSight are trademarks of Apple

bH.

be trademarks of their respective owners.

Contents

Preface....................................................................................................................... 6

About This Guide .............................................................................................................. 6

Who Should Read This Guide ...........................................................................................6

Organization of This Guide ................................................................................................ 7

How to Use This Guide ..................................................................................................... 8

Documentation Conventions ............................................................................................. 8

Typographical Conventions ..................................................................................................... 9

Shell Prompts in Command Examples................................................................................... 10

General Conventions .............................................................................................................10

Feedback........................................................................................................................11

Reference Format....................................................................................................12

XML Message Specifications........................................................................................... 13

XML Code Samples ........................................................................................................ 16

Agent Messages......................................................................................................18

Message Header............................................................................................................. 19

Message Body................................................................................................................ 24

Base Types and Interfaces .....................................................................................26

Common Types ..............................................................................................................26

Primitive Types ...................................................................................................................... 27

Simple Types......................................................................................................................... 27

Complex Types ..................................................................................................................... 30

Interfaces ........................................................................................................................ 72

alertm .................................................................................................................................... 72

authm.................................................................................................................................... 81

backup_storagem ............................................................................................................... 120

backupm............................................................................................................................. 120

server_group ....................................................................................................................... 161

computerm.......................................................................................................................... 177

data_storagem .................................................................................................................... 195

devm ................................................................................................................................... 198

Contents

sample_manager................................................................................................................. 232

envm ................................................................................................................................... 237

event_log............................................................................................................................. 275

filer ...................................................................................................................................... 280

firewallm .............................................................................................................................. 306

licensem.............................................................................................................................. 315

mailer .................................................................................................................................. 331

relocator .............................................................................................................................. 340

networkm ............................................................................................................................ 364

op_log ................................................................................................................................. 384

perf_mon............................................................................................................................. 389

packagem ........................................................................................................................... 399

proc_info ............................................................................................................................. 436

processm ............................................................................................................................ 445

res_log ................................................................................................................................ 452

ip_poolm ............................................................................................................................. 465

scheduler ............................................................................................................................ 478

servicem.............................................................................................................................. 495

sessionm............................................................................................................................. 506

userm.................................................................................................................................. 524

Events........................................................................................................................... 551

Types .................................................................................................................................. 551

Elements ............................................................................................................................. 553

System Interface and Special Packets........................................................................... 562

system................................................................................................................................. 562

The progress packet ........................................................................................................... 616

Container (CT) Types and Interfaces ....................................................................620

Common Types ............................................................................................................620

Simple Types....................................................................................................................... 620

Complex Types ................................................................................................................... 621

Interfaces ...................................................................................................................... 632

vzadevm.............................................................................................................................. 632

vzaenvm.............................................................................................................................. 633

vzarelocator......................................................................................................................... 658

vzanetworkm....................................................................................................................... 661

Contents

vzapackagem ...................................................................................................................... 668

vzaproc_info........................................................................................................................ 669

vzaprocessm....................................................................................................................... 676

vzaup2date ......................................................................................................................... 678

vzasupport .......................................................................................................................... 685

Virtual Machine (VM) Types and Interfaces ..........................................................694

Common Types ............................................................................................................694

Complex Types ................................................................................................................... 694

Interfaces ...................................................................................................................... 716

vzpenvm.............................................................................................................................. 716

vzpdevm.............................................................................................................................. 724

vzpnetworkm....................................................................................................................... 726

vzprelocator......................................................................................................................... 727

vzpsample_manager ........................................................................................................... 728

Appendix A: Performance Counters .....................................................................732

Appendix B: States and Transitions .....................................................................742

Appendix C: Error Codes ......................................................................................744

Index ......................................................................................................................759

C HAPTER 1

Preface

In This Chapter

About This Guide ..................................................................................................... 6

Who Should Read This Guide................................................................................... 6

Organization of This Guide ....................................................................................... 7

How to Use This Guide............................................................................................. 8

Documentation Conventions .................................................................................... 8

Feedback ................................................................................................................. 11

About This Guide

This guide is a complete Parallels Agent XML API reference. The XML API consists of interfaces to the Parallels Virtuozzo Containers, Parallels Cloud Server, Parallels Server Bare Metal, and Parallels Server for Mac management functions. An interface provides calls (similar to functions or methods in traditional programming languages) that allow to interact with the Virtuozzo Containers software, Parallels Cloud Server, Parallels Server Bare Metal, and Parallels Server for Mac on the server side. Using the XML API, you can build reliable tools for remote management and monitoring of the physical servers and virtual environments.

Who Should Read This Guide

This guide is intended for the developers who are writing their own Parallels Agent applications using XML API. This guide should also be used by the developers using Parallels Agent SOAP API. The proxy classes that you will generate using Parallels Agent WSDL specifications will have the same basic structure as the interfaces and calls described in this guide. By examining an XML API documentation, you can get a clear understanding of how to use a corresponding method of a proxy class in your SOAP-based application.

Preface

Organization of This Guide

This guide is organized into the following chapters:

Chapter 1, Preface. Provides information about this guide.

Chapter 2, Reference Format. Explains how to use the specifications presented in this guide.

Chapter 3, Agent Messages. Provides a description of the Parallels Agent XML message

structure.

Chapter 4, Base Types and Interfaces. Describes the base data types and interfaces. The chapter is divided into sections. The Common Types section (p. 26) describes the base data types that are used throughout the API. The Interfaces section (p. 72) describes the base interfaces and the available API calls. Each API call documentation consists of the XML request and response specifications, the description of the parameters, and one or more XML code samples.

Chapter 5, Virtuozzo Containers Types and Interfaces. This chapter is organized similarly to the Base Types and Interfaces chapter but describes the types and interfaces that are specific to the

Virtuozzo Containers management only. Some of these interfaces and types are derived from the base interfaces and types. If a call is not overridden in the derived interface, it will be documented in the base interface only. However, the Virtuozzo Containers specifics will still be documented and the appropriate examples will be provided.

Chapter 5, Parallels Server Types and Interfaces. This chapter describes the types and interfaces that are specific to the Parallels Server virtual machiens management only. Some of these interfaces and types are derived from the base interfaces and types.

Appendix A: Performance Counters. Provides a complete list of the available performance classes and counters which are used for performance monitoring.

Appendix B: States and Transitions. Provides a complete list of the available server states and transitions.

Appendix C: Error Codes. Provides a complete list of the Parallels Agent error codes, grouped by the interface or the category to which they apply.

Preface

How to Use This Guide

You don't have to read the entire XML reference guide from cover to cover, but you should read at least the Preface chapter (you are reading it now), the Reference Format chapter, and the Agent Messages chapter. The information provided in these chapters is essential to understanding the rest of the reference material. To get a better understanding of Parallels Agent and to learn how to write your own client programs using the provided API, you should also read the Parallels Agent Programmer's Guide which is a companion book to this one.

Each XML API interface provides calls to perform operations of a particular type. For example, the vzaenvm interface (p. 633) allows you to manage Virtuozzo Containers, the perf_mon interface (p. 389) allows you to monitor the performance of a Virtuozzo Container or the Hardware Node, etc. In this respect, the interfaces in the Agent XML API are similar to classes in traditional OOP languages, and the calls are similar to methods. The names of the interfaces are abbreviations based on the name of the functionality that they provide. For example, vzaenvm and vzpenvm stands for Virtuozzo Containers and Parallels virtual machine management, respectively; perf_mon stands for Performance Monitoring, etc. To find the specifications for a particular operation, browse the Interfaces sections of the Base Types and Interfaces chapter or the Virtuozzo Containers Types and Interfaces and Parallels Server Types and Interfaces chapter. Find the interface that interests you and read the introductory section which gives a brief description about the functionality that the interface provides. After that, proceed to the Calls subsection which lists the available calls that the interface provides. Select the call that interests you and proceed to the subsection describing it. In the subsection, you will find the request specifications, the response specifications, the description of the call, and an XML code sample. This should provide you with enough information to use the call in your client application to perform the desired operation. You may also search the guide using keywords.

Documentation Conventions

Before you start using this guide, it is important to understand the documentation conventions used in it.

Formatting conventions used in this guide:

Font Meaning Example

Special Bold

Selectable entities such as menu options, buttons, or list items.

Titles of chapters, sections and subsections.

Go to the Resources tab.

Read the Basic Administration chapter.

Preface

Italics

Monospace

Preformatted

Preformatted Bold

Key+Key Key combinations. Ctrl+P, Alt+F4

Important points, terms, guide titles, command variables.

Names of commands, files, and directories.

On-screen console output in command line sessions, source code.

What you type as contrasted with on-screen console output.

These are the so-called EZ templates. To destroy a Container, type vzctl

destroy CT_ID. Use vzctl start to start a Container.

Saves parameters for Container 101

# rpm -V virtuozzo-release

Besides the formatting conventions, you should also know about the common document structure shared by all guides for Parallels products: chapters consist of sections, which, in turn, consist of subsections. For example, About This Guide is a section, and Documentation Conventions is a subsection.

Typographical Conventions

The following kinds of formatting in the text identify special information.

Formatting convention

Type of Information Example

Triangular Bullet(¾) Step-by-step procedures. You can follow

the instructions below to complete a specific task.

Special Bold

Items you must select, such as menu options, command buttons, or items in a list.

Titles of chapters, sections, and subsections.

To create a Container:

Go to the Resources tab.

Read the Basic Administration chapter.

Preface

Italics

Monospace

Preformatted

Monospace Bold

CAPITALS Names of keys on the keyboard. SHIFT, CTRL, ALT

KEY+KEY Key combinations for which the user must

Used to emphasize the importance of a point, to introduce a term or to designate a command line placeholder, which is to be replaced with a real name or value.

The names of commands, files, and directories.

On-screen computer output in your command-line sessions; source code in XML, C++, or other programming languages.

What you type, contrasted with on-screen computer output.

press and hold down one key and then press another.

These are the so-called EZ templates. To destroy a Conainer, type vzctl destroy

ctid.

Use vzctl start to start a Container.

Saved parameters for Container 101

# rpm –V virtuozzo-release

CTRL+P, ALT+F4

Shell Prompts in Command Examples

Command line examples throughout this guide presume that you are using the Bourne-again shell (bash). Whenever a command can be run as a regular user, we will display it with a dollar sign prompt. When a command is meant to be run as root, we will display it with a hash mark prompt:

Bourne-again shell prompt

Bourne-again shell root prompt

General Conventions

Be aware of the following conventions used in this book.

• Chapters in this guide are divided into sections, which, in turn, are subdivided into subsections.

For example, Documentation Conventions is a section, and General Conventions is a subsection.

• When following steps or using examples, be sure to type double-quotes ("), left single-quotes

(`), and right single-quotes (') exactly as shown.

• The key referred to as RETURN is labeled ENTER on some keyboards. The root path usually includes the /bin, /sbin, /usr/bin and /usr/sbin directories, so the

steps in this book show the commands in these directories without absolute path names. Steps that use commands in other, less common, directories show the absolute paths in the examples.

Preface

Feedback

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

C HAPTER 2

Reference Format

This chapter explains how to use the specifications presented in this guide.

In This Chapter

XML Message Specifications .................................................................................... 13

XML Code Samples ................................................................................................. 16

Reference Format

XML Message Specifications

The XML message specifications in this guide are described using tables, similar to the following example:

Name Min/Max Type Description

login { name 0..1 base64Binary domain 0..1 base64Binary realm 1..1 guid_type password 0..1 base64Binary expiration 0..1 int }

The information in a table is based on a corresponding XML Schema and describes the format of a request or response message, or the format of a data type.

User name.

Domain.

Realm ID.

User password.

Custom timeout value.

Each row in a table represents an XML element. The elements are displayed in the order they are defined in the XML Schema.

The definitions for the table columns are as follows:

Name. Specifies an XML element name. The curly brackets represent the standard XML Schema xs:sequence element. This means that the elements inside the brackets are the child elements of the element that precedes the opening bracket. In our example, the name, domain, realm, password, and expiration elements are children of the login element. The following is a sample XML code, built according to this specification:

<login> <name>bXluYW1l</name> <domain>bXlkb21haW4=</domain> <realm>bXlyZWFsbQ==</realm> <password>bXlwYXNz</password> <expiration>1000</expiration> </login>

In addition, we use square brackets to represent the standard XML Schema xs:choice element, as shown in the following example:

Name Min/Max Type Description

status [

up 1..1 none

Device status,

Denotes a choice between the <up> and the <down> elements.

Enabled.

Reference Format

down 1..1 none ]

This means that the elements inside the brackets are the child elements of the element that precedes the opening bracket but the elements are mutually exclusive -- only one of them can be present in the request.

Disabled.

Min/Max. Specifies the cardinality of an element (the number of its minimum and maximum occurrences) in the following format:

minOccurs..maxOccurs

• 0 in the first position indicates that the element is optional.

• 1 in the first position indicates that the element is mandatory and must occur at least once.

• A number in the second position indicates the maximum number of occurrences.

• The [] (square brackets) in the second position indicate that the number of the element

occurrences is unbounded, meaning that the element may occur as many times as necessary in the same XML document at the specified position.

The following examples demonstrate how an element cardinality may be specified:

• 0..1 The element is optional and may occur only once if included in the document.

• 1..1 The element is mandatory. One, and only one, occurrence is expected in the

document.

• 0..[] The element is optional but may occur an unlimited number of times if needed.

• 1..[] The element is mandatory. At least one occurrence is expected but the element may

occur an unlimited number of times if needed.

Type. Specifies the element type. The following element types are used in the schema:

• Standard simple types: int, string, base64Binary, etc.

• Custom simple types. These types are usually derived from standard simple types with

additional restrictions imposed on them.

• Custom complex types.

Description. The description column contains the element description and provides information about its usage.

Let's now use the schema example from the beginning of this section and build the Agent request message from it. We already built the message body from it earlier. To make it a fully qualified Agent request message, we must also add the interface name to it and the message header. The following example is a complete Agent message that can be sent to the Agent and be processed by it:

<?xml version="1.0" encoding="utf-8"?> <packet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/types" version="4.0.0" id="2"> <data> <system>

<login xsi:type="ns2:auth_nameType"> <name>QWRtaW5pc3RyYXRvcg==</name> <realm>00000000-0000-0000-0000-000000000000</realm> <password>MXEydzNl</password> </login> </system> </data> </packet>

Reference Format

XML Code Samples

Most of the XML API call descriptions have one or more XML code samples. The samples are provided at the end of the section describing a call. You may copy an entire example and paste it into your program to quick-test the call. More than one samples may be provided for calls where different invocation scenarios must be considered. Please note that some values used in the samples may not be suitable for your particular situation and must be substituted with the values appropriate to your setup. The following is a typical XML code sample:

Example:

Retrieving Parallels Agent version number.

Input

Output

<packet id="2c446af2aet18be" time="2006-05-17T09:54:00+0000" priority="0" version="4.0.0"> <session>vzl.30100.ba7be334-4804-4494-a9c8-15149a0438a5.8c446ae612t2cd6</session> <target>vzclient4</target> <dst> <director>gend</director> </dst> <data> <system> <version>pvaagent-4.0.0</version> </system> </data> <src> <director>gend</director> </src> </packet>

The Input section contains a complete XML response message built according to the schema definition.

The Output section contains the actual response message received from Agent.

Note: Some of the elements and attributes common to all response messages will be omitted from the

Output examples for brevity. These attributes and elements may include time, priority from the <packet> element, and <session>, <target>, <dst>, <src> from the message header, and

possibly some other elements and attributes that are not essential to a particular example. The <data> element containing the output data will be included in its entirety, unless noted otherwise in the example itself.

Reference Format

C HAPTER 3

Agent Messages

In order to build XML messages correctly and to take full advantage of the available options, it is important to understand the basic building blocks of a message. This section describes how an Agent message is organized, and provides the necessary specifications and examples.

In This Chapter

Message Header ...................................................................................................... 19

Message Body ......................................................................................................... 24

Agent Messages

Message Header

The two main sections of any Agent XML message is the header and the body. The header provides message routing and control information. The body of the message contains the actual request (or response) parameters and data. The packet element is the root element of every message. Both the header and the body of a message reside within the same parent packet element.

The following table contains the Agent message header specification, as defined in XML Schema.

Message header specification:

Name Min..Max Type Description

packet { cookie 0..1 string

target 0..[] string

The root element of an Agent XML message.

User-defined information describing the message, or any other type of information. The data specified here remains unchanged during the request/response operation, i.e. if you put some data into this element in the request message, the response message will contain the same data.

In request messages, this element must contain the name of the operator to which the request should be sent for processing.

origin 0..1 string

Note: When using the system operator, do not include the target element. The system operator is the only exception. All other operators require this element.

The name of the operator is always the same as the name of the corresponding interface that you are using. For example, if you are using a call from the vzaenvm interface, the name of the target operator is also vzaenvm.

Multiple targets may be specified if you are including multiple calls in a single request.

In response messages, this element contains the name of the client that originated the request (the value is generated and used internally by Agent).

The name of the operator that generated the response. Included in response messages only.

Agent Messages

src 0..1 routeType

{ director 0..1 string

host 0..1 string

index 0..1 string

target 0..1 string

} dst

routeType

The source routing information. This field is automatically populated by the director on the server side when a message is routed from the corresponding operator to it. The same information is also duplicated in the dst element (described below) when a response is generated and is sent back to the client.

The name of the director to which the target operator belongs.

The Agent host ID. Used by Agent to determine the host address. Should be either contained in the Agent configuration (global mapping) or be a result of exclusive connect.

For on-demand operators, specifies a particular target.

Contains the origin information when a packet is sent remotely.

The destination routing information.

In request messages, use this structure to specify the server to which you want to forward the request. For example, if you are sending a request to the Agent on the host server but would like the request to be processed inside a virtual environments, specify the EID for the virtual environment using the dst/host parameter.

{ director 0..1 string

host 0..1 string

index 0..1 string

target 0..1 string

}

In the response messages, this information is automatically populated by the director on the server side.

The name of the director to which the target operator belongs. Populated automatically by the director.

Destination server EID. When using the message forwarding feature, it is used for specifying the ID of the target server.

For on-demand operators, specifies a particular target. Populated automatically by the director.

Contains the origin information when a packet is sent remotely. Populated automatically by Agent.

Agent Messages

session

}

string

Session ID.

In the request messages, this field is used to specify the session that should be used to process the request.

In the response messages, the ID indicates the session that was used to process the request.

The session ID is obtained from the response message of the system/login (p. 606) API call after a successful login.

The packet element may optionally contain attributes described in the following table.

Attributes of the <packet> element:

Attribute Type Description

version string

Parallels Agent protocol version number. The current protocol version number is

4.0.0. The older 3.0.3 protocol is also supported in Virtuozzo Containers 4.0.

id string

Packet ID. If included in a request message, the response will contain the same ID. This allows the response to be correlated with the original request. The attribute must also be included if you want to be notified in case of the request timeout, or if the packet was dropped on the server side for any reason. As a rule of thumb, you should always include this element in all of your outgoing packets.

The value should normally be a string containing an integer value, but it can also contain other characters if needed.

Agent Messages

priority string

time datetime_type

progress string

Specifies the packet priority in the message queue. The lower the number, the higher the queue priority level for the packet, the sooner it is selected from the queue to run.The default value is 0 (zero).

Packets are placed into queue priority pools defined by priority value intervals:

• -10000 or smaller — emergency

messages.

• -10000 to -2000 — urgent messages.

• -2000 to 2000 — normal messages.

• 2000 or greater — heavy messages

(tasks that take a long time to complete, such as a backup operation).

Each priority pool has a timeout value associated with it. Therefore, by specifying the queue priority for a packet, you are also specifying the timeout value for it.

The time when the packet was sent; in the ISO-8601 format: (e.g. "2007-02-04T08:55:51+0000").

Use this attribute to enable the progress reporting for long operations if you would like to receive intermediate results and to keep track of the request processing. Please note that not all operations actually generate progress reports.

The possible values are:

on -- the progress reporting is on.

log string

off (default if the attribute is omitted) -- the progress reporting is off.

When you turn the progress reporting on, you must also include the id attribute (above) specifying the message ID.

When present, the automatic progress reporting is logged for the operations supporting it. Switch this to “on” if you're planning to start an operation and disconnect from Agent before the operation is completed. By doing so, you'll be able to reconnect later and check the log files for the results of your operation.

The requests marked as Logged Operation in the XML API Reference support this feature.

Possible values are:

on -- the logging is turned on. off (default) -- the logging is off.

Agent Messages

type int

timeout int

timeout_limit int

uid int

*** INTERNAL ***

Bit field for the internal type of the message.

#define UNFINISHED 0x00000001

#define RESPONSE 0x00000002

#define RESCHEDULE 0x00000004

#define TIMEOUT 0x00000008

The timeout value which will be used for handling this request. The value can be specified in the incoming packet or it can be sent back from the operator, notifying the director about the time it is going to handle it. The value is set in seconds.

*** INTERNAL ***

Timeout limit for message processing. Used by an operator in determining the validity of its timeout.

*** INTERNAL ***

UID of the user sending this packet.

Example:

The following is an example of an Agent message header, built according to the specifications above. In a real message, the values of the XML elements would be substituted with the appropriate names, IDs, etc.

<packet version="4.0.0" id="500"> <cookie>I'm a cookie holding some text</cookie> <target>operator_name</target> <dst> Hosttarget_server_EID</host> </dst> <session>session_id</session> </packet>

Agent Messages

Message Body

Message body contains the actual request or response parameters and data. The data element is the root element of the message body tree. It is followed by the name of the interface that you would like to use, the name of the call, and the call parameters.

Note: There must be one and only one data element in any given message.

The request message:

The following XML code example is a complete Agent request message. As you already know, the packet element is the root element of every Agent message. The target element specifies the name of the target operator. The message body begins with the data element. The envm element specifies the name of the interface. The available interfaces are documented in the Parallels Agent XML API Reference documentation. The get_info element is the name of the call. The config element specifies that the information about the host configuration is requested.

The response message:

The following example demonstrates a complete response message. The body of the message begins with the data element which is followed by the name of the interface that was used in the corresponding request message, and the return parameters.

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/envm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="ac49b7e2c8t6784r580" time="2009-03-11T16:09:33+0000"> <ns1:origin>envm</ns1:origin> <ns1:target>vzclient4-b1e6bc1e-4231-b541-819a-191cd7fec5fb</ns1:target> <ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:envm> <ns2:env xsi:type="ns3:envType"> <ns3:parent_eid>00000000-0000-0000-0000-000000000000</ns3:parent_eid> <ns3:eid>b1e6bc1e-4231-b541-819a-191cd7fec5fb</ns3:eid> <ns3:status xsi:type="ns3:env_statusType"> <ns3:state>6</ns3:state> </ns3:status>

Agent Messages

<ns3:alert>0</ns3:alert> <ns3:config xsi:type="ns3:env_configType"> <ns3:name>mccp40.qa.sw.ru</ns3:name> <ns3:hostname>mccp40.qa.sw.ru</ns3:hostname> <ns3:address> <ns3:ip>10.27.1.174</ns3:ip> </ns3:address> <ns3:address> <ns3:ip>10.37.130.2</ns3:ip> </ns3:address> <ns3:address> <ns3:ip>10.37.131.2</ns3:ip> </ns3:address> <ns3:architecture>x86_64</ns3:architecture> <ns3:os xsi:type="ns3:osType"> <ns3:platform>Linux</ns3:platform> <ns3:kernel>2.6.18-028stab061.6</ns3:kernel> <ns3:name>Parallels Server Bare Metal 5.0</ns3:name> </ns3:os> <ns3:type>generic</ns3:type> <ns3:nameserver>10.27.0.1</ns3:nameserver> <ns3:child_type>parallels</ns3:child_type> <ns3:child_type>virtuozzo</ns3:child_type> </ns3:config> <ns3:virtual_config xsi:type="ns3:venv_configType"/> </ns2:env> </ns2:envm> </ns1:data> <src> <director>gend</director> </src> </packet>

The body of a response message may, in general, contain one of the following types of information:

• The actual information requested, as shown in the example above.

• The <OK/> element if the call doesn't return any data by definition. The <OK/> means that the

operation completed successfully.

• An error information, in case of a failure.

A complete XML Schema specification exists for every possible response of every Agent XML API call, and is described in the corresponding section of the Parallels Agent XML API Reference guide.

C HAPTER 4

Base Types and Interfaces

This chapter describes the base XML API types and interfaces. They can be used to perform operations on physical servers (Hardware Nodes),virtual machines, and Virtuozzo Containers. In addition, the Virtuozzo Containers Types and Interfaces chapter (p. 620) contains specifications of the types and interfaces that are specific to the Virtuozzo Containers only; the Parallels Server

Types and Interfaces chapter (p. 694) contains specifications of the types and interfaces that are

specific to virtual machines only.

In This Chapter

Common Types........................................................................................................ 26

Interfaces ................................................................................................................. 72

Events ...................................................................................................................... 551

System Interface and Special Packets...................................................................... 562

Common Types

This chapter describes the common data types. There are three main categories of common types:

• Primitive Types are the most basic data types. These are built-in types, which are defined in the

W3C XML Schema Data Types specification.

• Simple Types are custom types that are usually derived from primitive types with additional

restrictions imposed on them.

• Complex Types are custom types that can contain attributes and elements.

Each category is described in detail in the following sections.

Base Types and Interfaces

Primitive Types

Primitive types are the basic building blocks of an XML Schema. The following table describes the most common primitive types used in the Agent XML Schema.

Name Description

boolean

int long double string base64Binary

Boolean type. Legal values for boolean are true, false, 1 (which indicates true), and 0 (which indicates false).

A signed 32-bit integer.

A signed 64-bit integer

A 64-bit floating point.

A string. Note that unlike char arrays in C, XML strings are NOT null-terminated.

Base64-encoded binary data.

Simple Types

Simple types are custom types that can contain a value but cannot contain attributes or elements. Most of the custom simple types have restrictions added to them in order to limit their content. A restriction can limit the type to a specific primitive data type, it can also define a list of enumerated values, or it can define a string pattern that the value must adhere to.

Base Types and Interfaces

datetime_type

Summary:

Holds a datetime value.

Type specification:

datetime_type is derived from string

The type complies with ISO-8601, the International Standard for the representation of dates and times. The format is as follows.

YYYY-MM-DDThh:mm:ssZ

where:

YYYY -- four-digit year.

MM -- two-digit month (01 = January, etc.).

DD -- two-digit day of month (01 through 31).

The letter T in DDThh must literally be present to indicate the beginning of the time element.

hh -- two digits of hour (00 through 23, am/pm is NOT allowed).

mm -- two digits of minute (00 through 59).

ss -- two digits of second (00 through 59).

Z -- GMT/UTC offset (+hhmm or -hhmm).

Example:

2006-05-28T19:05:30-0500 corresponds to May 28, 2006, 19:05:30 (or 7:05:30 pm), US Eastern Standard Time.

Base Types and Interfaces

eid_type

Summary:

Holds a Server ID value. Server ID is a globally unique identifier that is assigned to every computer (physical or virtual) that has Parallels Agent installed on it. The ID is assigned to a physical server as soon as Parallels Virtual Automation software is installed on it. The ID is assigned to a virtual environment at the time of creation.

Type specification:

Restriction: guid_type (p. 29)

guid_type

Summary:

A globally unique identifier.

Type specification:

guid_type is derived from string

ip_type

Summary:

IP (Internet Protocol) address expressed as four decimal numbers separated by periods, such as

192.168.1.10

Type specification:

ip_type is derived from string

privilegeType

Summary:

A security privilege identification.

Type specification:

Restriction: string

Base Types and Interfaces

sidType

Summary:

Security ID.

Type specification:

Restriction: base64Binary

transport_type

Summary:

Transport type enumeration.

Type specification:

The enumeration has the following enumerators:

TCP -- Transmission Control Protocol.

UDP -- User Datagram Protocol.

Complex Types

Complex types are custom types that can contain text, attributes and other elements. This section describes the types that are common to the entire Parallels Agent XML API.

Base Types and Interfaces

aceType

Summary:

Access control entry.

Type specification:

Name Min/Max Type Description

type 1..1 int

sid 1..1 rights 1..1 base64Binary

sidType (p. 30)

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.

Type of ACE:

0 -- allow 1 -- deny

Security identifier of a user or a group.

Access rights.

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 rights parameter is not currently used. Simply include an empty rights element when setting permissions.

alert_dataType

Summary:

Contains alert information.

Type specification:

Extends event_dataType (p. 40)

Adds the following elements:

Name Min/Max Type Description

type 1..1 int

Description:

0 -- green alert. 1 -- yellow alert. 2 -- red alert.

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 alert_dataType are used to handle different alert categories, such as resource allocation alerts and cluster-wide alerts.

Subtypes:

resource_alertType (p. 73)

server_group_alertType (p. 74)

auth_nameType

Summary:

User login information.

Type specification:

Name Min/Max Type Description

name 0..1 base64Binary

domain 0..1 base64Binary

realm 1..1

guid_type (p. 29)

The name of a user or a group.

When working with LDAP directory entries, the name can be specified as a fully qualified distinguished name or as a plain name (as in "John" for instance). If the name contains a full DN then the entry is assumed to be located in the container specified. If the name is a plain name (as in "John" for instance), the entry is assumed to be located in the default container for users and groups for this realm. To find out what the default DN is, use the

get_realm call (p. 112).

Domain name. Currently, this filed is only used to specify the Server ID (eid) when logging into Agent as a user from the Virtuozzo Container Realm (the OS user registry inside the Container).

Realm ID. When adding a user or a group to a realm, specify the target realm ID here.

Base Types and Interfaces

connection_infoType

Summary:

Contains parameters necessary to connect to a remote computer.

Type specification:

Extends connectivity_infoType (p. 34)

Adds the following elements:

Name Min/Max Type Description

auth_nameType (p. 33)

Password.

connectivity_infoType

Summary:

Contains the network connectivity information.

Type specification:

Adds the following elements:

Name Min/Max Type Description

protocol 0..1 string

address 1..1 string port 0..1 unsignedInt

Communication protocol:

SSL -- SSL over TCP/IP. TCP -- plain TCP/IP.

NamedPipe -- named pipe.

IP address.

Port number.

cpu_loadType

Summary:

Contains CPU load values.

Type specification:

Name Min/Max Type Description

system 1..1 long user 1..1 long nice 1..1 long idle 1..1 long

CPU used by system processes.

CPU used by user processes.

CPU used by "nice" processes.

CPU idle.

cpuType

Summary:

Base Types and Interfaces

Contains common CPU characteristics.

Type specification:

Name Min/Max Type Description

mhz 1..1 int name 1..1 string number 1..1 int cores 1..1 int hyperthreads 1..1 int

units 1..1 int family 1..1 string model 1..1 string bogomips 1..1 int

CPU Frequency, in MegaHertz.

CPU name.

Number of CPUs in the system.

Number of cores per CPU.

Number of hyper-threads per CPU core. The value of 1 indicates that no hyperthreading is available.

CPU unit value.

CPU family.

CPU model.

BogoMIPS value.

Base Types and Interfaces

credentialType

Summary:

Describes the security attributes of a security principle.

Type specification:

Name Min/Max Type Description

id 1..1 string

policy 0..1 int

description 0..1 base64Binary cred 0..[]

credentialType (p.

36)

The ID of the node in the credentials hierarchy.

Policy:

1 -- allow (default) 0 -- deny

Credential description.

Nested credentials.

eid_listType

Summary:

Holds a list of Server ID values. See eid_type (p. 29) for the explanation on what a Server ID is.

Type specification:

Name Min/Max Type Description

eid 0..[]

eid_type (p.

29)

Server IDs.

Base Types and Interfaces

env_configType

Summary:

Contains server configuration information. This is a base type. It has only the attributes that are common 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 string description 0..1 base64Binary domain 0..1 string hostname 0..1 string

Server name.

Server description.

Domain name.

Hostname.

address 0..[]

architecture 0..1 string os 0..1 type 0..1 string nameserver 0..[] string

search_domain 0..[] string base_sample_id 0..1 base_snapshot_id 0..1

ip_addressType (p.

46)

osType (p. 55)

guid_type (p. 29) guid_type (p. 29)

List of IP addresses.

Do not use this field when adding or modifying IP addresses of Virtuozzo Containers. Use net_device element of venv_configType (p. 627) instead.

CPU architecture.

Operating system.

Server type.

Name servers.

Use this element when setting nameserver information for a Linux Virtuozzo Container.

For Windows Containers, use <net_device> element of venv_configType (p. 627) instead.

Search domains.

Base sample config ID.

Base snapshot ID.

Subtypes:

venv_configType (p. 69)

Base Types and Interfaces

env_resourceType

Summary:

Contains a list of IP addresses allocated to a server.

Type specification:

Name Min/Max Type Description

eid 1..1 ip_pool 0..1

eid_type (p. 29) ip_poolType (p. 47)

Server ID.

Allocated IP pool.

env_security_objectType

Summary:

A security object of type "server".

Type specification:

Extends security_objectType (p. 62)

Adds the following elements:

Name Min/Max Type Description

eid 1..1

eid_type (p. 29)

Server ID.

Base Types and Interfaces

env_statusType

Summary:

Contains a server status information.

Type specification:

Name Min/Max Type Description

state 0..1 int transition 0..1 int

The server state code.

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, see Appendix B: States and Transitions (p. 742).

envType

Summary:

Contains server information. This type is used for any server type, virtual or physical. However, the config and virtual_config elements may be instantiated using the server type-specific subtypes of their respective types.

Type specification:

Name Min/Max Type Description

parent_eid 1..1 eid 1..1 status 0..1 alert 0..1 int

config 0..1

virtual_config 0..1

eid_type (p. 29) eid_type (p. 29) env_statusType (p. 39)

env_configType (p. 37)

Parent server ID.

Server ID.

Server status.

If any alerts are currently raised on the server then this field will contain the highest existing alert level. See alert_dataType (p. 32) for the list of alert levels.

Regular configuration information.

Virtual configuration information.

Base Types and Interfaces

event_dataType

Summary:

The base type defining system event.

Type specification:

The type has no elements.

Subtypes:

env_status_event_dataType (p. 551) env_config_event_dataType (p. 552) alert_dataType (p. 32) resource_alertType (p. 553)

Base Types and Interfaces

eventType

Summary:

Contains a system event information.

Type specification:

Name Min/Max Type Description

eid 1..1

time 1..1

source 1..1 string

eid_type (p. 29)

datetime_type (p. 28)

The ID of the server that generated the event.

The time at which the event was generated.

The name of the event source -a plug-in or an operator name.

category 1..1 string sid 0..1

count 1..1 int

id 1..1 info 1..1 data 0..1 {

event data 1..1 event_dataType event_data 1..1

}

sidType (p. 30)

guid_type (p. 29) infoType (p. 43)

event_dataType (p.

40)

The category of the event.

The user SID (security ID). Identifies the active user at the time the event was generated.

Message counter. Counts messages received from the same source from the last server restart.

A universally unique message ID.

Event description.

Event type-specific data.

Depending on the event type, the actual data type returned will be one of the descendants of event_dataType (p. 40). The data type can be determined by comparing the value of the category element (above) and the event category described in the descendants of event_dataType (p. 40).

Description:

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 data element contains the event or alert type-specific data. Depending on the type of the event or alert, the data type of the event_data element will be one of the descendants of event_dataType (p. 40). Since you might not know in advance the type of the event, 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 eventType structure from Agent as a result of subscription or an on-demand request. Let's also say that the category element contains the "env_status" value. If you look at the event type definitions (p. 551), you'll see that "env_status" is the category of the env_status_event_dataType (note the env_status entry in the Event type subsection). What this means is that in this particular XML response, the data type of the event_data element (see table above) is env_status_event_dataType (p. 551), not the base event_dataType as shown in the table above.

groupType

Summary:

User group information structure.

Type specification:

Name Min/Max Type Description

user 0..[] { name 1..1 string } member_group 0..[] groupType { name 0..1 string } name 0..1 string gid 0..1 int

userType (p. 68)

User info.

User name.

Member group info.

Group name.

Group ID.

Base Types and Interfaces

infoType

Summary:

The infoType structure is used as a generic container for name/value pairs, and for the text messages that may require localization.

Type specification:

Name Min/Max Type Description

message 1..1 base64Binary

translate 0..1 none

parameter 0..[]

infoType (p. 43)

The original message in the official language 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. The values of the parameters are not included in this element but supplied in the parameter element.

If present, indicates that the message contains words in a natural language and, as such, may require a translation to the language of the user.

The values of the parameters specified in the message element.

The value is linked to the parameter using the name element in such a way that the value of the name element of this structure will be the same as the name of the parameter (%param_name%) in the message element (see example below).

The parameter may also be used as a simple name/value container.

name 1..1 string

Parameter name.

Example:

<info> <message>T3BlcmF0b3IgJW9wZXJhdG9yJSBhdCAlZWlkJSBzdGFydGVk</message> <name></name> <translate/> <parameter> <message>ODQ5YzliZTktNWZiYi00ZTdkLWIxMDAtZjg0MWY4NmMxNTBl</message> <name>eid</name> </parameter> <parameter> <message>dnphX2NvbmY=</message> <name>operator</name> </parameter> </info>

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.

<info> <message>Operator %operator% at %eid% started</message> <name></name> <translate/> <parameter> <message>849c9be9-5fbb-4e7d-b100-f841f86c150e</message> <name>eid</name> </parameter> <parameter> <message>vzl_conf</message> <name>operator</name> </parameter> </info>

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 your

application. For that, you have to check if the translate element is present in the packet. In our 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 are

preceded 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 parameter elements that follow the message element. In the packet listed above, the first parameter is %operator% and its name (operator) is contained in the second (from the top) parameter element. The value of the parameter is contained in the parameter/message element and is vzl_conf. The next parameter (%eid%) is processed in the same exact manner. If you substitute the parameter references in the original message with their values now, the message will read as follows:

Operator vzl_conf at 849c9be9-5fbb-4e7d-b100-f841f86c150e started.

So, the original message that we received essentially means that the vzl_conf Agent operator has been started on the server with the Server ID 849c9be9-5fbb-4e7d-b100- f841f86c150e.

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 message element in the beginning of the structure does not contain any value, which means that the packet does not contain any message. The underlying parameters simply describe the different properties of a server such as hostname, IP address, operating system, etc.

Base Types and Interfaces

<ns2:info> <ns2:message></ns2:message> <ns2:name></ns2:name> <ns2:translate/> <ns2:parameter> <ns2:message>SG9zdC0xMDY=</ns2:message> <ns2:name>hostname</ns2:name> <ns2:translate/> </ns2:parameter> <ns2:parameter> <ns2:message>MTAuMTMwLjEuNg==</ns2:message> <ns2:name>ip</ns2:name> <ns2:translate/> </ns2:parameter> <ns2:parameter> <ns2:message>VGVzdC1WRTY=</ns2:message> <ns2:name>name</ns2:name> <ns2:translate/> </ns2:parameter> <ns2:parameter> <ns2:message></ns2:message> <ns2:name>os</ns2:name> <ns2:parameter> <ns2:message>TGludXg=</ns2:message> <ns2:name>platform</ns2:name> </ns2:parameter> </ns2:parameter> <ns2:parameter> <ns2:message>ODllMjc5NjAtOTdiOC00NjFmLTkwMmYtNTU3YjRiMTY3ODRi</ns2:message> <ns2:name>parent_eid</ns2:name> <ns2:translate/> </ns2:parameter> </ns2:info>

interfaceType

Summary:

Describes a network interface.

Type specification:

Name Min/Max Type Description

name 1..1 string bandwidth 0..1 int transfer 0..1

ipaddress 0..1 flags 0..1 int

transferType (p.

67) ip_type (p. 29)

Interface name.

Bandwidth.

Transfer rate.

IP address.

Network adapter flags:

Bit 0 -- loopback flag.

Bit 1 -- no ARP flag.

Base Types and Interfaces

intervalType

Summary:

A basic date interval structure.

Type specification:

Name Min/Max Type Description

start_time 1..1 end_time 1..1

datetime_type (p. 28) datetime_type (p. 28)

Start time.

End time.

ip_addressType

Summary:

IP address and netmask.

Type specification:

Name Min/Max Type Description

ip 1..1 netmask 0..1

ip_type (p. 29) ip_type (p. 29)

IP address.

Netmask.

Base Types and Interfaces

ip_poolType

Summary:

The IP address information.

Type specification:

Name Min/Max Type Description

[

ip_range 1..1

{ start_ip 1..1 end_ip 1..1 } ip 1..1

ip_type (p. 29) ip_type (p. 29)

ip_type (p. 29)

This is a choice group. Either ip_range or ip can occur in a document but not both at the same time.

Defines a range of IP addresses.

First IP address in the range.

Last IP address in the range.

A single IP address.

]

ip_rangeType

Summary:

IP address range defined by the start IP address and a subnet mask.

Type specification:

Name Min/Max Type Description

id 0..1 string start_ip 0..1 subnet_mask 0..1 int comment 0..1 string

ip_type (p. 29)

Range ID.

Start IP address.

Subnet mask.

Comments.

Base Types and Interfaces

load_avg_statsType

Summary:

Contains load average statistics.

Type specification:

Name Min/Max Type Description

l1 1..1 statsType { avg 0..1 long min 0..1 long max 0..1 long cur 0..1 long } l2 0..1 statsType { avg 0..1 long min 0..1 long max 0..1 long cur 0..1 long } l3 0..1 statsType { avg 0..1 long min 0..1 long max 0..1 long cur 0..1 long

}

1 minute Load Average values.

Average value.

Minimum value.

Maximum value.

Current value.

5 minute Load Average values.

Average value.

Minimum value.

Maximum value.

Current value.

15 minute Load Average values.

Average value.

Minimum value.

Maximum value.

Current value.

load_avgType

Summary:

Load average values.

Type specification:

Name Min/Max Type Description

l1 1..1 double l2 0..1 double l3 0..1 double

1 minute Load Average value.

5 minute Load Average value.

15 minute Load Average value.

log_options_baseType

Summary:

Base Types and Interfaces

Base type.

Type specification:

The type has no elements.

Subtypes:

log_optionsType

log_optionsType (p. 621)

log_optionsType

Summary:

The type for logging options.

Type specification:

Extends log_options_baseType (p. 49)

The type has no additional elements.

Base Types and Interfaces

modType

Summary:

The modType type is used when modifying a user or a group. It is populated with the list of the user/group attributes and the type of the modification to perform on them.

Type specification:

Extends named_listType (p. 50)

Adds the following elements:

Name Min/Max Type Description

op 0..1 int

Modification type:

0 -- Add the specified attribute values (default). 1 -- Delete the specified attribute values. 2 -- Replace the existing attribute values with the values

specified. If an attribute has more than one value, all of those values will be removed and the new values will be used in their place.

named_listType

Summary:

Attribute name/value pair.

Type specification:

Name Min/Max Type Description

name 1..1 string value 0..[] base64Binary

Attribute name.

Attribute value(s).

Base Types and Interfaces

native_configType

Summary:

The base type for the virtual server configuration data in a corresponding virtualization technology's native format. Agent uses its own structures (types) for the virtual server configuration data. Server virtualization products, such as Virtuozzo Containers, cannot directly use this data because they don't natively understand the format. The subtypes of native_configType are used to hold the configuration data in a format understood by a specific virtualization technology. While Agent configuration structures make sense within the context of Agent, the native configuration data can be used externally. For example, you can pass it to a utility that comes with your virtualization product and which expects it as an input. The envm interface (p. 237) provides two calls that allow to convert the configuration data between the two formats -- get_native_config (p. 273) and get_virtual_config.

Note: At the time of this writing, the only supported virtualization technology is Virtuozzo Containers.

Type specification:

The type has no elements.

Subtypes:

virtuozzo_configType (p. 630)

net_addressType

Summary:

Network address.

Type specification:

Name Min/Max Type Description

host 1..1 none

mask 0..1

ip_type (p. 29)

Host/Net name or IP address.

IP mask.

Base Types and Interfaces

net_classType

Summary:

Network class.

Type specification:

Name Min/Max Type Description

id 0..1 string transfer 0..1

transferType (p. 67)

Class ID.

Transfer statistics.

Base Types and Interfaces

net_deviceType

Summary:

Holds a generic network device information. A networks device can be a network interface card, a network bridge, or a virtual local area network. The subtypes of this type extend it adding additional functionality.

Type specification:

Name Min/Max Type Description

id 0..1 string

ip_address 0..[]

dhcp 0..1 none

network_id 0..1 base64Binary

status 0..1 [

up 1..1 none down 1..1 none

]

ip_addressType (p. 46)

Device ID (e.g. interface name eth0, eth1, br2, etc).

The list of IP addresses assigned to this device.

DHCP flag. If present, the device uses DHCP to receive TCP/IP settings.

The ID of the virtual network this device belongs to.

Network device status.

Denotes a choice between the up and the down elements.

The device is up (enabled).

The device is down (disabled).

Subtypes:

net_nicType (p. 54)

net_vethType (p. 622)

net_vlanType (p. 365)

net_bridgeType (p. 365)

Base Types and Interfaces

net_nicType

Summary:

Contains a physical network adapter information.

Type specification:

Extends net_deviceType (p. 53)

Adds the following elements:

Name Min/Max Type Description

mac_address 0..1 string

MAC address.

operator_functionalType

Summary:

Agent Operators are represented in the front-end API by interfaces. 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 operator_functionalType. The type defines the basic input and output parameters. Interfaces extend it with their own input and output parameters.

Type specification:

Name Min/Max Type Description

ok 1..1

error 1..1

{ code 1..1 int message 0..1 string

}

This element is returned to the client when a request completes successfully but does not return any information by definition.

This element is returned when a request results in failure.

Error code.

Text message describing the error.

osType

Summary:

Contains the operating system information.

Type specification:

Name Min/Max Type Description

platform 0..1 string name 1..1 string version 0..1 string kernel 0..1 string

OS platform (Windows, Linux, etc.).

OS name (Windows XP, Red Hat 9, etc.).

OS version.

Kernel ID.

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 packageType type is used as an input parameter, use one of the appropriate 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 string summary 0..1 string os 0..1 description 0..1 string arch 0..1 string

version 0..1 string

osType (p. 55)

Package name.

Summary description.

Target OS and platform.

Description.

Package architecture -- x86, x86_64, etc.

Package version.

Subtypes:

package_linuxType (p. 400)

package_rpmType (p. 400)

package_debType (p. 400)

package_vztemplateType (p. 625)

package_std_vztemplateType (p. 624)

Base Types and Interfaces

perf_dataType

Summary:

Contains data returned by the performance monitor.

Type specification:

Name Min/Max Type Description

eid 1..1 class 0..[] none

{ name 1..1 string instance 1..[] none

{ name 0..1 string counter 1..[] none

{ name 1..1 string value 1..1

} } } interval 1..1

eid_type (p. 29)

perf_statType (p.

58)

intervalType (p. 46)

Server ID.

A list of performance classes that were selected for monitoring.

Class name.

A list of class instances that were selected for monitoring.

Instance name.

A list of performance counters that were selected for monitoring.

Counter name.

Values.

The time interval over which the data was collected.

Base Types and Interfaces

perf_statType

Summary:

Performance statistics.

Type specification:

Name Min/Max Type Description

cur 1..1 anySimpleType avg 1..1 anySimpleType max 1..1 anySimpleType min 1..1 anySimpleType

Current value.

Average value.

Maximum value.

Minimum value.

processesType

Summary:

Contains information about system processes.

Type specification:

Name Min/Max Type Description

run 1..1 int zombie 1..1 int

sleep 1..1 int uninterrupt 1..1 int

stopped 1..1 int total 1..1 int

Number of processes in a "running" state.

Number of processes in a "zombie" state.

Number of processes in a "sleep" state.

Number of processes in a "uninterrupt" state.

Number of processes in a "stopped" state.

Total number of processes.

Base Types and Interfaces

ps_infoType

Summary:

Contains information about system processes.

Type specification:

Name Min/Max Type Description

process 1..[] none { pid 1..1 int param 0..[] base64Binary

} param_id 1..[] string

Process information

Process identifier (PID).

A list of process parameter values in the order indicated by the list contained in the param_id element.

A list of the included process parameters in the order in which their values appear in the param element.

qosType

Summary:

Contains QoS (quality of service) limits.

Type specification:

Name Min/Max Type Description

id 1..1 string soft 0..1 long hard 0..1 long cur 0..1 long

QoS counter ID.

Soft limit.

Hard limit.

Current value.

Base Types and Interfaces

realmType

Summary:

The base type defining a Realm. A Realm is an authentication database containing Parallels Infrastructure 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_realm call (p.

112).

Type specification:

Name Min/Max Type Description

id 0..1

type 1..1 int

name 1..1 string builtin 0..1

guid_type (p.

29)

Globally unique Realm ID. The ID is automatically generated by Agent when a Realm definition is added to the Agent configuration. The ID is guaranteed to be unique across different computers and networks.

Realm type: 0 -- System Realm. This is the operating

system 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. The directory can be located locally or anywhere on the network.

1000 -- Virtuozzo Container Realm. This is the operating system user registry inside a Virtuozzo Container.

The name of the Realm (user defined).

If present, indicates that this is a built-in Realm. A built-in Realms is a preinstalled authentication database. It can be an LDAP directory or an operating system user registry. Built-in Realms contain Parallels Infrastructure Management authentication and authorization information, including built-in security roles, permissions, users, and groups used by Virtuozzo Tools.

Subtypes:

dir_realmType (p. 82)

resourceType

Summary:

A generic type for specifying a resource information.

Type specification:

Name Min/Max Type Description

total 0..1 long used 0..1 long free 0..1 long avg 0..1 long min 0..1 long max 0..1 long

Total units available.

Number of units currently used.

Number if units currently available.

Average usage.

Minimum units used.

Maximum units used.

Base Types and Interfaces

sample_confType

Summary:

Sample configuration information.

Type specification:

Name Min/Max Type Description

id 0..1 name 1..1 string comment 0..1 base64Binary env_config 1..1 vt_version 0..1

{ platform 1..1 string

architecture 1..1 string vt_technology 1..1 string

}

guid_type (p. 29)

env_configType (p. 37)

Sample configuration ID.

Sample configuration name.

Comment.

Configuration parameters.

Virtualization technology information.

Platform (WIndows, Linux, etc.).

Architecture.

Virtualization technology name.

Base Types and Interfaces

security_descriptorType

Summary:

Security descriptor.

Type specification:

Name Min/Max Type Description

owner 1..1

group 1..1

dacl 0..1 { ace 0..[] }

sidType (p. 30)

aceType (p.

Security ID of a security object owner. The owner is the user that is always allowed to control the DACL of the object.

Group security ID. It is used as a way of tracking a group for each object providing support for Linux permissions.

Discretionary Access Control List (DACL).

Access control entry.

31)

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

statsType

Summary:

Holds QoS data.

Type specification:

Name Min/Max Type Description

avg 0..1 long min 0..1 long max 0..1 long total 0..1 long cur 0..1 long soft 0..1 long hard 0..1 long

Average value

Minimum value

Maximum value

Total value

Current value

Soft limit

Hard limit

Base Types and Interfaces

sys_infoType

Summary:

System information.

Type specification:

Name Min/Max Type Description

load_avg 1..1 processes 1..1 cpu_load 1..1 cpu_states 1..1

load_avgType (p. 49) processesType (p. 58) cpu_loadType (p. 35) cpu_loadType (p. 35)

Load averages

Processes statistics

CPU load statistics.

CPU load statistics (percentage).

users 1..1 int uptime 1..1 long memory 0..1

{ total 0..1 long used 1..1 long } swap 0..1

{ total 0..1 long used 1..1 long }

resourceType (p. 61)

Number of users.

Uptime.

Memory statistics. Provided only for Hardware Node.

Total memory available

Memory used.

Swap statistics. Provided only for Hardware Node.

Total.

Used.

Base Types and Interfaces

system_nodeType

Summary:

Contains computer access parameters.

Type specification:

Name Min/Max Type Description

address 1..1 { ip 1..1 } login 0..1 { user 1..1 string password 1..1 base64Binary }

ip_type (p. 29)

IP address.

User name.

Password.

Base Types and Interfaces

tokenType

Summary:

Security token.

Type specification:

Name Min/Max Type Description

user 1..1 groups 0..1

{ sid 1..[] } deny_only_sids 0..1 { sid 1..[] } privileges 0..1 { privilege 1..[]

} source 1..1 { name 1..1 string id 1..1 guid_type }

sidType (p. 30)

privilegeType (p.

29)

SID of the token owner.

The list of SIDs of the groups to which the token owner belongs.

SIDs.

The list of deny-only SIDs.

SIDs.

These fields are not currently used.

Base Types and Interfaces

transferType

Summary:

Contains network transfer statistics.

Type specification:

Name Min/Max Type Description

input 1..1 none { bytes 1..1 long packets 0..1 long } output { bytes 1..1 long packets 0..1 long }

none

Incoming traffic.

Number of bytes.

Number of packets.

Outgoing traffic.

Number of bytes.

Number of packets.

usageType

Summary:

A generic type for specifying a resource usage information.

Type specification:

Name Min/Max Type Description

total 0..1 long used 0..1 long free 0..1 long

Total units.

Used units.

Free units.

Base Types and Interfaces

userType

Summary:

User information.

Type specification:

Name Min/Max Type Description

initial_group 0..1

{ name 0..1 string gid 0..1 int } group 0..[] { name 0..1 string gid 0..1 int } uid 0..1 int shell 0..1 string

password 0..1 base64Binary home_dir 0..1 string name 0..1 string comment 0..1 string

Initial group

Group name

Group ID

Other groups.

Group name.

Group ID.

User ID.

Shell.

Password.

Home directory.

User name.

Comment.

Base Types and Interfaces

venv_configType

Summary:

Virtual server configuration. Container and virtual machine specific structures are derived from this type and contain additional parameters.

Type specification:

Extends env_configType (p. 37)

Adds the following elements:

Name Min/Max Type Description

qos 0..[]

Subtypes:

venv_configType (p. 627)

qosType (p. 59)

QoS parameters.

venv_configType (p. 695)

Base Types and Interfaces

voc_parameterType

Summary:

Contains an Agent vocabulary entry information.

Type specification:

Name Min/Max Type Description

id 1..1 string type 0..1 string min 0..1 string max 0..1 string long 0..1 string short 0..1 string category 0..[] string complex 0..1 string

default 0..1 string measure 0..1 string data 0..1

Vocabulary entry ID.

Data type (int, string, etc.)

Minimum possible value.

Maximum possible value.

Long description.

Short description.

Category.

Entry type-specific value. May have different meaning for different types of entries.

Default value.

Units of measure.

Data (entry-type specific value).

vocabularyType

Summary:

Contains the Agent vocabulary data.

Type specification:

Name Min/Max Type Description

name 1..1 string

parameter 0..[]

category 0..[]

voc_parameterType (p.

563) voc_parameterType (p.

563)

The name of Agent plug-in that this vocabulary is describing.

The vocabulary parameters.

The vocabulary categories.

Base Types and Interfaces

vt_infoType

Summary:

Virtualization technology-specific read-only settings. See subtypes for virtualization technology specific implementations.

Type specification:

Name Min/Max Type Description

xs:any

Subtypes:

vt_infoType (p. 631) vt_infoType (p. 709)

vt_settingsType

Summary:

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

Type specification:

Name Min/Max Type Description

default_sample_id 0..1

guid_type (p.

29)

The default sample configuration ID.

Subtypes:

vzat.vt_settingsType (p. 631)

vt_settingsType (p. 710)

Base Types and Interfaces

Interfaces

The material in this section describes the base Agent XML API interfaces. The term interface, as we use 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 the Virtuozzo Containers Types and Interfaces chapter (p. 620).

alertm

Purpose:

The alertm interface allows the user to receive notifications on critical system events via e-mail and to retrieve the list of currently raised alerts.

Base Types and Interfaces

Types

resource_alertType

Summary:

Resource allocation alert data.

Type specification:

Extends alert_dataType (p. 32)

Adds the following elements:

Name Min/Max Type Description

eid 0..1 class 1..1 string

instance 1..1 string counter 1..1 string cur 1..1 anySimpleType hard 1..1 anySimpleType soft 1..1 anySimpleType

eid_type (p. 29)

Server ID.

Performance class (see perf_mon (p. 389) for more info on this and the following parameters).

Class instance.

Performance counter.

Current value.

Hard value.

Soft value.

Base Types and Interfaces

server_group_alertType

Summary:

Virtuozzo group-wide alert data.

Type specification:

Extends alert_dataType (p. 32)

Adds the following elements:

Name Min/Max Type Description

eid 1..1

address 1..1 string

title 1..1 string description 1..1 string code 1..1 string

eid_type (p. 29)

The ID of the Container that caused the alert.

The address of the slave node hosting the Container specified in the eid element (above).

The title of the slave node.

Problem description.

Error code.

Calls

Call Description

get_alerts (p. 75) Returns current alert states for the specified list of servers.

subscribe_alert (p. 78) Subscribes to receive alert notifications via e-mail.

unsubscribe_alert (p. 80) Cancels alert subscriptions.

Base Types and Interfaces

get_alerts

Summary:

Returns current alert states for specified servers.

Request specification:

Name Min/Max Type Description

get_alerts { eid_list 0..1 category 0..1 string

eid_listType (p. 36)

Server list.

Categories of the alerts to return. If this element is omitted, the call will return alerts of all known types. The available alert categories are:

• resource_alert

• server_group_alert

env_type 0..1 string

}

Return alerts only for the servers of the specified type (generic, virtuozzo).

Returns:

Name Min/Max Type Description

alert 0..[]

eventType (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 subscribe (p. 612) and subscribe_alert (p. 78)), or you can retrieve all alerts that are currently raised on any given server using the get_alerts call.

Example:

The following sample shows how to obtain states of alerts for the specified server(s).

Input

<packet> <target>alertm</target> <data> <alertm> <get_alerts> <eid_list> <eid>ccc794ad-cc5d-49f2-8d84-6631263c81be</eid> </eid_list> </get_alerts>

Base Types and Interfaces

</alertm> </data> </packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/alertm" xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="2dc4ad4739ft26e9rec4" time="2009-10-13T12:33:17+0000"> <ns1:origin>alertm</ns1:origin> <ns1:target>vzclient763-75e18434-5abc-5db7-e963-9f67a2f03412</ns1:target> <ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:alertm> <ns2:alert xsi:type="ns3:eventType"> <ns3:eid>75e18434-5abc-5db7-e963-9f67a2f03412</ns3:eid> <ns3:time>2009-10-09T02:58:33+0000</ns3:time> <ns3:source>ResourceAlertMonitor</ns3:source> <ns3:category>resource_alert</ns3:category> <ns3:sid>AQUAAAAAIAM0hOF1vFq3Xeljn2ei8DQSAAAAAA==</ns3:sid> <ns3:count>1</ns3:count> <ns3:id>83c11a69-5c1f-4836-abc0-de2d779f3331</ns3:id> <ns3:data> <ns3:event_data xsi:type="ns2:resource_alertType"> <ns2:eid>75e18434-5abc-5db7-e963-9f67a2f03412</ns2:eid> <ns2:type>1</ns2:type> <ns2:class>counters_disk</ns2:class> <ns2:instance>\\?\Volume{388c3805-7509-11de-8c64806e6f6e6963}\</ns2:instance> <ns2:counter>counter_disk_share_used</ns2:counter> <ns2:cur>79</ns2:cur> <ns2:soft>85</ns2:soft> <ns2:hard>95</ns2:hard> </ns3:event_data> </ns3:data> <ns3:info xsi:type="ns3:infoType">

<ns3:message>UmVzb3VyY2UgJWlkJSAldHlwZSUgYWxlcnQgb24gZW52aXJvbm1lbnQgJWVudiUgY3VycmVudC B2YWx1ZTogJWN1ciUgc29mdCBsaW1pdDogJXNvZnQlIGhhcmQgbGltaXQ6ICVoYXJkJQ==</ns3:message> <ns3:name></ns3:name> <ns3:translate/> <ns3:parameter> <ns3:message>Nzk=</ns3:message> <ns3:name>cur</ns3:name> </ns3:parameter> <ns3:parameter> <ns3:message>JXRpdGxlJQ==</ns3:message> <ns3:name>env</ns3:name> <ns3:translate/> <ns3:parameter>

<ns3:message>NzVlMTg0MzQtNWFiYy01ZGI3LWU5NjMtOWY2N2EyZjAzNDEy</ns3:message> <ns3:name>eid</ns3:name> <ns3:translate/> </ns3:parameter> <ns3:parameter> <ns3:message>RVZCWU1JTlNEMDIyMw==</ns3:message>

Base Types and Interfaces

<ns3:name>title</ns3:name> <ns3:translate/> </ns3:parameter> <ns3:parameter> <ns3:message>Z2VuZXJpYw==</ns3:message> <ns3:name>type</ns3:name> <ns3:translate/> </ns3:parameter> </ns3:parameter> <ns3:parameter> <ns3:message>OTU=</ns3:message> <ns3:name>hard</ns3:name> </ns3:parameter> <ns3:parameter> <ns3:message>Y291bnRlcl9kaXNrX3NoYXJlX3VzZWQ=</ns3:message> <ns3:name>id</ns3:name> </ns3:parameter> <ns3:parameter> <ns3:message>ODU=</ns3:message> <ns3:name>soft</ns3:name> </ns3:parameter> <ns3:parameter> <ns3:message>eWVsbG93</ns3:message> <ns3:name>type</ns3:name> <ns3:translate/> </ns3:parameter> </ns3:info> </ns2:alert> </ns2:alertm> </ns1:data>

Base Types and Interfaces

subscribe_alert

Summary:

Subscribes to alert notifications via e-mail.

Request specification:

Name Min/Max Type Description

subscribe_alert { eid_list 0..1

email 1..1 string

name 0..1 string

[ 0..1

eid_listType (p.

36)

Server IDs. If omitted, subscribes to receive alert notifications for all known servers.

The e-mail address to send the notifications to.

The name of the e-mail template. The template is configured using the

mailer interface (p. 331). If not

specified, the default template for the specific alert type will be used.

This section specifies the alert type. If the section is omitted, subscribes to QoS alerts by default.

services 1..1 { service 1..[] string } ] }

Get alerts on changing service status.

Service name.

Returns:

OK/Error.

Description:

To prevent alert (mail) flooding you can set mute_alert_period configuration parameter in the alertm section of Agent configuration. Negative value means that subscription stops after the first alert and you have to re-subscribe. Zero value turns off flooding control, i.e. all alerts will be delivered. Positive value means that subsequent alerts for the same servers will be delivered at once in case of period expiration or if alert level is greater than the one of the previous alert.

To set a default e-mail address, use the support_email parameter in the alertm section of Agent configuration.

Base Types and Interfaces

To receive alert notifications directly (not through e-mail), use the system/subscribe call (p.

612) together with resource_alert event (p. 560).

To unsubscribe from this service, use the unsubscribe_alert call (p. 80).

Example:

Input

<packet> <target>alertm</target> <data> <alertm> <subscribe_alert> <eid_list> <eid>ccc794ad-cc5d-49f2-8d84-6631263c81be</eid> </eid_list> <email>johndoe@mail.com</email> <services> <service>crond</service> </services> </subscribe_alert> </alertm> </data> </packet>

Output

<packet> <origin>alertm</origin> <data> <alertm> <ok/> </alertm> </data> </packet>

Incoming email

From: support@tc6.com To: johndoe@mail.com Subject: Service crond is stopped on ccc794ad-cc5d-49f2-8d84-6631263c81be at 2006-0506T19:04:01+0000 Service crond changed status to stopped on ccc794ad-cc5d-49f2-8d84-6631263c81be at 2006-05-06T19:04:01+0000

Base Types and Interfaces

unsubscribe_alert

Summary:

Cancels an alert notification subscription.

Request specification:

Name Min/Max Type Description

unsubscribe_alert { eid_list 0..1

email 1..1 string

services 1..1

eid_listType (p.

36)

Server ID list.

E-mail that was used to subscribe for alerts.

Cancel service status changes alerts.

Returns:

OK/Error

Description

Use the unsubscribe_alert call if you would like to stop receiving alert notifications through email that you previously subscribed to using the subscribe_alert call (p. 78).

Example:

The following sample shows how to obtain states of alerts for the specified server(s).

Input

<packet> <target>alertm</target> <data> <alertm> <unsubscribe_alert> <eid_list> <eid>a6f1d061-8bcd-8ec7-1a73-b078fe2d416f</eid> </eid_list> <email>siarhei_rabtsau@epaml.com</email> <services> <service>crond</service> </services> </unsubscribe_alert> </alertm> </data> </packet>

Output

Base Types and Interfaces

<packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/alertm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="15c4adf08b8t5f90r2c8" time="2009-10-21T13:10:49+0000"> <ns1:origin>alertm</ns1:origin> <ns1:target>vzclient8271-a6f1d061-8bcd-8ec7-1a73-b078fe2d416f</ns1:target> <ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:alertm> <ns1:error> <ns1:code>4102</ns1:code> <ns1:message>Unsubscribe error: Subscription not found email: siarhei_rabtsau@epaml.com, eid: a6f1d061-8bcd-8ec7-1a73-b078fe2d416f</ns1:message> </ns1:error> </ns2:alertm> </ns1:data> <src> <director>gend</director> </src> </packet>

authm

Purpose:

User/group profile management, user authentication, realm management.

Base Types and Interfaces

Types

dir_realmType

Summary:

Defines an LDAP directory-based realm (an LDAP-compliant directory such as AD or ADAM on Windows, or OpenLDAP on Linux).

Type specification:

Extends realmType (p. 60).

Adds the following elements:

Name Min/Max Type Description

address 1..1 string

port 1..1 int

base_dn 1..1 string

default_dn 1..1 string

The IP address or the hostname of the server hosting the directory.

The TCP port at which the directory instance is listening for requests.

Base DN. This is the top level of the directory tree.

Default DN. This is the distinguished name of the default container where the user information is stored.

The default DN allows you to pass the user name during login or other operations as a plain name instead of using a fully qualified DN.

For example, let's say that the default DN is CN=Users,DC=Mydomain

If the user name is passed as TestUser (for example), then Agent will automatically construct a full DN by adding the TestUser to the default DN.

Login information. This information is used to establish a connection with the directory instance to perform authentication. The user specified here must exist in the directory and should have sufficient rights to use the directory services.

Base Types and Interfaces

security_principalType

Summary:

Contains information about a security principal.

Type specification:

Extends auth_nameType (p. 33)

Adds the following elements:

Name Min/Max Type Description

group 0..[]

member_group 0..[] member_user 0..[] data 0..1 { attr 0..[]

}

auth_nameType (p. 33) A list of groups to which this user

or group belongs.

When adding a user or a group, this element is used to specify the groups to add the principal user/group to.

auth_nameType (p. 33) A list of member groups.

auth_nameType (p. 33) A list ot member users.

named_listType (p. 50) Attributes and their values. The

The user/group profile data.

available attributes are determined by the "database" used. In an LDAP directory these would be the attributes of an object representing the user.

Base Types and Interfaces

sp_modType

Summary:

Used when modifying a user or a group.

Type specification:

Name Min/Max Type Description

name 0..1 base64Binary domain 0..1 base64Binary data 0..1 { mod 0..[]

}

modType (p. 50)

User/group name.

Domain name.

Attributes.

A list of the user/group attributes. The values can be added, deleted, or replaced based on the specified operation type. See modType (p. 50) for details.

Base Types and Interfaces

Calls

Call Description

add_group (p. 86) Adds a new group to the specified realm.

add_user (p. 93) Adds a new user to the specified realm.

edit_group (p. 543) Modifies an existing group.

edit_user (p. 104) Modifies an existing user.

add_to_group (p. 91) Adds a user/group to other groups as a member.

del_from_group (p. 97) Deletes a user/group from groups.

get_group (p. 541) Retrieves group information.

get_user (p. 535) Retrieves user information.

del_group (p. 532) Deletes a group from the database.

del_user (p. 101) Deletes a user from the database.

authenticate (p. 95) Authenticates a user.

add_realm (p. 88) Adds a new Realm definition to the Agent configuration.

del_realm (p. 100) Deletes an existing Realm definition.

get_realm (p. 112) Retrieves information about existing realms.

set_realm (p. 119) Modifies the specified realm definition.

get_auth_name (p. 106) Returns login information for the security account specified by the SID.

get_sid (p. 114) Returns SID of the security account specified by the login info.

Base Types and Interfaces

add_group

Summary:

Adds a new group to the specified Realm.

Request specification:

Name Min/Max Type Description

add_group { group 1..1 security_principalType

}

(p. 83)

The new group information.

Returns:

OK/Error

Description:

The group name can be specified as a DN or as a plain name. If you specify a fully qualified distinguished name, the group will be created in the specified location in the directory tree. If you use a plain name, the group will be created using the specified name in the default container for this realm. To find out what the default DN is, use the get_realm call (p. 112).

Note: The call will try to create a new directory object of class Group (objectClass=Group). Your directory schema must have the Group class in it or the call will fail.

Example:

Creating a new group named Test_Group in the specified Realm. The group name is specified as a plain name so it will be created in the default container for this Realm.

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <add_group> <group> <name>VGVzdF9Hcm91cA==</name> <realm>3e761571-6607-1344-a064-a42679da8ed9</realm> <data> <attr> <name>description</name> <value>VGhpcyBpcyBhIHRlc3QgZ3JvdXA=</value> </attr> </data> </group> </add_group>

Base Types and Interfaces

</authm> </data> </packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="9c469dcebft6784r4b4" time="2007-07-18T06:21:21+0000" priority="0" version="4.0.0"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient4-2cbbe469-8f57-7f46-97fb-fd987231d957</ns1:target> <ns1:dst> <ns1:director>gend</ns1:director> </ns1:dst> <ns1:data> <ns2:authm> <ns1:ok/> </ns2:authm> </ns1:data> <ns1:src> <ns1:director>gend</ns1:director> </ns1:src> </packet>

Base Types and Interfaces

add_realm

Summary:

Adds a Realm definition to the Agent configuration.

Request specification:

Name Min/Max Type Description

add_realm { realm 1..1

password 0..1 base64Binary

}

realmType (p. 60)

Realm information. Depending on the realm type, use the appropriate subtype of the realmType type (p.

60).

The password for the user account specified in the login portion of the realm structure above.

Returns:

Name Min/Max Type Description

id 1..1 guid_type

The new realm ID (automatically generated by Agent). The ID is universally unique.

Description:

When adding an LDAP directory realm, the call does not verify whether the values that you supply are valid or not. It verifies the basic syntax, but it doesn't actually try to connect to the directory. After you execute the call, you should check that you can connect to the directory and retrieve the data from it. For example, you can try getting a user information from with the get_user call (p.

116).

Note: When adding an LDAP directory Realm please make sure that the users in your directory are stored as objects of type User (objectClass=User) and that the groups are stored as objects of type Group (objectClass=Group). If the user and group objects use different classes, you will not be able to see or authenticate them in Agent.

Example:

The following example shows how to create a typical LDAP directory realm. The following table describes the parameters and their values used in the example.

Parameter Value Description

type

LDAP directory realm.

Base Types and Interfaces

name address 192.168.0.117

port 398

base_dn dc=vzl default_dn cn=users,dc=vzl

password bXlwYXNz

myrealm

Realm name.

The IP address of the server hosting the LDAP directory.

TCP port number on which the directory instance is listening for requests.

Base DN (the top level of the directory tree).

Default DN (the default container in the directory where the user information is stored).

The DN of the user that will be used to connect to the directory instance to perform authentications.

The password for the user specified in the login/name parameter above.

Input

<packet xmlns:ns4="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0"> <target>authm</target> <data> <authm> <add_realm> <realm xsi:type="ns4:dir_realmType"> <type>1</type> <name>myrealm</name> <address>192.168.0.117</address> <port>398</port> <base_dn>dc=vzl</base_dn> <default_dn>cn=users,dc=vzl</default_dn> <login> <name>Y249dnphZ2VudCxkYz1WWkw=</name> </login> </realm> <password>bXlwYXNz</password> </add_realm> </authm> </data> </packet>

Output

<?xml version="1.0" encoding="UTF-8"?><ns1:packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="8c460a8b7ft6952r350" time="2007-03-21T12:21:57+0000" priority="0" version="4.0.0"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient8</ns1:target> <ns1:dst> <ns1:director>gend</ns1:director> </ns1:dst> <ns1:data> <ns2:authm> <ns2:id>18e8c5f0-e656-4144-864c-0520275a4bd1</ns2:id> </ns2:authm> </ns1:data>

Base Types and Interfaces

<ns1:src> <ns1:director>gend</ns1:director> </ns1:src> </ns1:packet>

add_to_group

Summary:

Add a user or a group to other groups as a member.

Request specification:

Name Min/Max Type Description

add_to_group 1..1

{ group 1..[]

}

auth_nameType (p. 33) The inherited auth_nameType

portion is used to specify the user/group to add to other groups as a member.

auth_nameType (p. 33)

Parent groups. The specified user or group will be added as a member to these groups.

Returns:

Base Types and Interfaces

OK/Errors.

Description:

The call adds a user or a group to another group or to multiple groups. This call works only with the users and groups that already exist. To create a new user or a group and add it to another group at the same time, use the add_user (p. 93) or add_group (p. 86) calls.

Example:

Adding a user Test_User from the default realm to the Administrators group.

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <add_to_group> <name>VGVzdF9Vc2Vy</name> <realm>00000000-0000-0000-0000-000000000005</realm> <group> <name>VGVzdF9Hcm91cA==</name> <realm>00000000-0000-0000-0000-000000000005</realm> </group> </add_to_group> </authm> </data> </packet>

Output

Base Types and Interfaces

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="36c4ae00f60t4dc8r2c8" time="2009-10-22T07:53:34+0000"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient60-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target> <ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:authm> <ns1:ok/> </ns2:authm> </ns1:data> <src> <director>gend</director> </src> </packet>

Base Types and Interfaces

add_user

Summary:

Adds a new user to the specified realm.

Request specification:

Name Min/Max Type Description

add_user { user 1..1 security_principalType

password 1..1 base64Binary

}

(p. 83)

The new user information.

A password to set for the new user.

Returns:

OK/Error

Description:

The user name can be specified as a distinguished name (DN) or as a plain name. If you use a fully qualified DN, the user will be created in the specified location in the directory tree. If you use just a plain name, the user will be created in the default container for this realm. To find out what the default DN is, use the get_realm call (p. 112).

Note: The call will try to create a new directory object of class User (objectClass=User). Your directory schema must have the User class in it or the call will fail.

Example:

Creating a new user named Test_User in the specified realm. The user name is specified as a plain name so it will be created in the default container for this Realm.

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <add_user> <user> <name>VGVzdF9Vc2Vy</name> <realm>3e761571-6607-1344-a064-a42679da8ed9</realm> <data> <attr> <name>description</name> <value>VGhpcyBpcyBhIHRlc3QgdXNlcg==</value> </attr>

Base Types and Interfaces

</data> </user> <password>bXlwYXNzd2Q=</password> </add_user> </authm> </data> </packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="23c469e077at4db7r4b4" time="2007-07-18T08:57:51+0000" priority="0" version="4.0.0"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient4-2cbbe469-8f57-7f46-97fb-fd987231d957</ns1:target> <ns1:dst> <ns1:director>gend</ns1:director> </ns1:dst> <ns1:data> <ns2:authm> <ns1:ok/> </ns2:authm> </ns1:data> <ns1:src> <ns1:director>gend</ns1:director> </ns1:src> </packet>

Base Types and Interfaces

authenticate

Summary:

Authenticates the specified user.

Request specification:

Name Min/Max Type Description

authenticate 1..1

{ password 1..1 base64Binary

}

auth_nameType (p.

33)

The inherited auth_nameType portion is used to specify the user login information.

The password of the user account specified in the auth_nameType portion.

Returns:

Name Min/Max Type Description

token 1..1

tokenType (p. 66)

The security token for the user.

Returns error if the user credentials are invalid.

Description:

The call authenticates a user against the specified realm. Unlike the system/login call (p. 606), this call does not log the user in and does not create a session for the user. It simply verifies the identity of the user and, in case of success, returns the user security information.

Example:

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <authenticate> <name>VGVzdF9Vc2Vy</name> <realm>3e761571-6607-1344-a064-a42679da8ed9</realm> <password>bXlwYXNz</password> </authenticate> </authm> </data> </packet>

Output

Base Types and Interfaces

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="38c4ae0120ft66bbr2c8" time="2009-10-22T08:05:00+0000"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient60-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target> <ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:authm> <ns2:token xsi:type="ns3:tokenType"> <ns3:user>AQUAAAAAIAERFULeKciOQr59KBZnje7JAQAAAA==</ns3:user> <ns3:groups> <ns3:sid>AQUAAAAAIAERFULeKciOQr59KBZnje7JAQAAAA==</ns3:sid> <ns3:sid>AQUAAAAAIAGvZxwyACmNS7W3n7IpoA6KAQAAAA==</ns3:sid> </ns3:groups> <ns3:deny_only_sids/> <ns3:privileges/> <ns3:name xsi:type="ns3:auth_nameType"> <ns3:name>VGVzdF9Vc2Vy</ns3:name> <ns3:realm>00000000-0000-0000-0000-000000000005</ns3:realm> </ns3:name> </ns2:token> </ns2:authm> </ns1:data> <src> <director>gend</director> </src> </packet>

Base Types and Interfaces

del_from_group

Summary:

Remove a user or a group from a group.

Request specification:

Name Min/Max Type Description

del_from_group 1..1

{ group 1..[]

}

auth_nameType (p. 33)

The member user or member group information.

The list of the groups to remove the specified user/group from.

Returns:

OK/Errors.

Description:

The call removes the specified user or group from the specified group(s). To delete a user or a group from the database (realm), use del_user (p. 101) or del_group (p. 99).

Example:

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <del_from_group> <name>VGVzdF9Vc2Vy</name> <realm>00000000-0000-0000-0000-000000000005</realm> <group> <name>Q049QWRtaW5pc3RyYXRvcnMsQ049Um9sZXMsREM9U1dB</name> <realm>00000000-0000-0000-0000-000000000005</realm> </group> </del_from_group> </authm> </data> </packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol" xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0" id="39c4ae01815t428br2c8" time="2009-10-22T08:30:42+0000"> <ns1:origin>authm</ns1:origin> <ns1:target>vzclient60-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

Base Types and Interfaces

<ns1:dst> <director>gend</director> </ns1:dst> <ns1:data> <ns2:authm> <ns1:ok/> </ns2:authm> </ns1:data> <src> <director>gend</director> </src> </packet>

Base Types and Interfaces

del_group

Summary:

Deletes the specified group from the specified realm.

Request specification:

Name Min/Max Type Description

del_group { group 0..1

}

auth_nameType (p.

33)

The group information.

Returns:

OK/Errors

Description:

The del_group call deletes the specified group from the specified realm. If the group has member users and/or groups, their membership will be automatically revoked.

Example:

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <del_group> <group> <name>Q049VGVzdF9Hcm91cCxDTj1Sb2xlcyxEQz1TV0E=</name> <realm>3f15a4a2-14e0-17da-b387-599bc36ee36d</realm> </group> </del_group> </authm> </data> </packet>

Output

<packet id="2" version="4.0.0"> <origin>authm</origin> <target>vzclient1</target> <dst> <director>gend</director> </dst> <data> <authm> <ok/> </authm> </data>

Base Types and Interfaces

del_realm

Summary:

Deletes an existing realm definition from the Agent configuration.

Request specification:

Name Min/Max Type Description

del_realm { id 1..1 guid_type }

The ID of the realm to remove.

Returns:

OK/Errors.

Description:

The call deletes the specified realm definition from the Agent configuration. It does not physically delete the "database" (i.e. an LDAP directory instance), so the user data stored in it will not be affected. You can recreate the realm definition using the same directory at any time if you wish.

Example:

Input

<packet version="4.0.0" id="2"> <target>authm</target> <data> <authm> <del_realm> <id>453a0163-8abd-4e38-a04f-fe67d0c48b97</id> </del_realm> </authm> </data> </packet>

100

Parallels Virtual Automation - 6.1 User Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Preface

About This Guide

Who Should Read This Guide

Organization of This Guide

How to Use This Guide

Documentation Conventions

Typographical Conventions

Shell Prompts in Command Examples

General Conventions

Feedback

Reference Format

XML Message Specifications

XML Code Samples

Agent Messages

Message Header

Message Body

Base Types and Interfaces

Common Types

Primitive Types

Simple Types

datetime_type

eid_type

guid_type

ip_type

privilegeType

sidType

transport_type

Complex Types

aceType

alert_dataType

auth_nameType

connection_infoType

connectivity_infoType

cpu_loadType

cpuType

credentialType

eid_listType

env_configType

env_resourceType

env_security_objectType

env_statusType

envType

event_dataType

eventType

groupType

infoType

interfaceType

intervalType

ip_addressType

ip_poolType

ip_rangeType

load_avg_statsType

load_avgType

log_options_baseType

log_optionsType

modType

named_listType

native_configType

net_addressType

net_classType

net_deviceType

net_nicType

operator_functionalType

osType

packageType

perf_dataType

perf_statType

processesType

ps_infoType

qosType

realmType

resourceType

sample_confType

security_descriptorType

security_objectType

statsType