Parallels PVA Agent Virtual Automation 6.1 XML API Reference 61 Ref EN

PVA Agent

XML API Reference

Parallels IP Holdings GmbH.

bH.

320 411

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

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

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

s.

be trademarks of their respective owners.

c/o Parallels International Gm

Parallels International GmbH

Vordergasse 49

CH8200 Schaffhausen

Switzerland

Tel: + 41 526

Fax: + 41 52672 2010

www.parallels.com

C

T

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

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

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

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

7

Preface

Organization of This Guide

This guide is organized into the following chapters:

Chapter 1, Preface. Provides information about this guide.

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

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

structure.

Chapter 4, Base Types and Interfaces. Describes the base data types and interfaces. The

chapter is divided into sections. The Common 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.

8

Preface

How to Use This Guide

You don't have to read the entire XML reference guide from cover to cover, but you should read 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

Selectable entities such as menu

options, buttons, or list items.

Go to the Resources tab.

Special Bold

Titles of chapters, sections and

subsections.

Read the Basic Administration chapter.

9

Preface

Italics Important points, terms, guide

titles, command variables.

These are the so-called EZ templates.

To destroy a Container, type vzctl

destroy CT_ID.

Monospace Names of commands, files, and

directories.

Use vzctl start to start a Container.

Preformatted On-screen console output in

command line sessions, source

code.

Saves parameters for Container

101

Preformatted Bold What you type as contrasted with

on-screen console output.

# rpm -V virtuozzo-release

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

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.

To create a Container:

Special Bold Items you must select, such as menu

options, command buttons, or items in a

list.

Go to the Resources tab.

Titles of chapters, sections, and

subsections.

Read the Basic Administration chapter.

10

Preface

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

These are the so-called EZ templates.

To destroy a Conainer, type vzctl destroy

ctid.

Monospace The names of commands, files, and

directories.

Use vzctl start to start a Container.

Preformatted On-screen computer output in your

command-line sessions; source code in

XML, C++, or other programming

languages.

Saved parameters for Container 101

Monospace Bold What you type, contrasted with on-screen

computer output.

# rpm –V virtuozzo-release

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

KEY+KEY Key combinations for which the user must

press and hold down one key and then

press another.

CTRL+P, ALT+F4

Shell Prompts in Command Examples

Command line examples throughout this guide presume that you are using the Bourne-again shell

(bash). Whenever a command can be run as a regular user, we will display it with a dollar sign

prompt. When a command is meant to be run as root, we will display it with a hash mark prompt:

Bourne-again shell prompt $

Bourne-again shell root prompt #

General Conventions

Be aware of the following conventions used in this book.

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

For example, Documentation 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.

11

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

CHAPTER 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

13

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

domain 0..1 base64Binary Domain.

realm 1..1 guid_type Realm ID.

password 0..1 base64Binary User password.

expiration 0..1 int Custom timeout value.

}

The information in a table is based on a corresponding XML Schema and describes the format of a

request or response message, or the format of a data type.

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

defined in the XML Schema.

The definitions for the table columns are as follows:

Name. Specifies an XML element name. The curly brackets represent the standard XML Schema

xs: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>

</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 Device status,

[ Denotes a choice between the <up> and the

<down> elements.

up 1..1 none Enabled.

14

Reference Format

down 1..1 none Disabled.

]

This means that the elements inside the brackets are the child elements of the element that precedes the opening

bracket but the elements are mutually exclusive -- only one of them can be present in the request.

Min/Max. Specifies the cardinality of an element (the number of its minimum and maximum

occurrences) in the following format:

minOccurs..maxOccurs

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

15

Reference Format

<name>QWRtaW5pc3RyYXRvcg==</name>

<password>MXEydzNl</password>

</login>

</system>

</data>

</packet>

16

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

<data>

<get_version/>

</system>

</data>

</packet>

Output

<packet id="2c446af2aet18be" time="2006-05-17T09:54:00+0000" priority="0"

version="4.0.0">

<target>vzclient4</target>

<dst>

</dst>

<data>

<version>pvaagent-4.0.0</version>

</system>

</data>

<src>

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

17

Reference Format

CHAPTER 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

19

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 The root element of an Agent XML message.

{

cookie 0..1 string 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.

target 0..[] string In request messages, this element must

contain the name of the operator to which

the request should be sent for processing.

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

origin 0..1 string The name of the operator that generated the

response. Included in response messages

only.

20

Agent Messages

src 0..1 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.

{

director 0..1 string The name of the director to which the target

operator belongs.

host 0..1 string 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.

index 0..1 string For on-demand operators, specifies a

particular target.

target 0..1 string Contains the origin information when a

packet is sent remotely.

}

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

In the response messages, this information

is automatically populated by the director on

the server side.

{

director 0..1 string The name of the director to which the target

operator belongs. Populated automatically

by the director.

host 0..1 string Destination server EID. When using the

message forwarding feature, it is used for

specifying the ID of the target server.

index 0..1 string For on-demand operators, specifies a

particular target. Populated automatically by

the director.

target 0..1 string Contains the origin information when a

packet is sent remotely. Populated

automatically by Agent.

}

21

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.

22

Agent Messages

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

time datetime_type The time when the packet was sent; in the ISO-8601

format: (e.g. "2007-02-04T08:55:51+0000").

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

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.

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

23

Agent Messages

type int *** INTERNAL ***

Bit field for the internal type of the message.

#define UNFINISHED 0x00000001

#define RESPONSE 0x00000002

#define RESCHEDULE 0x00000004

#define TIMEOUT 0x00000008

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

timeout_limit int *** INTERNAL ***

Timeout limit for message processing. Used by an

operator in determining the validity of its timeout.

uid int *** 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.

<cookie>I'm a cookie holding some text</cookie>

<target>operator_name</target>

<dst>

Hosttarget_server_EID</host>

</dst>

<session>session_id</session>

</packet>

24

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.

<data>

<envm>

<get_info>

</get_info>

</envm>

</data>

</packet>

The response message:

The following example demonstrates a complete response message. The body of the message

begins with the data element which is followed by the name of the interface that was used in the

corresponding request message, and the return parameters.

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/envm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="ac49b7e2c8t6784r580" time="2009-03-11T16:09:33+0000">

<ns1:origin>envm</ns1:origin>

<ns1:target>vzclient4-b1e6bc1e-4231-b541-819a-191cd7fec5fb</ns1:target>

<ns1:dst>

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

25

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>

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

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

27

Base Types and Interfaces

Primitive Types

Primitive types are the basic building blocks of an XML Schema. The following table describes the

most common primitive types used in the Agent XML Schema.

Name Description

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

true), and 0 (which indicates false).

int A signed 32-bit integer.

long A signed 64-bit integer

double A 64-bit floating point.

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

base64Binary Base64-encoded binary data.

Simple Types

Simple types are custom types that can contain a value but cannot contain attributes or elements.

Most of the custom simple types have restrictions added to them in order to limit their content. A

restriction can limit the type to a specific primitive data type, it can also define a list of enumerated

values, or it can define a string pattern that the value must adhere to.

28

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.

29

Base Types and Interfaces

eid_type

Summary:

Holds a Server ID value. Server ID is a globally unique identifier that is assigned to every computer

(physical or virtual) that has Parallels Agent installed on it. The ID is assigned to a physical server as

soon as Parallels Virtual Automation software is installed on it. The ID is assigned to a virtual

environment at the time of creation.

Type specification:

Restriction: guid_type (p. 29)

guid_type

Summary:

A globally unique identifier.

Type specification:

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

30

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.

31

Base Types and Interfaces

aceType

Summary:

Access control entry.

Type specification:

Name Min/Max Type Description

type 1..1 int Type of ACE:

0 -- allow

1 -- deny

sid 1..1 sidType (p. 30) Security identifier of a user or a group.

rights 1..1 base64Binary Access rights.

Description:

The access control entry (ACE) is an individual record in a DACL (Discretionary Access Control List).

It includes the SID (security ID) of a single user or a group along with an access mask that specifies

the permissions being granted or denied.

At the time of this writing, you can only set permissions to the entire object (not the individual

operations that can be performed on it). This means that the rights parameter is not currently

used. Simply include an empty rights element when setting permissions.

See also:

security_descriptorType (p. 62)

32

Base Types and Interfaces

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 0 -- green alert.

1 -- yellow alert.

2 -- red alert.

Description:

The alert type denotes the severity level. There are four alert levels:

Green alert -- Normal operation. This alert type is normally silent but can still trigger when one of the

higher alert levels is canceled and the situation returns to normal.

Yellow alert -- Warning. For a resource allocation alert it means that at least 90% of the specified

soft limit was reached.

Red alert -- Critical situation. For a resource alert it means that the current resource usage is above

the soft limit and further allocation can be refused at any moment.

The subtypes of 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)

33

Base Types and Interfaces

auth_nameType

Summary:

User login information.

Type specification:

Name Min/Max Type Description

name 0..1 base64Binary 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 0..1 base64Binary 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 1..1 guid_type (p. 29) Realm ID. When adding a user or a

group to a realm, specify the target

realm ID here.

34

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

login 0..1 auth_nameType (p. 33) Login information.

password 0..1 base64Binary Password.

connectivity_infoType

Summary:

Contains the network connectivity information.

Type specification:

Adds the following elements:

Name Min/Max Type Description

protocol 0..1 string Communication protocol:

SSL -- SSL over TCP/IP.

TCP -- plain TCP/IP.

NamedPipe -- named pipe.

address 1..1 string IP address.

port 0..1 unsignedInt Port number.

35

Base Types and Interfaces

cpu_loadType

Summary:

Contains CPU load values.

Type specification:

Name Min/Max Type Description

system 1..1 long CPU used by system processes.

user 1..1 long CPU used by user processes.

nice 1..1 long CPU used by "nice" processes.

idle 1..1 long CPU idle.

cpuType

Summary:

Contains common CPU characteristics.

Type specification:

Name Min/Max Type Description

mhz 1..1 int CPU Frequency, in MegaHertz.

name 1..1 string CPU name.

number 1..1 int Number of CPUs in the system.

cores 1..1 int Number of cores per CPU.

hyperthreads 1..1 int Number of hyper-threads per CPU core.

The value of 1 indicates that no hyper-

threading is available.

units 1..1 int CPU unit value.

family 1..1 string CPU family.

model 1..1 string CPU model.

bogomips 1..1 int BogoMIPS value.

36

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 The ID of the node in the

credentials hierarchy.

policy 0..1 int Policy:

1 -- allow (default)

0 -- deny

description 0..1 base64Binary Credential description.

cred 0..[] credentialType (p.

36)

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.

37

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

description 0..1 base64Binary Server description.

domain 0..1 string Domain name.

hostname 0..1 string Hostname.

address 0..[] ip_addressType (p.

46)

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.

architecture 0..1 string CPU architecture.

os 0..1 osType (p. 55) Operating system.

type 0..1 string Server type.

nameserver 0..[] string 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_domain 0..[] string Search domains.

base_sample_id 0..1 guid_type (p. 29) Base sample config ID.

base_snapshot_id 0..1 guid_type (p. 29) Base snapshot ID.

Subtypes:

venv_configType (p. 69)

38

Base Types and Interfaces

env_resourceType

Summary:

Contains a list of IP addresses allocated to a server.

Type specification:

Name Min/Max Type Description

eid 1..1 eid_type (p. 29) Server ID.

ip_pool 0..1 ip_poolType (p. 47) 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.

39

Base Types and Interfaces

env_statusType

Summary:

Contains a server status information.

Type specification:

Name Min/Max Type Description

state 0..1 int The server state code.

transition 0..1 int 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_type (p. 29) Parent server ID.

eid 1..1 eid_type (p. 29) Server ID.

status 0..1 env_statusType (p. 39) Server status.

alert 0..1 int 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.

config 0..1 env_configType (p. 37) Regular configuration

information.

virtual_config 0..1 env_configType (p. 37) Virtual configuration

information.

40

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)

41

Base Types and Interfaces

eventType

Summary:

Contains a system event information.

Type specification:

Name Min/Max Type Description

eid 1..1 eid_type (p. 29) The ID of the server that

generated the event.

time 1..1 datetime_type (p. 28)The time at which the event was

generated.

source 1..1 string The name of the event source --

a plug-in or an operator name.

category 1..1 string The category of the event.

sid 0..1 sidType (p. 30) The user SID (security ID).

Identifies the active user at the

time the event was generated.

count 1..1 int Message counter. Counts

messages received from the

same source from the last server

restart.

id 1..1 guid_type (p. 29) A universally unique message ID.

info 1..1 infoType (p. 43) Event description.

data 0..1 Event type-specific data.

{

event data 1..1 event_dataType

event_data 1..1 event_dataType (p.

40)

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:

42

Base Types and Interfaces

This structure is returned by the calls that provide information about system events and alerts. The

elements in the beginning of the structure are common to all event types and provide the basic

event information. The 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..[] userType (p. 68) User info.

{

name 1..1 string User name.

}

member_group 0..[] groupType Member group info.

{

name 0..1 string Group name.

}

name 0..1 string Group name.

gid 0..1 int Group ID.

43

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

translate 0..1 none 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.

parameter 0..[] infoType (p. 43) 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>

<message>ODQ5YzliZTktNWZiYi00ZTdkLWIxMDAtZjg0MWY4NmMxNTBl</message>

</parameter>

<message>dnphX2NvbmY=</message>

<name>operator</name>

</parameter>

</info>

44

Base Types and Interfaces

In order to decode the message above, you first have to decode the base64-encoded values that

the message contains. The following is the same message with the values decoded to plain text.

<info>

<message>Operator %operator% at %eid% started</message>

</parameter>

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

45

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: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 Interface name.

bandwidth 0..1 int Bandwidth.

transfer 0..1 transferType (p.

67)

Transfer rate.

ipaddress 0..1 ip_type (p. 29) IP address.

flags 0..1 int Network adapter flags:

Bit 0 -- loopback flag.

Bit 1 -- no ARP flag.

46

Base Types and Interfaces

intervalType

Summary:

A basic date interval structure.

Type specification:

Name Min/Max Type Description

start_time 1..1 datetime_type (p. 28)Start time.

end_time 1..1 datetime_type (p. 28)End time.

ip_addressType

Summary:

IP address and netmask.

Type specification:

Name Min/Max Type Description

ip 1..1 ip_type (p. 29)IP address.

netmask 0..1 ip_type (p. 29)Netmask.

47

Base Types and Interfaces

ip_poolType

Summary:

The IP address information.

Type specification:

Name Min/Max Type Description

[ This is a choice group. Either

ip_range or ip can occur

in a document but not both

at the same time.

ip_range 1..1 Defines a range of IP

addresses.

{

start_ip 1..1 ip_type (p. 29) First IP address in the range.

end_ip 1..1 ip_type (p. 29) Last IP address in the range.

}

ip 1..1 ip_type (p. 29) 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 Range ID.

start_ip 0..1 ip_type (p. 29) Start IP address.

subnet_mask 0..1 int Subnet mask.

comment 0..1 string Comments.

48

Base Types and Interfaces

load_avg_statsType

Summary:

Contains load average statistics.

Type specification:

Name Min/Max Type Description

l1 1..1 statsType 1 minute Load Average values.

{

avg 0..1 long Average value.

min 0..1 long Minimum value.

max 0..1 long Maximum value.

cur 0..1 long Current value.

}

l2 0..1 statsType 5 minute Load Average values.

{

avg 0..1 long Average value.

min 0..1 long Minimum value.

max 0..1 long Maximum value.

cur 0..1 long Current value.

}

l3 0..1 statsType 15 minute Load Average values.

{

avg 0..1 long Average value.

min 0..1 long Minimum value.

max 0..1 long Maximum value.

cur 0..1 long Current value.

}

49

Base Types and Interfaces

load_avgType

Summary:

Load average values.

Type specification:

Name Min/Max Type Description

l1 1..1 double 1 minute Load Average value.

l2 0..1 double 5 minute Load Average value.

l3 0..1 double 15 minute Load Average value.

log_options_baseType

Summary:

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.

50

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

value 0..[] base64Binary Attribute value(s).

51

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 Host/Net name or IP

address.

mask 0..1 ip_type (p. 29) IP mask.

52

Base Types and Interfaces

net_classType

Summary:

Network class.

Type specification:

Name Min/Max Type Description

id 0..1 string Class ID.

transfer 0..1 transferType (p. 67) Transfer statistics.

53

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 Device ID (e.g. interface

name eth0, eth1, br2,

etc).

ip_address 0..[] ip_addressType (p. 46) The list of IP addresses

assigned to this device.

dhcp 0..1 none DHCP flag. If present, the

device uses DHCP to receive

TCP/IP settings.

network_id 0..1 base64Binary The ID of the virtual network

this device belongs to.

status 0..1 Network device status.

[ Denotes a choice between

the up and the down

elements.

up 1..1 none The device is up (enabled).

down 1..1 none The device is down

(disabled).

]

Subtypes:

net_nicType (p. 54)

net_vethType (p. 622)

net_vlanType (p. 365)

net_bridgeType (p. 365)

54

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 This element is returned to

the client when a request

completes successfully but

does not return any

information by definition.

error 1..1 This element is returned

when a request results in

failure.

{

code 1..1 int Error code.

message 0..1 string Text message describing the

error.

}

55

Base Types and Interfaces

osType

Summary:

Contains the operating system information.

Type specification:

Name Min/Max Type Description

platform 0..1 string OS platform (Windows, Linux, etc.).

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

version 0..1 string OS version.

kernel 0..1 string Kernel ID.

56

Base Types and Interfaces

packageType

Summary:

A generic software package information. Agent supports different types of software packages,

including different varieties of the Linux specific packages, and Virtuozzo Containers specific

packages. When the 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 Package name.

summary 0..1 string Summary description.

os 0..1 osType (p. 55) Target OS and platform.

description 0..1 string Description.

arch 0..1 string Package architecture -- x86, x86_64,

etc.

version 0..1 string Package version.

Subtypes:

package_linuxType (p. 400)

package_rpmType (p. 400)

package_debType (p. 400)

package_vztemplateType (p. 625)

package_std_vztemplateType (p. 624)

57

Base Types and Interfaces

perf_dataType

Summary:

Contains data returned by the performance monitor.

Type specification:

Name Min/Max Type Description

eid 1..1 eid_type (p. 29) Server ID.

class 0..[] none A list of performance classes that

were selected for monitoring.

{

name 1..1 string Class name.

instance 1..[] none A list of class instances that were

selected for monitoring.

{

name 0..1 string Instance name.

counter 1..[] none A list of performance counters that

were selected for monitoring.

{

name 1..1 string Counter name.

value 1..1 perf_statType (p.

58)

Values.

}

interval 1..1 intervalType (p. 46)The time interval over which the data

was collected.

58

Base Types and Interfaces

perf_statType

Summary:

Performance statistics.

Type specification:

Name Min/Max Type Description

cur 1..1 anySimpleType Current value.

avg 1..1 anySimpleType Average value.

max 1..1 anySimpleType Maximum value.

min 1..1 anySimpleType Minimum value.

processesType

Summary:

Contains information about system processes.

Type specification:

Name Min/Max Type Description

run 1..1 int Number of processes in a "running" state.

zombie 1..1 int Number of processes in a "zombie" state.

sleep 1..1 int Number of processes in a "sleep" state.

uninterrupt 1..1 int Number of processes in a "uninterrupt"

state.

stopped 1..1 int Number of processes in a "stopped" state.

total 1..1 int Total number of processes.

59

Base Types and Interfaces

ps_infoType

Summary:

Contains information about system processes.

Type specification:

Name Min/Max Type Description

process 1..[] none Process information

{

pid 1..1 int Process identifier (PID).

param 0..[] base64Binary A list of process parameter values in

the order indicated by the list

contained in the param_id

element.

}

param_id 1..[] string 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 QoS counter ID.

soft 0..1 long Soft limit.

hard 0..1 long Hard limit.

cur 0..1 long Current value.

60

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

type 1..1 int 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.

name 1..1 string The name of the Realm (user defined).

builtin 0..1 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)

61

Base Types and Interfaces

resourceType

Summary:

A generic type for specifying a resource information.

Type specification:

Name Min/Max Type Description

total 0..1 long Total units available.

used 0..1 long Number of units currently used.

free 0..1 long Number if units currently available.

avg 0..1 long Average usage.

min 0..1 long Minimum units used.

max 0..1 long Maximum units used.

sample_confType

Summary:

Sample configuration information.

Type specification:

Name Min/Max Type Description

id 0..1 guid_type (p. 29) Sample configuration ID.

name 1..1 string Sample configuration name.

comment 0..1 base64Binary Comment.

env_config 1..1 env_configType (p. 37) Configuration parameters.

vt_version 0..1 Virtualization technology

information.

{

platform 1..1 string Platform (WIndows, Linux,

etc.).

architecture 1..1 string Architecture.

vt_technology 1..1 string Virtualization technology

name.

}

62

Base Types and Interfaces

security_descriptorType

Summary:

Security descriptor.

Type specification:

Name Min/Max Type Description

owner 1..1 sidType (p. 30)Security ID of a security object owner. The

owner is the user that is always allowed to

control the DACL of the object.

group 1..1 sidType (p. 30) Group security ID. It is used as a way of

tracking a group for each object providing

support for Linux permissions.

dacl 0..1 Discretionary Access Control List (DACL).

{

ace 0..[] aceType (p. 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.

63

Base Types and Interfaces

statsType

Summary:

Holds QoS data.

Type specification:

Name Min/Max Type Description

avg 0..1 long Average value

min 0..1 long Minimum value

max 0..1 long Maximum value

total 0..1 long Total value

cur 0..1 long Current value

soft 0..1 long Soft limit

hard 0..1 long Hard limit

64

Base Types and Interfaces

sys_infoType

Summary:

System information.

Type specification:

Name Min/Max Type Description

load_avg 1..1 load_avgType (p. 49) Load averages

processes 1..1 processesType (p. 58)Processes statistics

cpu_load 1..1 cpu_loadType (p. 35) CPU load statistics.

cpu_states 1..1 cpu_loadType (p. 35) CPU load statistics (percentage).

users 1..1 int Number of users.

uptime 1..1 long Uptime.

memory 0..1 resourceType (p. 61) Memory statistics. Provided only

for Hardware Node.

{

total 0..1 long Total memory available

used 1..1 long Memory used.

}

swap 0..1 resourceType (p. 61) Swap statistics. Provided only for

Hardware Node.

{

total 0..1 long Total.

used 1..1 long Used.

}

65

Base Types and Interfaces

system_nodeType

Summary:

Contains computer access parameters.

Type specification:

Name Min/Max Type Description

address 1..1 IP address.

{

ip 1..1 ip_type (p. 29) IP address.

}

login 0..1 Login info.

{

user 1..1 string User name.

password 1..1 base64Binary Password.

}

66

Base Types and Interfaces

tokenType

Summary:

Security token.

Type specification:

Name Min/Max Type Description

user 1..1 sidType (p. 30) SID of the token owner.

groups 0..1 The list of SIDs of the groups to

which the token owner belongs.

{

sid 1..[] sidType (p. 30) SIDs.

}

deny_only_sids 0..1 The list of deny-only SIDs.

{

sid 1..[] SIDs.

}

privileges 0..1 These fields are not currently used.

{

privilege 1..[] privilegeType (p.

29)

}

source 1..1 These fields are not currently used.

{

name 1..1 string

id 1..1 guid_type

}

67

Base Types and Interfaces

transferType

Summary:

Contains network transfer statistics.

Type specification:

Name Min/Max Type Description

input 1..1 none Incoming traffic.

{

bytes 1..1 long Number of bytes.

packets 0..1 long Number of packets.

}

output none Outgoing traffic.

{

bytes 1..1 long Number of bytes.

packets 0..1 long 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 Total units.

used 0..1 long Used units.

free 0..1 long Free units.

68

Base Types and Interfaces

userType

Summary:

User information.

Type specification:

Name Min/Max Type Description

initial_group 0..1 Initial group

{

name 0..1 string Group name

gid 0..1 int Group ID

}

group 0..[] Other groups.

{

name 0..1 string Group name.

gid 0..1 int Group ID.

}

uid 0..1 int User ID.

shell 0..1 string Shell.

password 0..1 base64Binary Password.

home_dir 0..1 string Home directory.

name 0..1 string User name.

comment 0..1 string Comment.

69

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..[] qosType (p. 59) QoS parameters.

Subtypes:

venv_configType (p. 627)

venv_configType (p. 695)

70

Base Types and Interfaces

voc_parameterType

Summary:

Contains an Agent vocabulary entry information.

Type specification:

Name Min/Max Type Description

id 1..1 string Vocabulary entry ID.

type 0..1 string Data type (int, string, etc.)

min 0..1 string Minimum possible value.

max 0..1 string Maximum possible value.

long 0..1 string Long description.

short 0..1 string Short description.

category 0..[] string Category.

complex 0..1 string Entry type-specific value. May have

different meaning for different types of

entries.

default 0..1 string Default value.

measure 0..1 string Units of measure.

data 0..1 Data (entry-type specific value).

vocabularyType

Summary:

Contains the Agent vocabulary data.

Type specification:

Name Min/Max Type Description

name 1..1 string The name of Agent plug-in that

this vocabulary is describing.

parameter 0..[] voc_parameterType (p.

563)

The vocabulary parameters.

category 0..[] voc_parameterType (p.

563)

The vocabulary categories.

71

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)

72

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.

73

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 eid_type (p. 29) Server ID.

class 1..1 string Performance class (see

perf_mon (p. 389) for more info

on this and the following

parameters).

instance 1..1 string Class instance.

counter 1..1 string Performance counter.

cur 1..1 anySimpleType Current value.

hard 1..1 anySimpleType Hard value.

soft 1..1 anySimpleType Soft value.

74

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 eid_type (p. 29) The ID of the Container that

caused the alert.

address 1..1 string The address of the slave node

hosting the Container specified in

the eid element (above).

title 1..1 string The title of the slave node.

description 1..1 string Problem description.

code 1..1 string 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.

75

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 eid_listType (p. 36)Server list.

category 0..1 string 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

<target>alertm</target>

<data>

<get_alerts>

<eid_list>

</eid_list>

</get_alerts>

76

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>

</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-8c64-

806e6f6e6963}\</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>

77

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

78

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 eid_listType (p.

36)

Server IDs. If omitted, subscribes to

receive alert notifications for all known

servers.

email 1..1 string The e-mail address to send the

notifications to.

name 0..1 string 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.

[ 0..1 This section specifies the alert type. If

the section is omitted, subscribes to

QoS alerts by default.

services 1..1 Get alerts on changing service status.

{

service 1..[] string 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.

79

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

<target>alertm</target>

<data>

<subscribe_alert>

<eid_list>

</eid_list>

<email>johndoe@mail.com</email>

<service>crond</service>

</services>

</subscribe_alert>

</alertm>

</data>

</packet>

Output

<origin>alertm</origin>

<data>

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

06T19:04:01+0000

Service crond changed status to stopped on ccc794ad-cc5d-49f2-8d84-6631263c81be at

2006-05-06T19:04:01+0000

80

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 eid_listType (p.

36)

Server ID list.

email 1..1 string E-mail that was used to subscribe

for alerts.

services 1..1 Cancel service status changes

alerts.

Returns:

OK/Error

Description

Use the unsubscribe_alert call if you would like to stop receiving alert notifications through e-

mail 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

<target>alertm</target>

<data>

<unsubscribe_alert>

<eid_list>

</eid_list>

<email>siarhei_rabtsau@epaml.com</email>

<service>crond</service>

</services>

</unsubscribe_alert>

</alertm>

</data>

</packet>

Output

81

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>

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

</src>

</packet>

authm

Purpose:

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

82

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 The IP address or the hostname of the

server hosting the directory.

port 1..1 int The TCP port at which the directory

instance is listening for requests.

base_dn 1..1 string Base DN. This is the top level of the

directory tree.

default_dn 1..1 string 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 0..1 loginType 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.

83

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

member_group 0..[] auth_nameType (p. 33) A list of member groups.

member_user 0..[] auth_nameType (p. 33) A list ot member users.

data 0..1 The user/group profile data.

{

attr 0..[] named_listType (p. 50) Attributes and their values. The

available attributes are determined

by the "database" used. In an

LDAP directory these would be

the attributes of an object

representing the user.

}

84

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 User/group name.

domain 0..1 base64Binary Domain name.

data 0..1 Attributes.

{

mod 0..[] modType (p. 50) 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.

}

85

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.

86

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

<target>authm</target>

<data>

<authm>

<add_group>

<group>

<name>VGVzdF9Hcm91cA==</name>

<data>

<attr>

<name>description</name>

<value>VGhpcyBpcyBhIHRlc3QgZ3JvdXA=</value>

</attr>

</data>

</group>

</add_group>

87

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>

88

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 realmType (p. 60) Realm information. Depending on

the realm type, use the appropriate

subtype of the realmType type (p.

60).

password 0..1 base64Binary 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

1 LDAP directory realm.

89

Base Types and Interfaces

name

myrealm Realm name.

address 192.168.0.117 The IP address of the server hosting the LDAP

directory.

port 398 TCP port number on which the directory

instance is listening for requests.

base_dn dc=vzl Base DN (the top level of the directory tree).

default_dn cn=users,dc=vzl Default DN (the default container in the directory

where the user information is stored).

login/name cn=pvaagent,dc=VZL The DN of the user that will be used to connect

to the directory instance to perform

authentications.

password bXlwYXNz 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>

<name>myrealm</name>

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

90

Base Types and Interfaces

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

91

Base Types and Interfaces

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 auth_nameType (p. 33) The inherited auth_nameType

portion is used to specify the

user/group to add to other groups

as a member.

{

group 1..[] auth_nameType (p. 33)Parent groups. The specified user

or group will be added as a

member to these groups.

}

Returns:

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

<target>authm</target>

<data>

<authm>

<add_to_group>

<name>VGVzdF9Vc2Vy</name>

<group>

<name>VGVzdF9Hcm91cA==</name>

</group>

</add_to_group>

</authm>

</data>

</packet>

Output

92

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>

</ns1:dst>

<ns1:data>

<ns2:authm>

<ns1:ok/>

</ns2:authm>

</ns1:data>

<src>

</src>

</packet>

93

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

(p. 83)

The new user information.

password 1..1 base64Binary 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

<target>authm</target>

<data>

<authm>

<add_user>

<user>

<name>VGVzdF9Vc2Vy</name>

<data>

<attr>

<name>description</name>

<value>VGhpcyBpcyBhIHRlc3QgdXNlcg==</value>

</attr>

94

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>

95

Base Types and Interfaces

authenticate

Summary:

Authenticates the specified user.

Request specification:

Name Min/Max Type Description

authenticate 1..1 auth_nameType (p.

33)

The inherited

auth_nameType portion is

used to specify the user login

information.

{

password 1..1 base64Binary 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

<target>authm</target>

<data>

<authm>

<name>VGVzdF9Vc2Vy</name>

<password>bXlwYXNz</password>

</authenticate>

</authm>

</data>

</packet>

Output

96

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>

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

</src>

</packet>

97

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 auth_nameType (p. 33) The member user or member

group information.

{

group 1..[] auth_nameType (p. 33) 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

<target>authm</target>

<data>

<authm>

<del_from_group>

<name>VGVzdF9Vc2Vy</name>

<group>

<name>Q049QWRtaW5pc3RyYXRvcnMsQ049Um9sZXMsREM9U1dB</name>

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

98

Base Types and Interfaces

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:authm>

<ns1:ok/>

</ns2:authm>

</ns1:data>

<src>

</src>

</packet>

99

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

<target>authm</target>

<data>

<authm>

<del_group>

<group>

<name>Q049VGVzdF9Hcm91cCxDTj1Sb2xlcyxEQz1TV0E=</name>

</group>

</del_group>

</authm>

</data>

</packet>

Output

<origin>authm</origin>

<target>vzclient1</target>

<dst>

</dst>

<data>

<authm>

<ok/>

</authm>

</data>

100

Base Types and Interfaces

<src>

</src>

</packet>

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

<target>authm</target>

<data>

<authm>

<del_realm>

</del_realm>

</authm>

</data>

</packet>

101

Base Types and Interfaces

del_user

Summary:

Permanently deletes the specified user(s) from their respective realms.

Call specification:

Name Min/Max Type Description

del_user

{

user 1..[] auth_nameType (p.

33)

The list of users to delete. You can

delete multiple users from multiple

realms at the same time -- simply

specify the user name and the

appropriate realm ID in each instance

of the structure.

}

Returns:

OK/Errors

Example:

Input

<target>authm</target>

<data>

<authm>

<del_user>

<user>

<name>VGVzdF9Vc2Vy</name>

</user>

</del_user>

</authm>

</data>

</packet>

102

Base Types and Interfaces

edit_group

Summary:

Modifies an existing group.

Request specification:

Name Min/Max Type Description

edit_group 1..1 auth_nameType (p.

33)

The auth_nameType portion of the

request specification is used to

specify the name/domain/realm

information about the group that you

would like to modify.

{

group 1..1 sp_modType (p. 84) The new group information. Includes

the name and the group attributes.

The attribute values can be added,

deleted, or replaced based on the

specified operation type. See

sp_modType (p. 81) for details.

}

Returns:

OK/Errors.

Example:

The following example modifies the description attribute value of the specified group.

Input

<target>authm</target>

<data>

<authm>

<edit_group>

<name>VGVzdF9Hcm91cA==</name>

<group>

<data>

<mod>

<type>description</type>

<value>VGhpcyBpcyBhIG5ldyBkZXNjcmlwdGlvbg==</value>

</mod>

</data>

</group>

</edit_group>

</authm>

</data>

</packet>

Output

103

Base Types and Interfaces

<?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="11c460a9dc5t2ea6r350"

time="2007-03-21T13:10:28+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>

<ns1:ok/>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

104

Base Types and Interfaces

edit_user

Summary:

Modifies an existing user.

Request specification:

Name Min/Max Type Description

edit_user 1..1 auth_nameType (p. 33)The auth_nameType portion of

the request specification is used

to specify the name/domain/realm

information about the user that

you would like to modify.

{

user 1..1 sp_modType (p. 84) The new user information.

Includes the user name and the

user attributes. The attribute

values can be added, deleted, or

replaced based on the specified

operation type. See sp_modType

(p. 81) for details.

password 0..1 base64Binary New password.

}

Returns:

OK/Error.

Example:

Modifying the existing user name and the value of the description attribute.

Input

<target>authm</target>

<data>

<authm>

<edit_user>

<name>VGVzdF9Vc2Vy</name>

<user>

<name>Sm9obiBEb2U=</name>

<data>

<mod>

<name>description</name>

<value>Sm9obiBEb2UgdXNlcg==</value>

</mod>

</data>

</user>

</edit_user>

</authm>

105

Base Types and Interfaces

</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="14c460a9eeft7e87r350"

time="2007-03-21T13:13:36+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>

<ns1:ok/>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

106

Base Types and Interfaces

get_auth_name

Summary:

Returns login information for the security account specified by its SID.

Request specification:

Name Min/Max Type Description

get_auth_name

{

sid 1..1 sidType (p. 30) Security ID (SID).

realm 0..1 guid_type (p.

29)

The ID of the realm in which you would

like to search for the user.

}

Returns:

Name Min/Max Type Description

auth_name 1..1 auth_nameType

(p. 33)

The security account login information.

Example:

Input

<target>authm</target>

<data>

<authm>

<get_auth_name>

<sid>AQQAAAAAAAXoAwAAQSVagwTHaUu6mzyE</sid>

</get_auth_name>

</authm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><ns1:packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

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="39c461cde46t63cbr1d8"

time="2007-04-11T13:10:39+0000" priority="0" version="4.0.0">

<ns1:origin>authm</ns1:origin>

<ns1:target>vzclient13</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:authm>

<ns2:auth_name xsi:type="ns3:auth_nameType">

<ns3:name>QWRtaW5pc3RyYXRvcgA=</ns3:name>

<ns3:realm>b5945e8a-68f9-48c2-827c-96af9549e46b</ns3:realm>

107

Base Types and Interfaces

</ns2:auth_name>

<ns2:type>1</ns2:type>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

108

Base Types and Interfaces

get_group

Summary:

Retrieves group information from the specified realm.

Request specification:

Name Min/Max Type Description

get_group

{

[ 1..1 Denotes a choice between the

group and the attr elements.

You have to include one of them,

you cannot execute the call without

any parameters.

group 1..1 auth_nameType (p.

33)

The group to retrieve the information

for. The group is specified by

supplying the group name, domain,

and realm information. Omit the

name parameter to retrieve all

groups from the specified realm. If

the name is included, only the

information for the specified group

will be retrieved.

attr 1..1 none This parameter can be used to

search for a group or multiple

groups having a particular attribute

set to a particular value. This applies

only to the groups stored in an

LDAP directory.

{

name 1..1 string Attribute name.

value 1..1 base64Binary Attribute value.

realm 1..1 guid_type (p. 29) The ID of the realm to conduct the

search in.

}

]

attrs 0..1 none The group attributes to include in

the result set. Omit this element to

retrieve just the names of a group (or

groups) without any attributes. Omit

the name element (below) to retrieve

all available attributes.

{

109

Base Types and Interfaces

name 0..[] string The list of attributes to include in the

result set. If a group doesn't have a

particular attribute value set, the

attribute will not be listed for that

group.

}

Returns:

Name Min/Max Type Description

group 1..[] security_principalType

(p. 83)

Group information.

Description:

The call retrieves the group information from the specified realm. The following actions are possible

depending on the options selected:

• Retrieving the list of all groups from the specified realm. This is achieved by including the

group element and specifying the realm ID.

• Retrieving the information for the specified group. This is achieved by including the group

element and specifying the group name and the realm ID.

• Searching for a group or multiple groups based on the value of an attribute of a group. For this,

include the attr element and specify the attribute name and value, and the realm ID to

conduct the search in.

Note: If you are using an external LDAP directory, you have to make sure that the groups are stored as

objects of class Group (objectClass=Group). If the group objects in your directory use a different

class, the get_group call will not find them.

Example:

Retrieving the list of all groups from the specified realm. Requesting to include the value of the

description attribute for every group in the result set.

Input

<target>authm</target>

<data>

<authm>

<get_group>

<group>

</group>

<attrs>

<name>description</name>

</attrs>

</get_group>

</authm>

</data>

110

Base Types and Interfaces

</packet>

Output

<packet xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

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="14c469df342t26e9r4b4"

time="2007-07-18T08:01:55+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>

<ns2:group>

<ns2:data>

<ns2:attr>

<ns2:name>description</ns2:name>

<ns2:value>VGhpcyBpcyBhIHRlc3QgZ3JvdXA=</ns2:value>

</ns2:attr>

</ns2:data>

<ns3:name>VGVzdF9Hcm91cA==</ns3:name>

<ns3:realm>3e761571-6607-1344-a064-a42679da8ed9</ns3:realm>

</ns2:group>

<ns2:group xsi:type="ns3:auth_nameType">

<ns3:name>VmlydHVvenpvIENvbnRyb2wgQ2VudGVyIFVzZXJz</ns3:name>

<ns3:realm>3e761571-6607-1344-a064-a42679da8ed9</ns3:realm>

</ns2:group>

<ns2:group>

<ns2:data>

<ns2:attr>

<ns2:name>description</ns2:name>

<ns2:value>VlpBZ2VudCBhZG1pbmlzdHJhdG9ycyBncm91cA==</ns2:value>

</ns2:attr>

</ns2:data>

<ns3:name>Y249dnphZG1pbmlzdHJhdG9ycyxjbj1CdWlsdGluLGRjPVZaTA==</ns3:name>

<ns3:realm>3e761571-6607-1344-a064-a42679da8ed9</ns3:realm>

</ns2:group>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</packet>

The next example demonstrates how to search for a group based on the value of a group attribute.

Here, we are searching for a group with the description attribute set to "Agent administrators

group".

Input

<target>authm</target>

<data>

<authm>

<get_group>

<attr>

<name>description</name>

<value>VlpBZ2VudCBhZG1pbmlzdHJhdG9ycyBncm91cA==</value>

111

Base Types and Interfaces

</attr>

</get_group>

</authm>

</data>

</packet>

Output

<packet xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

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="14c469df342t26e9r4b4"

time="2007-07-18T08:01:55+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>

<ns2:group>

<ns3:name>Y249dnphZG1pbmlzdHJhdG9ycyxjbj1CdWlsdGluLGRjPVZaTA==</ns3:name>

<ns3:realm>3e761571-6607-1344-a064-a42679da8ed9</ns3:realm>

</ns2:group>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</packet>

112

Base Types and Interfaces

get_realm

Summary:

Retrieves the list of the available Realms from the current Agent configuration.

Request specification:

Name Min/Max Type Description

get_realm 1..1

Returns:

Name Min/Max Type Description

realms

{

realm 1..[] realmType (p. 60) The list of the available realms. The

appropriate data type will be used for a

particular realm type (LDAP, System,

etc.). See the subtypes of the

realmType type (p. 60) for the

available realm types.

}

Description:

Use this call to retrieve the list of realms to present to the user during login (p. 508) or any other

operation requiring the realm ID as an input parameter. To get the list of realms during the initial

login to the system (p. 606), use the system/get_realm call (p. 597).

Example:

Input

<target>authm</target>

<data>

<authm>

<get_realm/>

</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:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/authm"

xmlns:ns4="http://www.swsoft.com/webservices/vzl/4.0.0/dirm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="23c4adff204tbb3r2c8" time="2009-10-22T05:48:20+0000">

<ns1:origin>authm</ns1:origin>

<ns1:target>vzclient60-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

113

Base Types and Interfaces

</ns1:dst>

<ns1:data>

<ns2:authm>

<ns2:realms>

<ns2:realm xsi:type="ns3:realmType">

<ns3:builtin/>

<ns3:name>System</ns3:name>

<ns3:type>0</ns3:type>

<ns3:id>00000000-0000-0000-0000-000000000000</ns3:id>

</ns2:realm>

<ns2:realm xsi:type="ns3:realmType">

<ns3:builtin/>

<ns3:name>Parallels Internal</ns3:name>

<ns3:type>4</ns3:type>

<ns3:id>00000000-0000-0000-0000-000000000005</ns3:id>

</ns2:realm>

<ns2:realm xsi:type="ns3:realmType">

<ns3:builtin/>

<ns3:name>Parallels Agent Internal</ns3:name>

<ns3:type>-1</ns3:type>

<ns3:id>00000000-0000-0000-0000-000000000006</ns3:id>

</ns2:realm>

<ns2:realm xsi:type="ns4:dir_realmType">

<ns4:login>

<ns4:domain>cWEuc3cucnU=</ns4:domain>

<ns4:name>YWRtaW5pc3RyYXRvcg==</ns4:name>

<ns4:realm>f3ddc2f0-0b5e-4220-b6a8-a26616ff3548</ns4:realm>

</ns4:login>

<ns3:name>DataBase</ns3:name>

<ns3:type>1</ns3:type>

<ns3:id>f3ddc2f0-0b5e-4220-b6a8-a26616ff3548</ns3:id>

<ns4:address>base.sw.ru</ns4:address>

<ns4:port>389</ns4:port>

<ns4:base_dn>sw.ru</ns4:base_dn>

<ns4:default_dn>sw.ru</ns4:default_dn>

</ns2:realm>

</ns2:realms>

</ns2:authm>

</ns1:data>

<src>

</src>

</packet>

114

Base Types and Interfaces

get_sid

Summary:

Returns SID of the security account specified by the login info.

Request specification:

Name Min/Max Type Description

get_sid

{

auth_name 1..1 auth_nameType (p.

33)

The login information of the security

account to search for.

}

Returns:

Name Min/Max Type Description

sid 1..1 sidType (p. 30) Security ID.

Example:

Input

<target>authm</target>

<data>

<authm>

<get_sid>

<auth_name>

<name>VGVzdF9Vc2Vy</name>

</auth_name>

</get_sid>

</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="17c460aa333t99r350"

time="2007-03-21T13:25:05+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:sid>AQUAAAAAA+hWW5a9ohIJQ6S9aykBIAAA9QEAAA==</ns2:sid>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

115

Base Types and Interfaces

</ns1:src>

</ns1:packet>

116

Base Types and Interfaces

get_user

Summary:

Retrieves user information from the specified realm.

Request specification:

Name Min/Max Type Description

get_user 1..1

{

[ 1..1 Denotes a choice between the user

and the attr elements.

user 1..1 auth_nameType (p.

33)

The user to retrieve the information for.

The user is specified by supplying the

user name, domain, and realm

information. Omit the name parameter

to retrieve all users from the specified

realm. If the name is included, only the

information for the specified user will

be retrieved.

attr 1..1 This parameter can be used to search

for a user or multiple users having a

particular attribute set to a particular

value. This applies only to the users

stored in an LDAP directory.

{

name 1..1 string The name of the attribute to search

for.

value 1..1 base64Binary Attribute value.

realm 1..1 guid_type (p. 29) The ID of the realm to conduct the

search in.

}

]

attrs 0..1 none The user attributes to include in the

result set. Omit this element to retrieve

just the names of a user (or users)

without any attributes. Omit the name

element (below) to retrieve all available

attributes.

{

name 0..[] string The list of attributes to include in the

result set. If a user doesn't have a

particular attribute value set, the

attribute will not be listed for that user.

}

117

Base Types and Interfaces

Returns:

Name Min/Max Type Description

user 1..[] security_princi

palType (p. 83)

User information.

Description:

The call retrieves the user information from the specified realm. The following actions are possible

depending on the options selected:

• Retrieving the list of all users from the specified realm. This is achieved by including the user

element and specifying the realm ID.

• Retrieving the information for the specified user. This is achieved by including the user element

and specifying the user name and the realm ID.

• Searching for a user or multiple users based on the value of an attribute of a user. For this,

include the attr element and specify the attribute name and value, and the realm ID to

conduct the search in.

Note: If you are using an external LDAP directory, you have to make sure that the users are stored as

objects of class User (objectClass=User). If the user objects in your directory use a different class,

the get_user call will not find them.

Example:

Retrieving the list of all users from the specified realm. Requesting to include the value of the

description attribute for every user in the result set.

Input

<target>authm</target>

<data>

<authm>

<get_user>

<user>

</user>

<attrs>

<name>description</name>

</attrs>

</get_user>

</authm>

</data>

</packet>

Output

118

Base Types and Interfaces

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

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="24c469e07f4t1547r4b4"

time="2007-07-18T08:59:11+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>

<ns2:user>

<ns2:data>

<ns2:attr>

<ns2:name>description</ns2:name>

<ns2:value>VGhpcyBpcyBhIHRlc3QgdXNlcg==</ns2:value>

</ns2:attr>

</ns2:data>

<ns3:name>VGVzdF9Vc2Vy</ns3:name>

<ns3:realm>3e761571-6607-1344-a064-a42679da8ed9</ns3:realm>

</ns2:user>

</ns2:authm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</packet>

119

Base Types and Interfaces

set_realm

Summary:

Modifies the specified realm definition.

Request specification:

Name Min/Max Type Description

set_realm

{

realm 1..1 realmType (p. 60) Realm information. Depending on

the realm type, use the appropriate

subtype of the realmType type (p.

60).

The realm/id parameter is

mandatory and must contain the ID

of the realm that you would like to

modify.

password 0..1 base64Binary The password for the user account

specified in the login portion of the

realm structure above.

}

Returns:

OK/Error.

Description:

The set_realm call allows to modify parameters that define an existing realm. You can change

realm name, connection parameters (address, port, etc.), login parameters, and password. For

more information on individual realm parameters see the add_realm call (p. 88).

Example:

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>

<set_realm>

<name>myrealm</name>

<base_dn>dc=vzl</base_dn>

<default_dn>cn=users,dc=vzl</default_dn>

120

Base Types and Interfaces

<login>

<name>Y249dnphZ2VudCxkYz1WWkw=</name>

</login>

</realm>

<password>bXlwYXNz</password>

</set_realm>

</authm>

</data>

</packet>

backup_storagem

Purpose:

The backup_storagem interface provides calls for configuring a backup storage.

Specification:

The interface is derived from the data_storagem interface (p. 195).

Calls

Call Description

get_storage_config (p. 197) Retrieves backup storage configuration.

set_storage_config (p. 197) Sets backup storage configuration.

backupm

Purpose:

The backup management interface.

121

Base Types and Interfaces

Types

backup_dataType

Summary:

Basic backup information. Used in get_info call (p. 156).

Type specification:

The type has no elements.

Subtypes:

env_backup_dataType (p. 127)

backup_options_baseType

Summary:

Base type for backup options.

Type specification:

The type has no elements.

Subtypes:

backup_optionsType (p. 122)

122

Base Types and Interfaces

backup_optionsType

Summary:

Backup options.

Type specification:

Extends backup_options_baseType (p. 121)

Adds the following elements:

Name Min/Max Type Description

type 0..1 int Backup type:

0 -- Full (default). A full backup

is a starting point for all other

backup types. You may define

the files and folders to be

backed up using the

include/exclude options (see

below).

1 -- Incremental. Only the files

that have changed since the

latest full, incremental, or

differential backup are

included. When restoring from

an incremental backup, you'll

need the latest full backup as

well as every incremental

and/or differential backup that

you've made since the last full

backup.

2 -- Differential. Only the files

that have changed since the

last full backup are included.

When restoring from a

differential backup, only the

latest differential backup itself

and the latest full backup is

needed.

policy 0..1 Backup policy.

{

ignore_error 0..1 none A flag indicating not to stop on

error when backing up multiple

servers. If an individual server

backup fails, the operation will

proceed with the next server in

the list.

123

Base Types and Interfaces

ignore_unexistent 0..1 none A flag indicating not to produce

an error if one of the servers in

the list does not exist. If this

element is absent and the list

contains an invalid Server ID,

the batch backup operation will

stop with an error.

}

remove 0..1 If present, defines the old

backup of the specified server

to be removed from the backup

server.

{

backup 0..1 string Backup ID to remove. If this

element is absent, the oldest

backup from this sequence will

be removed.

}

include_list 0..1 Files and directories to include

in the backup. Use this option

when you want to backup only

the select files and directories.

{

path 1..[] base64Binary A list of files and directories to

include in the backup.

Wildcards are permitted.

}

exclude_list 0..1 exclude_listT

ype (p. 129)

Files and directories to exclude

from the backup. The list

provides various options that

can be used individually or in

any combination.

compression 0..1 int Compression level:

0 -- no compression

1 -- normal (default)

2 -- high

3 -- maximum

description 0..1 base64Binary Backup description.

124

Base Types and Interfaces

backupid_type

Summary:

Backup ID.

Type specification:

Restriction: ds_object_path_type (p. 196)

125

Base Types and Interfaces

backupm_configType

Summary:

Contains the backup configuration information.

Type specification:

Name Min/Max Type Description

backup_server 1..1 connection_infoTyp

e (p. 34)

Backup server connection

information.

chain_length 0..1 int Maximum number of

incremental backups in any

given backup sequence. When

this number is exceeded, a

new backup sequence must

be started beginning with a full

backup.

chain_days 0..1 int Maximum number of days an

incremental backup sequence

may continue uninterrupted.

When this number is

exceeded, a new sequence

must be started beginning with

a new backup.

keep_max 0..1 int The maximum number of

backup archives for a given

server that should be kept on

the backup server. When this

number is exceeded, the

oldest backup file is

automatically removed on

every successful new backup.

compression 0..1 int The default compression level.

See backup_optionsType

(p. 122) for the available

compression levels.

type 0..1 int Default backup type. See

b

ackup

_

optionsType (p.

122) for the list of backup

types.

pe_backups_limit 0..1 none The maximum number of

backups a user can perform

on a single server, be it a

Parallels Virtuozzo for

Linux/Windows, or Parallels

Server physical server.

126

Base Types and Interfaces

backupType

Summary:

Backup information.

Type specification:

Extends ds_object_infoType (p. 196)

Adds the following elements:

Name Min/Max Type Description

eid 1..1 eid_type (p. 29) Server ID.

description 0..1 base64Binary Backup description.

count 1..1 int The total number of backups

for this server in this storage.

capability 0..1 Backup capabilities. Specifies

miscellaneous backup

properties.

{

browsable 0..1 none A flag indicating that the

contents of this backup can be

listed using the filer/list

call (p. 284), and can be

restored using the

selective_restore_env

call (p. 146).

}

127

Base Types and Interfaces

env_backup_dataType

Summary:

Contains a server-specific backup information. Used in get_info call (p. 156).

Type specification:

Extends backup_dataType (p. 121)

Adds the following elements:

Name Min/Max Type Description

env 0..1 envType (p. 39) The server information.

include_list 0..1 A list of files and directories

that were listed in the

include_list element in

the original backup request

(p. 122).

{

path 1..[] base64Binary Pathnames (may contain

wildcards).

}

exclude_list 0..1 exclude_listType

(p. 129)

A list of files and directories

that were listed in the

exclude_list element in

the original backup request

(p. 122).

128

Base Types and Interfaces

get_env_info_optionsType

Summary:

Server-specific options for get_info call (p. 156).

Type specification:

Extends get_info_optionsType (p. 129)

Adds the following elements:

Name Min/Max Type Description

env 0..1 none If this element is present, the get_info

call returns the full server information.

excludes 0..1 none If present, the get_info call returns the

names of files and directories that were

included in or excluded from the backup.

See exclude_list and include_list

in backup_optionsType (p. 122) for

more info.

129

Base Types and Interfaces

exclude_listType

Summary:

Contains files and directories to exclude from backup.

Type specification:

Name Min/Max Type Description

path 0..[] base64Binary List of files and directories to

exclude from backup.

hidden 0..[] none If this element is present, all hidden

files will be excluded from the

backup.

system 0..1 none If this element is present, all system

files will be excluded from the

backup.

This option may not be available for

all server types. You can check

whether this option is available or

not for a particular server type by

searching the Agent vocabulary for

the backup.exclude.system

entry. If the entry is present, then the

feature is available. To retrieve the

vocabulary, use the

get_vocabulary call (p. 603).

get_info_optionsType

Summary:

Basic options for get_info call (p. 156).

Type specification:

This is an abstract type. Use the appropriate subtype of this type when executing the get_info

call (p. 156).

Subtypes:

get_env_info_optionsType (p. 128)

130

Base Types and Interfaces

list_optionsType

Summary:

Backup list retrieval options.

Type specification:

Name Min/Max Type Description

eid 0..1 eid_type (p. 29) Server ID to list the backups for.

latest 0..1 none If this element is present, only the

latest backup for each existing

Container (or the Container

specified in the eid element

above) will be included in the

result. If this element is omitted,

the list will contain all of the

available backups -- old and new.

info 0..1 none If this element is present, the

additional backup information will

be retrieved, if available. The

information will be included in the

info element of the backup

return structure (p. 149).

storage_eid 0..1 eid_type (p. 29) The Server ID of the slave Node in

the Virtuozzo group from which to

retrieve the list of backups. The

parameter can be used only when

the list call (p. 149) is executed

on the Master Node in the group.

When retrieving a list of backups

from a standalone Hardware

Node, this parameter has no

effect.

131

Base Types and Interfaces

remove_optionsType

Summary:

Backup removal options.

Type specification:

Name Min/Max Type Description

eid 0..1 eid_type (p. 29) Server ID. If this element is included, the

remove call (p. 152) will search for all

backups of the specified server and will

remove all of them.

prev 0..1 none If this element is included, and the

backup_id element of the remove call

(p. 152) is included as well, the call will

find and remove all prior backups of the

same server that the specified

backup_id belongs to. In all other cases,

the element is ignored.

restore_optionsType

Summary:

Backup restoration options.

Type specification:

Name Min/Max Type Description

force 0..1 none Force the restore operation. If the element is

present, the procedure will try to resolve

potential conflicts, or ignore them if no

resolution is possible. The conflicts may arise

due to a duplicate server name or a Virtuozzo

Container ID (veid).

132

Base Types and Interfaces

search_optionsType

Summary:

Backup search options.

Type specification:

Name Min/Max Type Description

hostname 0..1 string Server hostname (wildcards

supported).

ip 0..1 string Server IP address. (wildcards

supported).

start_date 0..1 datetimeType Search with specified backup

creation date range.

end_date 0..1 datetimeType Search with specified backup

creation date range.

selective_restore_optionsType

Summary:

Selective restore options.

Type specification:

Name Min/Max Type Description

skip_locked 0..1 none If this element is included, the restore

operation will not stop on error while trying

to restore a locked file. If the element is

omitted, an attempt to restore a locked file

will produce an error and the entire

operation will be canceled.

133

Base Types and Interfaces

Calls

Call Description

backup_env (p. 134) Backs up a server.

restore_env (p. 141) Restores a server.

selective_restore_env (p. 146) Selectively restores individual files from a backup.

list (p. 149) Retrieves backup information.

remove (p. 152) Removes a backup.

search (p. 154) Searches for a server backup.

get_info (p. 156) Gets extended information about a backup.

set_config (p. 157) Sets the backup manager configuration.

get_config (p. 159) Retrieves the backup manager configuration information.

134

Base Types and Interfaces

backup_env

Summary:

Backs up a server. You may specify multiple servers to back up at the same time.

Request specification:

Name Min/Max Type Description

backup_env

{

env_list 1..1 eid_listType (p. 36) Servers to backup.

backup_options 0..1 backup_options_baseT

ype (p. 121)

Backup options.

backup_server 0..1 connection_infoType

(p. 34)

Backup server connectivity

information for remote

backups. If this element is

omitted, the default backup

server configuration will be

used. To retrieve the default

configuration, use the

get_configuration (p.

585) call.

}

Returns:

Name Min/Max Type Description

backup 0..[] backupType (p. 126) Backup details.

When backing up multiple

servers, a mix of the backup

and error information may be

returned.

Description:

The call provides a set of options that allow you to control the backup operation. The options

include replacing a specific old backup archive, backing up only the directories that you need,

excluding the files and directories that you don't need, setting the compression level, and others.

See backup_optionsType (p. 122) for the complete list of options.

Since a backup operation can take a significant amount of time, you may optionally include the

progress="on" attribute and specify the packet ID to receive the progress information. The

progress information will be sent to your client program via a series of responses using the

progress packet (p. 616).

Example:

135

Base Types and Interfaces

Performing a full backup of the specified Virtuozzo Container. Setting a compression level to "high".

Backing up to the default defined backup server.

Input

<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/backupm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" progress="on"

log="on" id="2">

<ns1:target>backupm</ns1:target>

<ns1:data>

<ns1:backupm>

<ns1:backup_env>

<ns1:env_list>

<ns1:eid>ced92df6-3921-f74c-a221-43045c9c568d</ns1:eid>

</ns1:env_list>

<ns1:backup_options xsi:type="ns2:backup_optionsType">

<ns2:type>0</ns2:type>

<ns2:compression>2</ns2:compression>

<ns2:description>RnVsbCBiYWNrdXAgMjAwNy0wMS0xMg==</ns2:description>

</ns1:backup_options>

</ns1:backup_env>

</ns1:backupm>

</ns1:data>

</ns1:packet>

Progress Messages

The following are some of the progress messages that we received in this example (the actual XML

packets are not listed here for brevity):

Operation backup_env is started

Checking parameters

Dumping quota

Backup storage: preparing to backup

Adjusting backup type (full)

Backup storage: receiving backup file

Backing up private area.

// Some progress percent messages were received here...

Percent: 2

...

Percent: 54

...

Percent: 99

....

Backup storage: storing private backup data

Backup storage: filling resultant backup info

The following is the actual example of a packet containing a progress message.

<ns1:packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="2" time="2007-02-

16T16:14:04+0000" type="1" priority="4000" version="4.0.0">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

136

Base Types and Interfaces

<ns1:progress>

<ns1:op>backupm.backup_env</ns1:op>

<ns1:message>

<ns1:message>T3BlcmF0aW9uICVvcF9uYW1lJSBpcyAlc3RhdHVzJQ==</ns1:message>

<ns1:name></ns1:name>

<ns1:translate/>

<ns1:parameter>

<ns1:message>YmFja3VwX2Vudg==</ns1:message>

<ns1:name>op_name</ns1:name>

</ns1:parameter>

<ns1:parameter>

<ns1:message>c3RhcnRlZA==</ns1:message>

<ns1:name>status</ns1:name>

<ns1:translate/>

</ns1:parameter>

</ns1:message>

<ns1:status>1</ns1:status>

</ns1:progress>

</ns1:data>

<ns1:target>log_subscription</ns1:target>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Output

The following is a packet received on the backup operation completion. The packet contains the

backup information, including the information about the server that was backed up, the backup ID,

backup archive size, backup type, and other info.

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/progress_event"

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:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="4000"

type="1" time="2010-11-26T02:37:50+0000" id="cc4cefc662t5af1r4c4">

<origin>backupm</origin>

<target>vzclient23-89bc4bb1-6e87-6271-fd2e-a332696dae7a</target>

<dst>

</dst>

<data>

<op>backupm.backup_env</op>

<message>T3BlcmF0aW9uIHdpdGggdGhlIENvbnRhaW5lciAlZW52JSBpcyAlc3RhdHVzJQ==</message>

<message>JXRpdGxlJQ==</message>

<message>Y2VkOTJkZjYtMzkyMS1mNzRjLWEyMjEtNDMwNDVjOWM1Njhk</message>

</parameter>

137

Base Types and Interfaces

<message>IzExMQ==</message>

<name>title</name>

</parameter>

<message>dmlydHVvenpv</message>

</parameter>

<message>YmFja3VwbS5iYWNrdXBfZW52</message>

</parameter>

<message>JXRpdGxlJQ==</message>

<name>source_env</name>

<message>ODliYzRiYjEtNmU4Ny02MjcxLWZkMmUtYTMzMjY5NmRhZTdh</message>

</parameter>

<message>UFZBNHdpbnNlcnYubWVnYXdpbjYuc3cucnU=</message>

<name>title</name>

</parameter>

<message>Z2VuZXJpYw==</message>

</parameter>

<message>c3RhcnRlZA==</message>

<name>status</name>

</parameter>

</message>

<eid_list>

</eid_list>

</progress>

</data>

<target>log_subscription</target>

<src>

</src>

</packet>

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/progress_event"

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:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="4000"

type="1" time="2010-11-26T02:37:50+0000" id="cc4cefc662t5af1r4c4">

138

Base Types and Interfaces

<origin>backupm</origin>

<target>vzclient23-89bc4bb1-6e87-6271-fd2e-a332696dae7a</target>

<dst>

</dst>

<data>

<message>QmFja2luZyB1cCBlbnZpcm9ubWVudCAjMTExIGxvY2FsbHk=</message>

<message>JXRpdGxlJQ==</message>

<name>source_env</name>

<message>ODliYzRiYjEtNmU4Ny02MjcxLWZkMmUtYTMzMjY5NmRhZTdh</message>

</parameter>

<message>UFZBNHdpbnNlcnYubWVnYXdpbjYuc3cucnU=</message>

<name>title</name>

</parameter>

<message>Z2VuZXJpYw==</message>

</parameter>

</message>

</progress>

</data>

<target>log_subscription</target>

<src>

</src>

</packet>

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/data_storagem"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/backupm"

xmlns:ns4="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="4000"

id="cc4cefc662t5af1r4c4" type="0" time="2010-11-26T02:38:50+0000">

<origin>backupm</origin>

<target>vzclient23-89bc4bb1-6e87-6271-fd2e-a332696dae7a</target>

<dst>

</dst>

<data>

139

Base Types and Interfaces

<description>RnVsbCBiYWNrdXAgMjAwNy0wMS0xMg==</description>

</capability>

<storage_eid>a91bcfea-3de2-ba43-859a-26f58f14706e</storage_eid>

<message>TGludXg=</message>

<name>platform</name>

</parameter>

<message>YTkxYmNmZWEtM2RlMi1iYTQzLTg1OWEtMjZmNThmMTQ3MDZl</message>

<name>parent_eid</name>

</parameter>

<message>dG1hcmtpbi5zdy5ydQ==</message>

<name>parent_env_title</name>

</parameter>

<message>dG1hcmtpbi5zdy5ydQ==</message>

<name>storage_title</name>

</parameter>

<message>Z2VuZXJpYw==</message>

<name>storage_type</name>

</parameter>

<message>IzExMQ==</message>

<name>title</name>

</parameter>

<message>dmlydHVvenpv</message>

</parameter>

</parameter>

</info>

140

Base Types and Interfaces

</backup>

</backupm>

</data>

<src>

</src>

</packet>

141

Base Types and Interfaces

restore_env

Summary:

Restores a server from a backup.

Request specification:

Name Min/Max Type Description

restore_env

{

backup_id 1..1 backupid_type (p. 124) Backup ID. The ID is

generated and returned to

the client program at the end

of the backup operation (p.

134). To get the list of the

existing backups, use the

list call (p. 149). To search

for backups of a particular

server, use the search call

(p. 154).

restore_options 0..1 restore_optionsType

(p. 131)

Restore options.

backup_server 1..1 connection_infoType

(p. 34)

Backup server connectivity

information for remote

backups. If this element is

omitted, the default backup

server configuration will be

used. To retrieve the default

configuration, use the

get_configuration (p.

585) call.

142

Base Types and Interfaces

parent_eid 0..1 eid_type (p. 29) This parameter is used only

when restoring a Container

within a Virtuozzo group.

Normally, in a Virtuozzo

group, a Container is

restored to the original

Hardware Node. If the

original Hardware Node is not

found, the restore operation

will fail. In such a situation,

you can use this parameter

to specify the alternate

Hardware Node to which to

restore the Container. The

following conditions apply:

1. The call must be executed

on the Master Node in the

group.

2. If the original Hardware

Node exists, this parameter

will be ignored.

target 0..1 eid_type (p. 29) The globally unique ID to

assign to the restored server.

If this parameter is omitted,

the restored server will have

the same ID as the original

server. If this parameter is

specified, the restored server

will be assigned the specified

ID.

You have to choose a

globally unique ID that's not

used by any other server.

Please note that reassigning

a server ID is a special case

scenario, which should be

handled with care.

}

Returns:

OK/Error

Description:

Use the restore_env call to restore a server from a backup. The backup that you are restoring

from must be one of the following:

• A full backup containing all the files and directories that are required for the server to operate

properly.

143

Base Types and Interfaces

• An incremental backup, plus all the prior incremental and differential backups, and the original

full backup from the same sequence.

• A differential backup, plus the original full backup from the same sequence.

By default, a server will be restored to the host that you are currently connected to. In a Virtuozzo

group, a server will be restored to the original Node. If the original Node is no longer registered with

the group, use the parent_eid parameter to specify an alternate Node.

You may set the progress="on" and the id arguments in the packet element of the message

header if you would like to receive the progress reports during the restore operations.

Example:

Restoring a server from the specified backup located on the default backup server. The server will

be restored to the host that we are currently connected to.

Input

<target>backupm</target>

<data>

<restore_env>

<backup_id>57c2cd6c-c02b-4645-bdb5-e883ea005896/20070219150134</backup_id>

<restore_options>

</restore_options>

</restore_env>

</backupm>

</data>

</packet>

Progress messages

The following is an example of one of the progress reports. When decoded, the message reads:

Operation restore_env started.

See backup_env (p. 134) and progress packet (p. 616) for more info on progress messages.

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/progress_event"

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:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="4000"

type="1" time="2009-10-22T14:53:40+0000" id="b8c4ae071det2fffr2c8">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient67-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:op>backupm.restore_env</ns2:op>

<ns2:message xsi:type="ns3:infoType">

144

Base Types and Interfaces

<ns3:message>T3BlcmF0aW9uIHdpdGggdGhlIENvbnRhaW5lciAlZW52JSBpcyAlc3RhdHVzJQ==</ns3:mess

age>

<ns3:name></ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>JXRpdGxlJQ==</ns3:message>

<ns3:name>env</ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>ODdhZjY0MGEtZjE1MS0yODQ0LTg2M2ItYzdmNDE1M2Q3OWI0</ns3:message>

<ns3:name>eid</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>Q1QzbGluUFNCTQ==</ns3:message>

<ns3:name>title</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>dmlydHVvenpv</ns3:message>

<ns3:name>type</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>YmFja3VwbS5yZXN0b3JlX2Vudg==</ns3:message>

<ns3:name>op_name</ns3:name>

</ns3:parameter>

<ns3:parameter>

<ns3:message>JXRpdGxlJQ==</ns3:message>

<ns3:name>source_env</ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>MmZhYmUxOTQtMDQ3Ny0wODcxLWEzMmQtNDkyMjAwNTBjZjVj</ns3:message>

<ns3:name>eid</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>bWNjcDQx</ns3:message>

<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:message>c3RhcnRlZA==</ns3:message>

<ns3:name>status</ns3:name>

<ns3:translate/>

</ns3:parameter>

</ns2:message>

<ns2:status>1</ns2:status>

<ns2:eid_list>

<ns3:eid>87af640a-f151-2844-863b-c7f4153d79b4</ns3:eid>

</ns2:eid_list>

145

Base Types and Interfaces

</progress>

</ns1:data>

<target>log_subscription</target>

<src>

</src>

</packet>

Output

The following "OK" message is received on successful restoration.

<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/backupm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="bc45dc4ddbt6df1r488"

time="2009-10-22T14:54:04+0000" priority="4000" version="4.0.0">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:backupm>

<ns1:ok/>

</ns2:backupm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

146

Base Types and Interfaces

selective_restore_env

Summary:

Selectively restore files from a backup.

Request specification:

Name Min/Max Type Description

selective_restore_env

{

eid 1..1 eid_type (p. 29) The ID of the server to

restore the selected

files to.

backup_id 1..1 backupid_type

(p. 124)

Backup ID. The ID is

generated and

returned to the client

program at the end of

the backup operation

(p. 134). To get the list

of the existing

backups, use the

list call (p. 149). To

search for backups for

a particular server, use

the search call (p.

154).

path 1..[] base64Binary A list of files and

directories to restore.

Wildcards are

permitted.

selective_restore_options 0..1 selective_rest

ore_optionsTyp

e (p. 132)

Restore options.

backup_server 0..1 connection_inf

oType (p. 34)

Backup server

connectivity

information for remote

backups. If this

element is omitted, the

default backup server

configuration will be

used. To retrieve the

default configuration,

use the

get_configuratio

n (p. 585) call.

}

Returns:

OK/Error

147

Base Types and Interfaces

Description:

Use the selective_restore_env call to restore only the files and directories that you need or

to restore from a backup that does not contain all the files and directories that are required for the

server to operate properly. There are some important differences between the regular

restore_env call (p. 141) and this call.

First of all, since you can only restore the files into an existing server, you must specify its Server ID.

If the server doesn't exist, or cannot be found, the call will fail. Please note that the call will try to

locate the specified server on the current host. Even if you execute the call on the Master Node in a

Virtuozzo group, it will still look for the specified target server on the Master Node only. If your

server is hosted by another node in a group, you will have to connect to it directly or provide its ID

via the dst element in the message header.

You always have to specify the files and directories that you would like to restore. In addition, you

may restore the files and directories into any available server of the same type as the original server.

As with other backup and restore operations, you may set the progress="on" and the id

arguments in the packet element of the message header if you would like to receive progress

reports during the restore operations.

Note: You can use the selective restore operation only with the backups that are capable of it. Use the

list call (p. 149) to get the backup information and look for the capabilities/browsable flag (p.

126) in the result set. If the element is present, the selective restore operation can be performed on the

backup.

Example:

Restoring the /var/tmp directory from the specified backup into the specified Virtuozzo

Container.

Input

<target>backupm</target>

<data>

<selective_restore_env>

<backup_id>57c2cd6c-c02b-4645-bdb5-e883ea005896/20070219150134</backup_id>

</selective_restore_env>

</backupm>

</data>

</packet>

Progress messages:

The following is an example of one of the progress reports (this was the last progress message

received, actually). When decoded, the message reads as follows:

Operation selective_restore_env finished successfully.

148

Base Types and Interfaces

See backup_env (p. 134) and progress packet (p. 616) for more info on progress messages.

<ns1:packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="cc45dc6bdbt5af1r488"

time="2007-02-20T09:00:16+0000" type="1" priority="4000" version="4.0.0">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns1:progress>

<ns1:op>backupm.selective_restore_env</ns1:op>

<ns1:message>

<ns1:message>T3BlcmF0aW9uICVvcF9uYW1lJSBpcyAlc3RhdHVzJSBzdWNjZXNzZnVsbHku</ns1:message>

<ns1:name></ns1:name>

<ns1:translate/>

<ns1:parameter>

<ns1:message>c2VsZWN0aXZlX3Jlc3RvcmVfZW52</ns1:message>

<ns1:name>op_name</ns1:name>

</ns1:parameter>

<ns1:parameter>

<ns1:message>ZmluaXNoZWQ=</ns1:message>

<ns1:name>status</ns1:name>

<ns1:translate/>

</ns1:parameter>

</ns1:message>

<ns1:percent>100</ns1:percent>

<ns1:status>3</ns1:status>

</ns1:progress>

</ns1:data>

<ns1:target>log_subscription</ns1:target>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Output

The final "OK" response on operation completion.

<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/backupm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="cc45dc6bdbt5af1r488"

time="2007-02-20T09:00:16+0000" priority="4000" version="4.0.0">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:backupm>

<ns1:ok/>

</ns2:backupm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

149

Base Types and Interfaces

list

Summary:

Retrieves backup information.

Request specification:

Name Min/Max Type Description

list

{

backup_id 0..[] backupid_type (p. 124) List of backup IDs to retrive

the information for. If this

element is omitted, the

information about all available

backups will be retrieved.

options 0..1 list_optionsType (p.

130)

List options. Use the options

provided by this element as a

filter to retrieve the

information that you require.

}

Returns:

Name Min/Max Type Description

backup 0..[] backupType (p. 126) Backup information.

Description:

If you are connected to the master node in a Virtuozzo group, the call retrieves information about all

backups in the group. In all other cases, the call retrieves only the backups that are stored on the

machine that you are connected to. If you are connected to a slave node but want to retrieve the

information from a backup server located elsewhere, you must connect to it directly and execute

the call there.

Example:

Retrieving information about the latest backup of the specified Virtuozzo Container.

Input

<target>backupm</target>

<data>

<list>

</options>

</list>

</backupm>

150

Base Types and Interfaces

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/data_storagem"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/backupm"

xmlns:ns4="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="6ac4ae03d97t3bf6r2c8" time="2009-10-22T11:10:41+0000">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient65-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:backupm>

<ns2:backup>

<ns2:eid>87af640a-f151-2844-863b-c7f4153d79b4</ns2:eid>

<ns2:description>M3JkIHJlbW90ZSBvbiB3Mms4</ns2:description>

<ns2:count>3</ns2:count>

<ns2:capability>

<ns2:browsable/>

</ns2:capability>

<ns3:id>87af640a-f151-2844-863b-c7f4153d79b4/20091020094521</ns3:id>

<ns3:time>2009-10-20T09:45:21+0000</ns3:time>

<ns3:size>4386538</ns3:size>

<ns3:type>0</ns3:type>

<ns3:storage_eid>a6f1d061-8bcd-8ec7-1a73-b078fe2d416f</ns3:storage_eid>

<ns3:info xsi:type="ns4:infoType">

<ns4:message></ns4:message>

<ns4:name></ns4:name>

<ns4:translate/>

<ns4:parameter>

<ns4:message>Q1QzbGluUFNCTQ==</ns4:message>

<ns4:name>hostname</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>MTAuMzEuMzIuMTA=</ns4:message>

<ns4:name>ip</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>Q1QzbGluUFNCTQ==</ns4:message>

<ns4:name>name</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message></ns4:message>

<ns4:name>os</ns4:name>

<ns4:parameter>

<ns4:message>TGludXg=</ns4:message>

<ns4:name>platform</ns4:name>

</ns4:parameter>

<ns4:parameter>

<ns4:message>ZTdiZWFiZTQtODljNS1iYzQyLWI0NWEtY2E4NTQ0OWIzZWI1</ns4:message>

<ns4:name>parent_eid</ns4:name>

151

Base Types and Interfaces

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>bWNjcDI1LnFhLnN3LnJ1</ns4:message>

<ns4:name>parent_env_title</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>bWNjcDQ0</ns4:message>

<ns4:name>storage_title</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>Z2VuZXJpYw==</ns4:message>

<ns4:name>storage_type</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>Q1QzbGluUFNCTQ==</ns4:message>

<ns4:name>title</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>dmlydHVvenpv</ns4:message>

<ns4:name>type</ns4:name>

</ns4:parameter>

<ns4:parameter>

<ns4:message>Njg5MzUyNQ==</ns4:message>

<ns4:name>veid</ns4:name>

<ns4:translate/>

</ns4:parameter>

</ns3:info>

</ns2:backup>

</ns2:backupm>

</ns1:data>

<src>

</src>

</packet>

152

Base Types and Interfaces

remove

Summary:

Removes a backup archive.

Request specification:

Name Min/Max Type Description

remove

{

backup_id 0..1 backupid_type (p. 124) The ID of the backup to be

removed.

options 0..1 remove_optionsType (p.

131)

Removal options.

}

Returns:

OK/Error

Description:

If you are connected to the master node in a Virtuozzo group, the call can remove any backup

stored on any physical node in a cluster. In all other cases, the call can remove only the backups

that are stored locally. If you are connected to a slave node but want to remove a backup from a

machine located elsewhere, you must connect to it directly and execute the call there.

To remove a specific backup, supply the backup ID using the backup_id element. If, at the same

time, you'll also include the options/prev element, the call will automatically determine the

server that the specified backup belongs to, and will remove all prior backups that belong to the

same server.

To remove all of the backups for a specific server, specify its Server ID using the options/eid

element.

Example 1:

Removing the specified backup archive.

<target>backupm</target>

<data>

<backup_id>57c2cd6c-c02b-4645-bdb5-e883ea005896/20070219170146</backup_id>

</remove>

</backupm>

</data>

</packet>

153

Base Types and Interfaces

Example 2:

Removing a backup archive and all the prior backups belonging to the same server.

<target>backupm</target>

<data>

<backup_id>57c2cd6c-c02b-4645-bdb5-e883ea005896/20070219170146</backup_id>

<prev/>

</options>

</remove>

</backupm>

</data>

</packet>

Example 3:

Removing all backups belonging to the specified server.

<target>backupm</target>

<data>

</options>

</remove>

</backupm>

</data>

</packet>

154

Base Types and Interfaces

search

Summary:

Searches existing backup archives for a specific server.

Request specification:

Name Min/Max Type Description

search

{

options 1..1 search_optionsType (p.

120)

Search options. You may

specify any option or any

combination of the options.

}

Returns:

Backup information if the specified server was found or an empty structure otherwise.

Name Min/Max Type Description

backup 0..[] backupType (p. 126) Backup information.

Description:

If you are connected to the master node in a Virtuozzo group, the call will search through all

backups located on every physical node. If you are connected to a slave node, the call will perform

the search locally. To search for a backup on a backup server located elsewhere, connect to that

server and execute the call there.

Example:

Searching backups by the hostname of the server.

Input

<target>backupm</target>

<data>

</options>

</search>

</backupm>

</data>

</packet>

Output

155

Base Types and Interfaces

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/data_storagem"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/backupm"

xmlns:ns4="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="77c4ae046e6t366br2c8" time="2009-10-22T11:50:23+0000">

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient65-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:backupm>

<ns2:backup>

<ns2:eid>87af640a-f151-2844-863b-c7f4153d79b4</ns2:eid>

<ns2:description>M3JkIHJlbW90ZSBvbiB3Mms4</ns2:description>

<ns2:count>3</ns2:count>

<ns2:capability>

<ns2:browsable/>

</ns2:capability>

<ns3:id>87af640a-f151-2844-863b-c7f4153d79b4/20091020094521</ns3:id>

<ns3:time>2009-10-20T09:45:21+0000</ns3:time>

<ns3:size>4386538</ns3:size>

<ns3:type>0</ns3:type>

<ns3:storage_eid>a6f1d061-8bcd-8ec7-1a73-b078fe2d416f</ns3:storage_eid>

<ns3:info xsi:type="ns4:infoType">

<ns4:message></ns4:message>

<ns4:name></ns4:name>

<ns4:translate/>

<ns4:parameter>

<ns4:message>Q1QzbGluUFNCTQ==</ns4:message>

<ns4:name>hostname</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>MTAuMzEuMzIuMTA=</ns4:message>

<ns4:name>ip</ns4:name>

<ns4:translate/>

</ns4:parameter>

<ns4:parameter>

<ns4:message>Q1QzbGluUFNCTQ==</ns4:message>

<ns4:name>name</ns4:name>

<ns4:translate/>

</ns4:parameter>

</ns3:info>

</ns2:backup>

</ns2:backupm>

</ns1:data>

<src>

</src>

</packet>

156

Base Types and Interfaces

get_info

Summary:

Retrieves extended information about backup.

Request specification:

Name Min/Max Type Description

get_info 1..1

{

backup_id 1..1 backupid_type (p. 124) The backup ID.

options 1..1 get_info_optionsType

(p. 129)

Options.

}

Returns:

Name Min/Max Type Description

info 1..1 backup_dataType (p.

121)

The requested backup

information.

The data type of the returned

structure is determined by

the data type of the

options element in the

request.

Description:

If you are connected to the Master Node in a Virtuozzo group, the call can access any backup

located on every physical node. If you are connected to a slave node, the call can access only the

local backups. If your backups are stored on a remote backup server, you must connect to that

server directly and execute the call there.

Example:

Retrieving information about the specified backup.

<packet xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/backupm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0">

<target>backupm</target>

<data>

<get_info>

<backup_id>57c2cd6c-c02b-4645-bdb5-e883ea005896/20070219170146</backup_id>

<env/>

</options>

</get_info>

</backupm>

</data>

</packet>

157

Base Types and Interfaces

set_config

Summary:

Sets the default backup configuration.

Request specification:

Name Min/Max Type Description

set_config

{

backupm_config 1..1 backupm_configType (p.

125)

Backup manager

configuration information.

}

Returns:

OK/Error

Description:

To retrieve current backup configuration, use the get_config call (p. 159).

Example:

Input

<target>backupm</target>

<data>

<set_config>

<backupm_config>

<backup_server>

<login>

<name>agent</name>

</login>

</backup_server>

<chain_length>0</chain_length>

<chain_days>0</chain_days>

<keep_max>0</keep_max>

<pe_backups_limit>1</pe_backups_limit>

</backupm_config>

</set_config>

</backupm>

</data>

</packet>

Output

158

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/backupm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="17c4cf3834ct99r4c4" time="2010-11-29T14:42:18+0000">

<origin>backupm</origin>

<target>vzclient7659-623c4daf-570a-b548-8171-4c7d0adbcb69</target>

<dst>

</dst>

<data>

<ok/>

</backupm>

</data>

<src>

</src>

</packet>

159

Base Types and Interfaces

get_config

Summary:

Retrieves the default backup configuration.

Request specification:

Name Min/Max Type Description

get_config 1..1 none

{

local 0..1 none If this element is present, the call returns the

local configuration. If no local configuration is

available, returns an error

(ERROR_VZL_NO_CONFIG=308).

If the element is omitted, the call returns the

actual configuration (retrieved from the master

node if necessary).

}

Returns:

Name Min/Max Type Description

backupm_config 1..1 backupm_configType (p.

125)

Backup manager

configuration.

Description:

The default backup configuration is stored in the Agent configuration file. It defines such parameters

as backup server location and connectivity, backup type, compression level, certain assumptions

and restrictions. The get_config call retrieves the currently defined backup configuration. The

configuration can be modified using the set_config call (p. 157).

Example:

Input

<target>backupm</target>

<data>

<get_config/>

</backupm>

</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/backupm"

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="84c4ae04f51t798br2c8" time="2009-10-22T12:26:17+0000">

160

Base Types and Interfaces

<ns1:origin>backupm</ns1:origin>

<ns1:target>vzclient65-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:backupm>

<ns2:backupm_config>

<ns2:backup_server xsi:type="ns3:connection_infoType">

<ns3:protocol>agent</ns3:protocol>

<ns3:login xsi:type="ns3:auth_nameType">

<ns3:realm>00000000-0000-0000-0000-000000000000</ns3:realm>

</ns3:login>

<ns3:address>local</ns3:address>

</ns2:backup_server>

<ns2:chain_length>0</ns2:chain_length>

<ns2:chain_days>0</ns2:chain_days>

<ns2:keep_max>0</ns2:keep_max>

<ns2:compression>1</ns2:compression>

<ns2:type>0</ns2:type>

<ns2:pe_backups_limit>1</ns2:pe_backups_limit>

</ns2:backupm_config>

</ns2:backupm>

</ns1:data>

<src>

</src>

</packet>

161

Base Types and Interfaces

server_group

Purpose:

The Virtuozzo group management interface.

Virtuozzo group is a collection of servers running Agent software, interconnected using internal

Agent mechanisms for the purpose of providing integrated access to their resources. A Virtuozzo

group consists of a Master Node and one or more Slave Nodes. The Master Node is a computer

that the users interact with. It provides access to other computers in the group transparently to the

user. The Master Node manages the entire group by allocating and controlling the available

resources. The server_group interface allows to set up and administer Virtuozzo groups.

Once a Virtuozzo group is set up, all of the servers in the group become one logical computing unit

with a shared resource pool and a common management interface. The following is a list of typical

management tasks performed in a Virtuozzo group:

• Retrieve a list of all Virtuozzo Containers from every server in a single call. Each Container has a

globally unique ID assigned to it by Agent, so the list will always contain unique entries.

• Perform any of the usual management tasks on any of the Containers in the entire group. A

client program connected to the Master Node can manage Virtuozzo Containers without even

knowing their actual hosts. However, the Server ID of any host (Slave Node) can be easily

obtained at any time if needed.

• Get a combined list of all of the OS and application templates available in the group. The

templates can be copied from one node to another and deployed to multiple nodes.

• Get a combined list of all the sample configurations available in the group. The configurations

can then be used to create Virtuozzo Containers on any node in the group.

• Get a combined list of the Virtuozzo Container backups available in the group. A backup can be

restored to any node in the group.

162

Base Types and Interfaces

Types

configType

Summary:

Virtuozzo group network configuration information.

Type specification:

Name Min/Max Type Description

nameservers 0..1 Nameserver information.

{

nameserver 0.[] ip_type Nameserver IP addresses.

}

search_domains 0..1 Search domain information.

{

search_domain 0..[] string Search domain names.

}

networks Virtuozzo virtual network

information.

{

network 0..[] networkType (p. 163) A list of the available Virtuozzo

virtual networks. This field is used

by Virtuozzo Tools as an easy way

of listing the virtual networks

available in a given Virtuozzo

group. Setting the network ID

through this field does not actually

create a network. The network

must be created through the

vzanetworkm interface (p. 661).

}

163

Base Types and Interfaces

networkType

Summary:

Contains Virtuozzo virtual network ID and description.

Type specification:

Name Min/Max Type Description

id 1..1 base64Binary Virtuozzo virtual network ID.

description 0..1 base64Binary Virtual network description.

voc_idType

Summary:

Contains the Agent vocabulary name and version.

Type specification:

Name Min/Max Type Description

name 1..1 string Vocabulary name.

version 1..1 string Vocabulary version.

Calls

Call Description

add (p. 164) Adds a slave node to a Virtuozzo group.

del (p. 166) Deletes a slave node from a Virtuozzo group.

get_list (p. 167) Retrieves a list of servers from a Virtuozzo group.

get_info (p. 169) Returns information about the specified Container.

destroy (p. 173) Dismantles a Virtuozzo group.

set_config (p. 174) Modifies the Virtuozzo group configuration.

get_config (p. 175) Retrieves the VIrtuozzo group configuration information.

get_env_voc (p. 176) Retrieves Agent vocabularies.

get_vocabulary (p. 177) Retrieves the specified vocabulary data.

164

Base Types and Interfaces

add

Summary:

Adds a Hardware Node to a Virtuozzo group.

Request specification:

Name Min/Max Type Description

add

{

conn_info 1..1 connection_infoType

(p. 34)

The Slave Node connection

information.

master 0..1 connectivity_infoTyp

e (p. 34)

The Master Node connection

information.

This parameter should be

used when master node has

more than one IP address.

For example, this parameter

should be set when the

master and the Slave Nodes

are located in the same

private network and should

communicate using IP

addresses other than those

exposed to the external

network.

If Master Node has more

than one IP address but this

parameter is not set, the

Master will select the address

randomly.

force 0..1 none Forcibly add a Node to the

group even if it's already

registered with another

group.

}

Returns:

Name Min/Max Type Description

eid 1..1 eid_type (p. 29) The Server ID of the Node

that you just added to the

Virtuozzo group.

Description:

The call adds a Slave Node to the Virtuozzo group by registering it with the Master Node. The call

must be executed on the Master Node.

165

Base Types and Interfaces

The server_group interface does not have a separate call that creates a Virtuozzo group. A

group is created and configured automatically as soon as you execute at least one successful add

request. The Node on which you execute the call becomes the Master Node. To add more Nodes

to the Group, execute the add request for each one of them. There can be only one Master Node

in a Virtuozzo group.

Example:

Input

<target>server_group</target>

<data>

<server_group>

<add>

<conn_info>

<login>

<name>dnphZG1pbg==</name>

</login>

<password>MXEzNl</password>

</conn_info>

</add>

</server_group>

</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/server_group"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="ec45d1b013t26e9rd54"

time="2007-02-12T06:26:17+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns1:ok/>

</ns2:server_group>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

166

Base Types and Interfaces

del

Summary:

Removes a Slave Node from a Virtuozzo group.

Request specification:

Name Min/Max Type Description

del

{

eid 1..1 eid_type (p. 29) Server ID of the slave Node

being removed from the

group.

force 0..1 none Forcibly remove the Node.

}

Returns:

OK/Error

Description:

The call removes a slave Node from a Virtuozzo group. The request must be executed on the

Master Node of the group. As a result, the specified slave Node will no longer be registered with

this group and can be added to a different group or become a Master Node of a new group.

Example:

Input

<target>server_group</target>

<data>

<server_group>

<del>

</del>

</server_group>

</data>

</packet>

167

Base Types and Interfaces

get_list

Summary:

Retrieves a list of servers from a Virtuozzo group.

Request specification:

Name Min/Max Type Description

get_list

{

count 0..1 int Maximum number of servers

to include in the list. Omit the

element to retrieve all

available servers.

type 0..1 string Types of servers to retrieve:

generic -- physical servers.

virtuozzo -- Virtuozzo

Containers.

parallels -- Parallels

virtual machines.

Omit the element to retrieve

the servers of all known

types.

hostname 0..1 string Host name.

ip 0..1 ip_type ID address.

status 0..[] env_statusType (p.

39)

Retrieve only the servers with

the specified status.

}

Returns:

Name Min/Max Type Description

eid 0..[] eid_type (p. 29) The list of Server IDs.

Description:

The call retrieves a list of IDs of the servers from a Virtuozzo group. Use the provided options to

specify a search criteria to retrieve only the servers that you need. The call must be executed on the

Master Node.

Example:

Input

<target>server_group</target>

<data>

168

Base Types and Interfaces

<server_group>

<get_list>

<type>generic</type>

</status>

</get_list>

</server_group>

</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/server_group"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="17c45d1c4f4t99rd54"

time="2007-02-12T07:35:39+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns2:eid>89e27960-97b8-461f-902f-557b4b16784b</ns2:eid>

<ns2:eid>72145bf0-7562-43d4-b707-cc33d37e3f10</ns2:eid>

</ns2:server_group>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

169

Base Types and Interfaces

get_info

Summary:

Retrieves information about the specified server in a Virtuozzo group.

Request specification:

Name Min/Max Type Description

get_info

{

eid 0..[] eid_type (p. 29) Server ID. If omitted, then

retrieves information for all

servers in a group.

status 0..1 none If present, a server status

information will be included in

the result.

config 0..1 none If present, a server

configuration information will

be included in the result.

filter_config 0..1 Filter. Allows to perform

selective retrieval.

{

<xs:any/> 1..1 Specify server configuration

parameters that you would

like to be retrieved.

}

Returns:

Name Min/Max Type Description

env 0..[] envType The requested server

information.

Example:

Input

<target>server_group</target>

<data>

<server_group>

<get_info>

</get_info>

</server_group>

</data>

</packet>

170

Base Types and Interfaces

Output

<ns1:packet xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/server_group"

xmlns:ns4="http://www.swsoft.com/webservices/vza/4.0.0/vzatypes"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="25c45d1d304t66bbr538"

time="2007-02-12T05:51:03+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient4</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns2:env xsi:type="ns3:envType">

<ns3:parent_eid>89e27960-97b8-461f-902f-557b4b16784b</ns3:parent_eid>

<ns3:eid>3288bb6b-8a49-4230-b565-6ad5521182aa</ns3:eid>

<ns3:status xsi:type="ns3:env_statusType">

<ns3:state>6</ns3:state>

</ns3:status>

<ns3:alert>0</ns3:alert>

<ns3:config xsi:type="ns3:env_configType"/>

<ns3:virtual_config xsi:type="ns3:venv_configType">

<ns3:hostname>Host-105</ns3:hostname>

<ns3:name>Test-VE5</ns3:name>

<ns3:offline_management>1</ns3:offline_management>

<ns3:on_boot>1</ns3:on_boot>

<ns3:os_template>

<ns3:version>20061020</ns3:version>

<ns3:name>redhat-as3-minimal</ns3:name>

</ns3:os_template>

<ns3:ve_root>/vz/root/$VEID</ns3:ve_root>

<ns3:ve_private>/vz/private/$VEID</ns3:ve_private>

<ns3:qos>

<ns3:id>avnumproc</ns3:id>

<ns3:hard>40</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>cpuunits</ns3:id>

<ns3:hard>1000</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>dcachesize</ns3:id>

<ns3:hard>1097728</ns3:hard>

<ns3:soft>1048576</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>dgramrcvbuf</ns3:id>

<ns3:hard>132096</ns3:hard>

<ns3:soft>132096</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>diskinodes</ns3:id>

<ns3:hard>220000</ns3:hard>

<ns3:soft>200000</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>diskspace</ns3:id>

<ns3:hard>1153434</ns3:hard>

<ns3:soft>1048576</ns3:soft>

171

Base Types and Interfaces

</ns3:qos>

<ns3:qos>

<ns3:id>kmemsize</ns3:id>

<ns3:hard>2936012</ns3:hard>

<ns3:soft>2752512</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>lockedpages</ns3:id>

<ns3:hard>32</ns3:hard>

<ns3:soft>32</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>numfile</ns3:id>

<ns3:hard>2048</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numflock</ns3:id>

<ns3:hard>110</ns3:hard>

<ns3:soft>100</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>numiptent</ns3:id>

<ns3:hard>128</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numothersock</ns3:id>

<ns3:hard>80</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numproc</ns3:id>

<ns3:hard>65</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numpty</ns3:id>

<ns3:hard>16</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numsiginfo</ns3:id>

<ns3:hard>256</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numtcpsock</ns3:id>

<ns3:hard>80</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>oomguarpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>6144</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>othersockbuf</ns3:id>

<ns3:hard>336896</ns3:hard>

<ns3:soft>132096</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>physpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>0</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>privvmpages</ns3:id>

172

Base Types and Interfaces

<ns3:hard>24576</ns3:hard>

<ns3:soft>22528</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>quotatime</ns3:id>

<ns3:hard>0</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>shmpages</ns3:id>

<ns3:hard>8192</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>tcprcvbuf</ns3:id>

<ns3:hard>524288</ns3:hard>

<ns3:soft>319488</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>tcpsndbuf</ns3:id>

<ns3:hard>524288</ns3:hard>

<ns3:soft>319488</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>vmguarpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>6144</ns3:soft>

</ns3:qos>

<ns3:veid>105</ns3:veid>

<ns3:type>virtuozzo</ns3:type>

<ns3:offline_service>vzpp</ns3:offline_service>

<ns3:offline_service>vzpp-plesk</ns3:offline_service>

<ns3:os xsi:type="ns3:osType">

<ns3:platform>Linux</ns3:platform>

<ns3:kernel>2.6.9-023stab033.6</ns3:kernel>

<ns3:version>20061020</ns3:version>

<ns3:name>redhat-as3-minimal</ns3:name>

</ns3:os>

<ns3:net_device xsi:type="ns4:net_vethType">

<ns3:id>venet0</ns3:id>

<ns3:ip_address>

<ns3:ip>10.130.1.5</ns3:ip>

</ns3:ip_address>

<ns4:host_routed/>

</ns3:net_device>

<ns3:address>

<ns3:ip>10.130.1.5</ns3:ip>

</ns3:address>

</ns3:virtual_config>

</ns2:env>

</ns2:server_group>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

173

Base Types and Interfaces

destroy

Summary:

Dismantles an existing VIrtuozzo group.

Request specification:

Name Min/Max Type Description

destroy 1..1 none

Returns:

OK/Error

Description:

The call dismantles a Virtuozzo group by removing all relevant references from the Master and

Slave Nodes. Once completed, the Nodes may be added to other Virtuozzo groups. Any former

participant of a group may also become a Master Node forming its own group. The call must be

executed on the Master Node.

Example:

Input

<target>server_group</target>

<data>

<server_group>

</server_group>

</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/server_group"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="26c45d1d434t428br538"

time="2007-02-12T05:54:53+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient4</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns1:ok/>

</ns2:server_group>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

174

Base Types and Interfaces

set_config

Summary:

Modifies Virtuozzo Group configuration.

Request specification:

Name Min/Max Type Description

set_config 1..1 none

{

config 1..1 configType (p. 162) Virtuozzo Group

configuration.

}

Returns:

OK/Error

Example:

Adding two name servers and one search domain to a Virtuozzo Group. The call must be executed

on the Master Node.

<target>server_group</target>

<data>

<server_group>

<set_config>

</nameservers>

<search_domains>

<search_domain>ts6.com</search_domain>

</search_domains>

</config>

</set_config>

</server_group>

</data>

</packet>

175

Base Types and Interfaces

get_config

Summary:

Retrieves configuration information for a given Virtuozzo Group.

Request specification:

Name Min/Max Type Description

get_config

Returns:

Name Min/Max Type Description

config 0..1 configType

(p. 162)

The cluster network configuration

information.

Example:

Retrieving Virtuozzo Group configuration information. The call must be executed on the Master

Node.

Input

<target>server_group</target>

<data>

<server_group>

<get_config/>

</server_group>

</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/server_group"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="29c45d1e0ebt5d03r538"

time="2007-02-12T06:35:58+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient4</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns2:config>

<ns2:nameservers>

<ns2:nameserver>192.168.1.51</ns2:nameserver>

<ns2:nameserver>192.168.1.52</ns2:nameserver>

</ns2:nameservers>

<ns2:search_domains>

<ns2:search_domain>ts6.com</ns2:search_domain>

</ns2:search_domains>

<ns2:networks/>

</ns2:config>

</ns2:server_group>

176

Base Types and Interfaces

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

get_env_voc

Summary:

Retrieves a list of vocabularies from a given Virtuozzo Group.

Request specification:

Name Min/Max Type Description

eid 0..[] eid_type (p.

29)

The IDs of the servers to retrieve the

vocabularies from. If omitted, a

combined list of vocabularies from all

servers in the group will be retrieved.

Returns:

Name Min/Max Type Description

env_voc Vocabulary information.

{

eid 1..1 eid_type (p.

29)

The ID of the servers from which the

vocabularies were retrieved.

id 0..[] voc_idType

(p. 163)

A list of vocabularies. Contains

vocabulary name and version

information.

}

Example:

Input

<target>server_group</target>

<data>

<server_group>

<get_env_voc/>

</server_group>

</data>

</packet>

177

Base Types and Interfaces

get_vocabulary

Summary:

Retrieves the specified Agent vocabulary.

Request specification:

Name Min/Max Type Description

get_vocabulary

{

id 1..[] voc_idType

(p. 163)

Vocabulary ID and version information.

To get the list of vocabulary IDs, use

the get_env_voc call (p. 176).

}

Returns:

Name Min/Max Type Description

vocabulary 1..[] vocabulary

Type (p. 70)

Vocabulary data.

computerm

Purpose:

Computer management interface. Provides a set of calls that allow to manage physical servers and

Virtuozzo Containers as if they were regular physical machines. The interface provides limited

control over the Hardware Node and is normally used to retrieve the computer system information.

Types

diskType

Summary:

Contains information about hard disk partitions.

Type specification:

Name Min/Max Type Description

partition 0..[] partitionType (p. 178) Partition information.

178

Base Types and Interfaces

partitionType

Summary:

Contains hard disk partition information.

Type specification:

Name Min/Max Type Description

name 0..1 string Partition name.

mount_point 0..1 string Partition mount point.

fs_type 0..1 string Filesystem type.

block_size 0..1 long Block size.

blocks 0..1 usageType (p. 67) Partition disk space information

(total/used/free).

inodes 0..1 usageType (p. 67) Partition disk inodes

information (total, used, free).

option 0..[] string Mount options.

systemType

Summary:

Contains computer system information.

Type specification:

Name Min/Max Type Description

architecture 1..1 string Architecture.

os 1..1 osType (p. Operating system

information.

55)

cpu 1..1 cpuType (p. CPU information.

35)

memory 1..1 resourceType (p. Physical memory

information.

61)

swap 1..1 resourceType (p. Swap memory information.

61)

179

Base Types and Interfaces

Calls

Call Description

get_disk (p. 180) Retrieves disk and partition information.

get_system (p. 182) Retrieves system information.

get_network (p. 184) Retrieves network information.

reboot (p. 189) Reboots or shuts down a server.

get_date (p. 190) Retrieves current date and time from a server.

set_date (p. 192) Sets date and time for a server.

get_zones_info (p. 194) Gets information about known time zones.

180

Base Types and Interfaces

get_disk

Summary:

Retrieves information about disks and partitions.

Request specification:

Name Min/Max Type Description

get_disk 0..1 None

Returns:

Name Min/Max Type Description

disk 0..[] diskType (p. Disk information.

177)

Description:

The call retrieves disk and partition information from the current server.

NOTE: For the Linux reiser file system, the command always returns negative values for inodes.

Example:

Input

<target>computerm</target>

<data>

<get_disk/>

</computerm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/computerm"

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:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="8c4ae2f73ct18ber500" time="2009-10-24T12:46:52+0000">

<ns1:origin>computerm</ns1:origin>

<ns1:target>vzclient5-0649a879-f36e-fc4f-b821-5358d55cdefd</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:computerm>

<ns2:disk>

<ns2:partition>

<ns2:name>/dev/vzfs</ns2:name>

<ns2:mount_point>/</ns2:mount_point>

<ns2:block_size>4096</ns2:block_size>

<ns2:fs_type>unknown fs [1448756819]</ns2:fs_type>

<ns2:option>rw</ns2:option>

181

Base Types and Interfaces

<ns2:blocks xsi:type="ns3:usageType">

<ns3:total>262144</ns3:total>

<ns3:used>169148</ns3:used>

<ns3:free>92996</ns3:free>

</ns2:blocks>

<ns2:inodes xsi:type="ns3:usageType">

<ns3:total>200000</ns3:total>

<ns3:used>17236</ns3:used>

<ns3:free>182764</ns3:free>

</ns2:inodes>

</ns2:partition>

</ns2:disk>

</ns2:computerm>

</ns1:data>

<src>

</src>

</packet>

182

Base Types and Interfaces

get_system

Summary:

Retrieves system information.

Request specification:

Name Min/Max Type Description

get_system 0..1 None

Returns:

Name Min/Max Type Description

system 0..1 systemType (p. 178) System information.

Description:

The call retrieves system information from the current Hardware Node. The result set is organized

into a list of structures, each containing the detailed information about a particular system area,

such as operating system, CPU, memory, swap file information.

Example:

Input

<target>computerm</target>

<data>

<get_system/>

</computerm>

</data>

</packet>

Output

<origin>computerm</origin>

<data>

<architecture>x86 Family 15 Model 3 Stepping 8</architecture>

Linux

<platform>Windows</platform>

<version>5.2.3790 Service Pack 1 Build 3790</version>

<name>Microsoft Windows Server 2003 family</name>

</os>

<cpu>

<family>x86 Family 15 Model 3 Stepping 8</family>

<name>Intel(R) Celeron(R) CPU 2.80GHz</name>

183

Base Types and Interfaces

<model>GenuineIntel</model>

</cpu>

</memory>

<swap>

</swap>

</system>

</computerm>

</data>

</packet>

184

Base Types and Interfaces

get_network

Summary:

Retrieves network information.

Request specification:

Name Min/Max Type Description

get_network 0..1 None

Returns:

Name Min/Max Type Description

network 0..1

{

nameserver 0..[] string Name servers.

hostname 1..1 string Hostname.

default_gateway 1..1 string Default gateway.

interface 0..[] interfaceType (p.

45)

Network interface info.

}

Description:

The call retrieves network settings from the Hardware Node.

Example:

Input

<target>computerm</target>

<data>

<get_network/>

</computerm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/computerm"

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:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="13c4ae2fbaet41bbr9c0" time="2009-10-24T13:06:21+0000">

<ns1:origin>computerm</ns1:origin>

<ns1:target>vzclient11-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

185

Base Types and Interfaces

<ns1:data>

<ns2:computerm>

<ns2:network>

<ns2:hostname>mccp41</ns2:hostname>

<ns2:default_gateway>0.0.0.0</ns2:default_gateway>

<ns2:nameserver>10.31.0.1</ns2:nameserver>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>Software Loopback Interface 1</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (SSTP)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (L2TP)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (PPTP)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

186

Base Types and Interfaces

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (PPPOE)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (IPv6)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (Network Monitor)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (IP)</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>RAS Async Adapter</ns3:name>

<ns3:transfer>

<ns3:input>

187

Base Types and Interfaces

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>Broadcom NetXtreme Gigabit Ethernet #2</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>2590058</ns3:packets>

<ns3:bytes>2164088371</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>1495949</ns3:packets>

<ns3:bytes>405240478</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:ipaddress>10.31.252.35</ns3:ipaddress>

<ns3:flags>0</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>isatap.{03C77D5A-BEC9-4520-879E-F9AC9D242A6F}</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>isatap.qa.sw.ru</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (IPv6)-QoS Packet Scheduler-0000</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

188

Base Types and Interfaces

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (IP)-QoS Packet Scheduler-0000</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>WAN Miniport (Network Monitor)-QoS Packet Scheduler-

0000</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>Broadcom NetXtreme Gigabit Ethernet-QoS Packet Scheduler-

0000</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>0</ns3:packets>

<ns3:bytes>0</ns3:bytes>

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

<ns2:interface xsi:type="ns3:interfaceType">

<ns3:name>Broadcom NetXtreme Gigabit Ethernet #2-QoS Packet Scheduler-

0000</ns3:name>

<ns3:transfer>

<ns3:input>

<ns3:packets>2590058</ns3:packets>

<ns3:bytes>2164088371</ns3:bytes>

</ns3:input>

<ns3:output>

<ns3:packets>1495949</ns3:packets>

<ns3:bytes>405240478</ns3:bytes>

189

Base Types and Interfaces

</ns3:output>

</ns3:transfer>

<ns3:flags>1</ns3:flags>

</ns2:interface>

</ns2:network>

</ns2:computerm>

</ns1:data>

<src>

</src>

</packet>

reboot

Summary:

Reboots or shuts down the machine.

Request specification:

Name Min/Max Type Description

reboot 0..1 none

{

shutdown 0..1 none If present, the server will be shut

down.

}

Returns:

OK/ERROR.

Description:

The call reboots or shuts down the current Hardware Node. To perform a complete shutdown,

include the optional shutdown element. To reboot, include just the reboot element. All users that

are currently logged on to the server will be automatically logged off.

Example:

Input

<target>computerm</target>

<data>

</reboot>

</computerm>

</data>

</packet>

190

Base Types and Interfaces

get_date

Summary:

Retrieves date and time information from the Hardware Node.

Request specification:

Name Min/Max Type Description

get_date 0..1 None

Returns:

Name Min/Max Type Description

date 1..1

{

time 0..1 datetime_type Current time.

time_zone 0..1 string Time zone information.

}

Example:

Input

<target>computerm</target>

<data>

<get_date/>

</computerm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/computerm"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="15c4ae30026t1ebr9c0" time="2009-10-24T13:25:25+0000">

<ns1:origin>computerm</ns1:origin>

<ns1:target>vzclient11-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:computerm>

<ns2:date>

<ns2:time>2009-10-24T13:25:25+0000</ns2:time>

<ns2:time_zone>Russian Standard Time</ns2:time_zone>

</ns2:date>

</ns2:computerm>

</ns1:data>

<src>

191

Base Types and Interfaces

</src>

</packet>

192

Base Types and Interfaces

set_date

Summary:

Sets local date and time on the Hardware Node.

Request specification:

Name Min/Max Type Description

set_date

{

date 1..1

{

year 1..1 int Four-digit year.

month 1..1 int Month (1 to 12).

day 1..1 int Day of month (1 to 31).

hour 1..1 int Hour (0 to 23).

minute 1..1 int Minute (0 to 59).

second 1..1 int Second (0 to 59).

day_of_week 0..1 int Day of week (0 to 7; 0 and 7

both refer to Sunday).

}

{

time_zone 0..1 string Time zone information.

}

Returns:

OK/Error

Example:

<target>computerm</target>

<data>

<set_date>

<date>

<day_of_week>2</day_of_week>

<time_zone>America/New_York</time_zone>

</date>

193

Base Types and Interfaces

</set_date>

</computerm>

</data>

</packet>

194

Base Types and Interfaces

get_zones_info

Summary:

Retrieves information about known time zones.

Request specification:

Name Min/Max Type Description

get_zones_info 0..1 None

Returns:

Name Min/Max Type Description

time_zone 0..[]

{

name 1..1 string Zone name.

display_name 1..1 string Display name.

}

Example:

Input

<target>computerm</target>

<data>

<get_zones_info/>

</computerm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/computerm"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="14c4ae2fe3bt26e9r9c0" time="2009-10-24T13:17:15+0000">

<ns1:origin>computerm</ns1:origin>

<ns1:target>vzclient11-2fabe194-0477-0871-a32d-49220050cf5c</ns1:target>

<ns1:dst>

</ns1:dst>

<ns1:data>

<ns2:computerm>

<ns2:time_zone>

<ns2:name>Afghanistan Standard Time</ns2:name>

<ns2:display_name>(GMT+04:30) Kabul</ns2:display_name>

</ns2:time_zone>

<ns2:time_zone>

<ns2:name>Alaskan Standard Time</ns2:name>

<ns2:display_name>(GMT-09:00) Alaska</ns2:display_name>

</ns2:time_zone>

<ns2:time_zone>

195

Base Types and Interfaces

<ns2:name>Arab Standard Time</ns2:name>

<ns2:display_name>(GMT+03:00) Kuwait, Riyadh</ns2:display_name>

</ns2:time_zone>

<ns2:time_zone>

<ns2:name>Yakutsk Standard Time</ns2:name>

<ns2:display_name>(GMT+09:00) Yakutsk</ns2:display_name>

</ns2:time_zone>

</ns2:computerm>

</ns1:data>

<src>

</src>

</packet>

data_storagem

Purpose:

The base data storage management interface.

Derived interfaces:

backup_storagem (p. 120)

Types

ds_locationType

Summary:

Contains data storage location configuration

Type specification:

Name Min/Max Type Description

type 1..1 int Data storage location type:

0 -- local

1 -- Windows share.

path 1..1 base64Binary Root data storage path.

login 0..1 auth_nameType (p.

33)

Login for remote storage.

password 0..1 string Password for remote

storage.

196

Base Types and Interfaces

ds_configurationType

Summary:

Describes data storage configuration.

Type specification:

Name Min/Max Type Description

location 1..1 ds_locationType (p.

195)

Data storage location.

ds_object_infoType

Summary:

Displays information about an object in data storage.

Type specification:

Name Min/Max Type Description

time 1..1 datetime_type (p. 28) Object modification or

creation time.

size 1..1 long Object size in storage.

type 1..1 int Object type. Values depend

on implementation.

id 1..1 ds_object_path_type (p.

196)

Object ID/path.

storage_eid 1..1 eid_type (p. 29) Server ID of the data

storage server.

info 1..1 infoType (p. 43) Additional information about

an object.

ds_object_path_type

Summary:

Object identifier.

Type specification:

Restriction: string.

197

Base Types and Interfaces

Calls

Call Description

get_storage_config (p. 197) Retrieves data storage configuration.

set_storage_config (p. 197) Sets data storage configuration.

get_storage_config

Summary:

Retrieves data storage configuration.

Request specification:

Name Min/Max Type Description

get_storage_config 1..1 none

Returns:

Name Min/Max Type Description

config ds_configurationType

(p. 196)

Data Storage configuration.

set_storage_config

Summary:

Sets the data storage configuration.

Request specification:

Name Min/Max Type Description

set_storage_config 1..1

{

config 1..1 ds_configurationType

(p. 196)

New Data Storage

configuration information.

}

Returns:

OK/Error

198

Base Types and Interfaces

devm

Purpose:

The base device management interface. Supported virtualization technologies have their own

device management interfaces, which are derived from the devm interface.

Derived interfaces:

vzadevm (p. 632)

vzpdevm (p. 724)

199

Base Types and Interfaces

Types

mount_deviceType

Summary:

Contains device mount information.

Type specification:

Name Min/Max Type Description

permanent 0..1 boolean Mount type:

true -- permanent mount.

false -- temporary mount.

Permanently mounted devices are mounted

automatically at system boot. Please note that

when mounting a device on the Hardware

Node, the mount information is written into the

/etc/fstab file. However, when mounting a

device inside a Virtuozzo Container, the mount

information is written into one of the Virtuozzo

script files, which are executed at the time a

specific Container is started.

device 0..1 string On Linux, the name of the device.

On Windows, the name of the device or an

EFD image file.

point 1..1 string Mount point.

On Linux , it is the directory name.

On Windows, it is the drive letter, e.g. E:

filesystem 0..1 string Filesystem type.

active 0..1 boolean Mount status:

true -- the mount is active.

false -- the mount is inactive.

The "inactive" status applies only to the

permanent mounts. Temporary mounts can

exist only in the "active" state. In other words,

you cannot mount a device temporarily and

make it inactive at the same time. If you try to

"deactivate" a temporarily mounted device, the

mount will be deleted altogether.

size 0..1 long The size of the EFD image file. When

creating an EFD image, specify the desired size

here.

200

Base Types and Interfaces

interface 0..1 string Interface type:

SCSI -- SCSI storage device.

This element is used when configuring Windows

Cluster Server (MSCS) support in a Virtuozzo

Container. You can create an EFD image,

mount it inside a Virtuozzo Container, and

configure the new drive to be recognized by

Windows running in the Container as a SCSI

storage device. In order to do that, include the

interface element containing the SCSI

value.

If this element is omitted while mounting an EFD

image inside a Container, the image is mounted

as a common loopback.

common_deviceType

Summary:

Common device information.

Type specification:

Name Min/Max Type Description

name 0..1 string Device name.

description 0..1 string Device description.

Subtypes:

windows_deviceType (p. 201)

scsi_deviceType (p. 201)

201

Base Types and Interfaces

windows_deviceType

Summary:

Contains information about any non-SCSI device on Windows.

Type specification:

Extends common_deviceType (p. 200)

Adds the following elements:

Name Min/Max Type Description

physical_name 0..1 base64Binary Physical device name.

scsi_deviceType

Summary:

Contains information about a SCSI device.

Type specification:

Extends windows_deviceType (p. 201)

The type has no additional elements.

202

Base Types and Interfaces

Calls

Call Description

get_mounts (p. 213) Retrieves a list of devices mounted inside the specified

server.

new_mount (p. 222) Mounts the specified device.

umount (p. 230) Unmounts the specified device.

get_info (p. 211) Gets information about all available filesystems, partitions

and devices.

create_drive (p. 203) Creates a new file system image file and loopback-

mounts it in the specified server.

delete_drive (p. 207) Unmounts and deletes the file system image file.

resize_drive (p. 228) Resizes file system image file.

format_drive (p. 208) Formats a disk drive.

list_devices (p. 217) Lists devices available on the Hardware Node.

forward_device (p. 209) Makes a SCSI device on the Hardware Node visible and

accessible to Virtuozzo Containers.

remove_forward (p. 226) Cancels forwarding of a device (see forward_device

above).

list_forward (p. 219) List the device forwarding information (see

forward_device above).

203

Base Types and Interfaces

create_drive

This call is available on Windows only.

Summary:

Creates a new file system image and loopback-mounts it on the specified server.

Request specification:

Name Min/Max Type Description

create_drive mount_deviceType

(p.

199)

{

eid 1..1 eid_type (p. Server ID.

29)

}

Returns:

Name Min/Max Type Description

device_info New disk information.

{

device 0..[] string The full path to the image file.

}

Description:

Use the create_drive call to create EFD file system images. EFD is Parallels' proprietary file

system. The call creates a new, empty file system image file and then loopback-mounts it the

specified Container. After the file is created and mounted, you can use it just like any other physical

disk drive inside the Container.

The device parameter specifies the name and path where the file will reside. If you specify a full

path, it will be treated as a path on the Hardware Node. If you specify just the name of the file, the

file will be created in the Container private area. If you omit the device element, the file name will

be generated automatically and the file will be created in the Container private area.

The image located in a particular Container private area can be mounted inside that Container only.

Note that when creating an image file, you have to mount it inside a Container, you cannot create

an unmounted EFD image.

The following describes the parameters used in this call:

204

Base Types and Interfaces

device -- The name and path of the image file. If not specified, the name will be generated

automatically by using the lpbk prefix (meaning "loopback") followed by a numeric value indicating

the file number (i.e. 0000, 0001, 0002, etc.), and the .efd extension. The following are the

examples of the automatic file names: lpbk0000.efd, lpbk0001.efd, lpbk0002.efd. If the

name doesn't contain a full path, the image file will be created in the Container private area. If the

full path is specified (e.g. C:\img.efd), it will be treated as a path on the Hardware Node.

size -- The size of the image file in bytes.The minimum allowed size is 6 megabytes. There's no

limit on the max size. You can change this size later with the resize_drive call (p. 228).

point -- The mount point. This must be the disk drive letter, e.g. E:

eid -- The ID of the server where you would like to mount the image file.

Configuring shared loopback based Container clustering

interface -- To configure shared loopback based Container clustering, the new drive must be

recognized by Windows running inside the Container as SCSI block device. This is accomplished

by include the interface element containing the SCSI value. Before you can start using the drive

inside the Container, you'll have to initialize it as follows:

1 Log in to the Container via Remote Desktop.

2 On the Windows Start menu, select Programs->Administrative Tools->Computer

Management.

3 In the Computer Management window, select Storage->Disk Management.

4 Right-click on the new disk and select the Initalize option from the pop-up menu.

5 Right-click on the disk partition and select the New Parition option from the menu.

6 Complete the New Partition wizard using the default values on all screens except the Assign

the Drive Letter or Path screen where you should select the drive letter that you specified in

the point parameter of the create_drive call.

The following steps describe how to deploy shared loopback based Container clustering.

1. Enable Windows Cluster Server support in a Virtuozzo Container by turning the

failover_cluster capability on. The following code example shows how it is accomplished:

<target>vzaenvm</target>

<data>

<set>

<id>failover_cluster</id>

</capability>

</config>

</set>

205

Base Types and Interfaces

</vzaenvm>

</data>

</packet>

2. Create a shared disk drive as described above.

3. Login to the Container via Remote Desktop and create/add the Container to a cluster using

Microsoft Cluster Administrator.

Example 1:

Creating the filesystem image named img.efd in the C: drive root directory on the Hardware

Node and mounting it as an F: drive inside the specified Virtuozzo Container.

Input

<target>vzadevm</target>

<data>

<create_drive>

</create_drive>

</vzadevm>

</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/vza/4.0.0/vzadevm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="2bc46486e35t6443re80"

time="2007-05-15T13:12:23+0000" priority="0" version="4.0.0">

<ns1:origin>vzadevm</ns1:origin>

<ns1:target>vzclient2</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzadevm>

<ns2:device_info>

<ns2:device>C:\img.efd</ns2:device>

</ns2:device_info>

</ns2:vzadevm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Example 2:

In this example we do not specify the name for the image file. The name, therefore, will be

generated automatically and the file will be created in the Container private area.

206

Base Types and Interfaces

Input

<target>vzadevm</target>

<data>

<create_drive>

</create_drive>

</vzadevm>

</data>

</packet>

Output

The output below contains the name of the image file: lpbk0004.efd

<?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/vza/4.0.0/vzadevm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="2cc46487129t66bbre80"

time="2007-05-15T13:24:59+0000" priority="0" version="4.0.0">

<ns1:origin>vzadevm</ns1:origin>

<ns1:target>vzclient2</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzadevm>

<ns2:device_info>

<ns2:device>lpbk0004.efd</ns2:device>

</ns2:device_info>

</ns2:vzadevm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Example 3:

This example demonstrates how to create a shared SCSI storage device inside a Container.

Input

<target>vzadevm</target>

<data>

<create_drive>

</create_drive>

</vzadevm>

</data>

</packet>

207

Base Types and Interfaces

delete_drive

This call is available on Windows only.

Summary:

Unmounts and deletes the specified filesystem image file.

Request specification:

Name Min/Max Type Description

delete_drive

{

eid 0..1 eid_type (p. Server ID.

29)

[ Denotes a choice between the

point and the device elements.

point 1..1 string Mount point.

device 1..1 string This parameter is not currently used.

]

}

Returns:

OK/Error

Description:

The delete_drive call unmounts the EFD image from the specified Container that was

previously mounted using the create_drive (p. 203) or the new_mount (p. 222) calls. The

image file is then permanently deleted from the Hardware Node or the Container private area.

CAUTION! You will not be able to re-mount the file and recover its contents after executing this call.

To unmount the file system image without deleting the image file, use the umount call (p. 230).

Example:

<target>vzadevm</target>

<data>

<delete_drive>

</delete_drive>

</vzadevm>

</data>

</packet>

208

Base Types and Interfaces

format_drive

This call has not been implemented in the current Agent version.

Summary:

Formats a disk drive.

Request specification:

Name Min/Max Type Description

format_drive

{

device 1..1 string Device name.

type 1..1 string Filesystem type to create.

label 0..1 string Volume label.

block_size 0..1 long Filesystem block size (in bytes).

}

209

Base Types and Interfaces

forward_device

This call is currently available on Windows only.

Summary:

Makes a SCSI device on the Hardware Node accessible from within a Virtuozzo Container.

Request specification:

Name Min/Max Type Description

forward_device

{

forward 1..1

{

source 1..1 Source device information.

{

eid 0..1 eid_type (p. Not used here.

29)

device 1..1 common_deviceType

(p.

The device information.

200) Use scsi_deviceType type (p.

201) -- the the subtype of

common_deviceType (p. 200)

-- when populating this structure.

}

destination 1..1 Target device information.

{

eid 0..1 eid_type (p. Target server ID.

29)

device 1..1 common_deviceType

(p.

The device info as you want to be

displayed in the target server.

200)

}

Returns:

OK/Error

Description:

210

Base Types and Interfaces

This functionality exists for the purpose of setting up SAN (Storage Area Networks) based

Container clustering. One of the requirements for setting up SAN based clustering is the ability to

access remote storage devices (shared SCSI, fiberchannel, etc.) from within a Container by

mounting such a device inside the Container. The forward_device call allows to accomplish this

task. The source device information must include the name and the ID of the device (the ID is

contained in the physical_name element). To retrieve the list of SCSI devices available on the

Hardware Node, use the list_device call (p. 217) and select the entries from the result set that

are contained in the device element of type scsi_deviceType (p. 201). The following is an

example of such an entry:

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>S SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

<ns2:physical_name>

U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0Rf

Vk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4wXDQm

M0E3Mzk1MjkmMCYwMDA=

</ns2:physical_name>

</ns2:device>

The target device information must include the ID of the server where you would like to mount the

drive, and the device info (name, description) as you want it to be displayed in the target server.

Example:

Input

<packet xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/devm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0">

<target>vzadevm</target>

<data>

<forward_device>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>S SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

<ns2:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMDA=</ns2:physical_name>

</ns2:device>

</source>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>My SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

</ns2:device>

</destination>

</forward>

</forward_device>

</vzadevm>

</data>

</packet>

211

Base Types and Interfaces

get_info

Summary:

Retrieves information about all available filesystems, partitions, and devices from the current server.

Request specification:

Name Min/Max Type Description

get_info 0..1 none

Returns:

Name Min/Max Type Description

device_info

{

filesystem 0..[] string Filesystem type.

device 0..[] string Device name.

partition 0..[] string Partition name.

}

Example:

Input

<target>vzadevm</target>

<data>

<get_info/>

</vzadevm>

</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/vza/4.0.0/vzadevm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="22c4649b5f1t26e9rf74"

time="2007-05-15T16:57:31+0000" priority="0" version="4.0.0">

<ns1:origin>vzadevm</ns1:origin>

<ns1:target>vzclient5-1df4b04e-0d55-f246-b718-89bbc62fd371</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzadevm>

<ns2:device_info>

<ns2:partition>/dev/sda1</ns2:partition>

<ns2:partition>/dev/sda2</ns2:partition>

<ns2:partition>/dev/sda3</ns2:partition>

<ns2:partition>/dev/sda5</ns2:partition>

<ns2:partition>/dev/dm-0</ns2:partition>

<ns2:filesystem>auto</ns2:filesystem>

212

Base Types and Interfaces

</ns2:device_info>

</ns2:vzadevm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

213

Base Types and Interfaces

get_mounts

Summary:

Retrieves information about the filesystems mounted on the specified server.

Request specification:

Name Min/Max Type Description

get_mounts

{

eid 0..1 eid_type (p. Server ID. If omitted, a list of file systems

mounted in the current server will be

retrieved.

29)

}

Returns:

Name Min/Max Type Description

mount Mount information.

{

permanent 0..1 boolean Contains true if the filesystem is mounted

permanently. Contains false otherwise.

Permanently mounted filesystems have

corresponding entries in /etc/fstab file

and are mounted automatically every time

the system reboots.

device 0..1 string Device name, e.g. /dev/fd0

point 1..1 string Mount point, e.g. /mnt/floppy

filesystem 0..1 string Filesystem type.

active 0..1 boolean Contains true if mount is active. Contains

false otherwise.

Temporarily mounted filesystems exist only

in the "active" state. Trying to make the

temporary mount inactive will remove the

mount from the system.

}

Returns:

Name Min/Max Type Description

mount Mount information.

{

214

Base Types and Interfaces

device 0..1 string Device name. Can be a letter of the

physical drive on the Hardware Node or the

name of the loopback-mounted filesystem

image.

point 1..1 string The drive letter the filesystem is mounted

to.

size 0..1 long The total size of the media in the mounted

physical drive or the size of the loopback-

mounted file, in bytes.

}

Description:

On Linux, the get_mounts call retrieves information about currently mounted filesystems

(usually a device, but can also be a directory name or a dummy).

On Windows, it is possible to mount a physical drive or a filesystem image. Depending on the

source, the get_mounts call returns the following information:

• If the device is a physical drive on the Hardware Node, the device parameter will contain the

drive letter. For example, if a Hardware Node has a CD-ROM drive with a letter D: assignment,

and this drive is mounted on a server as drive F:, the device parameter will contain the D:

and the point parameter will contain the F:. The size parameter will contain the total size of

the media in the drive (hard disk partition, floppy disk, CD-ROM, etc.).

• If the device is a loopback-mounted filesystem image, the device parameter will contain the

name and path of the file and the point parameter will contain the drive letter that the image

file is mounted to. The size parameter will contain the file size in bytes.

Example:

Input

<target>vzadevm</target>

<data>

<get_mounts>

</get_mounts>

</vzadevm>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>devm</ns1:origin>

<ns1:target>vzclient5</ns1:target>

<ns1:data>

<ns2:devm>

<ns2:mount>

<ns2:device>/dev/VolGroup00/LogVol00</ns2:device>

<ns2:filesystem>ext3</ns2:filesystem>

215

Base Types and Interfaces

<ns2:permanent>1</ns2:permanent>

<ns2:active>1</ns2:active>

<ns2:point>/</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>LABEL=/boot</ns2:device>

<ns2:filesystem>ext3</ns2:filesystem>

<ns2:permanent>1</ns2:permanent>

<ns2:point>/boot</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/sdb1</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:permanent>1</ns2:permanent>

<ns2:point>/vz</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/hdd</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:point>/media/cdrom</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/hdc</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:point>/media/cdrom1</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/hdb</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:point>/media/cdrom2</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/hda</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:point>/media/cdrom3</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>/dev/fd0</ns2:device>

<ns2:filesystem>auto</ns2:filesystem>

<ns2:point>/media/floppy</ns2:point>

</ns2:mount>

</ns2:devm>

</ns1:data>

</ns1:packet>

Example:

Input

<target>vzadevm</target>

<data>

<get_mounts>

</get_mounts>

</vzadevm>

</data>

</packet>

Output

216

Base Types and Interfaces

<?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/vza/4.0.0/vzadevm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="2dc464871d0t428bre80"

time="2007-05-15T13:27:38+0000" priority="0" version="4.0.0">

<ns1:origin>vzadevm</ns1:origin>

<ns1:target>vzclient2</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzadevm>

<ns2:mount>

<ns2:device>root.efd</ns2:device>

<ns2:size>174094336</ns2:size>

<ns2:point>C:</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>C:\img.efd</ns2:device>

<ns2:size>6027264</ns2:size>

<ns2:point>F:</ns2:point>

</ns2:mount>

<ns2:mount>

<ns2:device>lpbk0000.efd</ns2:device>

<ns2:size>1000011776</ns2:size>

<ns2:point>K:</ns2:point>

</ns2:mount>

</ns2:vzadevm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

217

Base Types and Interfaces

list_device

This call is available on Windows only.

Summary:

Lists devices installed on the Hardware Node.

Request specification:

Name Min/Max Type Description

list_device

{

device 0..[] common_deviceType

(p.

Device info. If none specified,

returns a list of all available devices.

200)

}

Returns:

Name Min/Max Type Description

device 0..1 common_deviceType

(p.

Device information.

200) The actual data type returned here

can be used to identify the device

type (SCSI, other Windows devices).

See the subtypes of the

common_deviceType (p. 200) for

the available types. When setting up

Container clustering, select the

desired SCSI device from the list.

Example:

Input

<data>

<devm>

<list_device/>

</devm>

</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/devm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="55c464dc9d9t2350r878"

time="2007-05-19T14:44:18+0000" priority="0" version="4.0.0">

<ns1:origin>devm</ns1:origin>

<ns1:target>vzclient6</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

218

Base Types and Interfaces

<ns1:data>

<ns2:devm>

<ns2:device xsi:type="ns2:windows_deviceType">

<ns2:name>Microsoft AC Adapter</ns2:name>

<ns2:description>Microsoft AC Adapter</ns2:description>

<ns2:physical_name>QUNQSVxBQ1BJMDAwM1wx</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:windows_deviceType">

<ns2:name>ACPI Fixed Feature Button</ns2:name>

<ns2:description>ACPI Fixed Feature Button</ns2:description>

<ns2:physical_name>QUNQSVxGSVhFREJVVFRPTlwyJkRBQkEzRkYmMA==</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:windows_deviceType">

<ns2:name>Microsoft System Management BIOS Driver</ns2:name>

<ns2:description>Microsoft System Management BIOS Driver</ns2:description>

<ns2:physical_name>Uk9PVFxTWVNURU1cMDAwMg==</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>VMware, VMware Virtual S SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

<ns2:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMDA=</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>VMware, VMware Virtual S SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

<ns2:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMTA=</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:windows_deviceType">

<ns2:name>Generic volume</ns2:name>

<ns2:description>Generic volume</ns2:description>

<ns2:physical_name>U1RPUkFHRVxWT0xVTUVcMSYzMEE5NjU5OCYwJlNJR05BVFVSRUM2NzhERTkxT0ZGU0VU

N0UwMExFTkdUSDNGRkFCRDIwMA==</ns2:physical_name>

</ns2:device>

<ns2:device xsi:type="ns2:windows_deviceType">

<ns2:name>Generic volume</ns2:name>

<ns2:description>Generic volume</ns2:description>

<ns2:physical_name>U1RPUkFHRVxWT0xVTUVcMSYzMEE5NjU5OCYwJlNJR05BVFVSRUVGMThFRjE4T0ZGU0VU

N0UwMExFTkdUSDFGRjU4MjgwMA==</ns2:physical_name>

</ns2:device>

</ns2:devm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

219

Base Types and Interfaces

list_forward

This call is available on Windows only.

Summary:

Lists the device forwarding information. See the forward_device call (p. 209) for more info on

device forwarding.

Request specification:

Name Min/Max Type Description

list_forward

{

eid 0..1 eid_type (p. The ID of the server for which you

would like to see the device

forwarding information.

29)

}

220

Base Types and Interfaces

Returns:

Name Min/Max Type Description

forward 1..[] A list of "forwarded" devices.

{

source 1..1 Source device information.

{

eid 0..1 eid_type (p. 29) Host server ID.

device 0..1 common_deviceType

(p. 200)

Device information.

}

destination Destination device information.

{

eid 0..1 eid_type (p. 29) Server ID.

device 0..1 common_deviceType

(p. 200)

Device information.

}

Example:

Input

<target>vzadevm</target>

<data>

<list_forward>

</list_forward>

</vzadevm>

</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:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/devm"

xmlns:ns2="http://www.swsoft.com/webservices/vza/4.0.0/vzadevm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="51c464db67ft56aer878"

time="2007-05-19T13:21:44+0000" priority="0" version="4.0.0">

<ns1:origin>vzadevm</ns1:origin>

<ns1:target>vzclient6</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzadevm>

<ns2:forward>

<ns2:source>

221

Base Types and Interfaces

<ns2:device xsi:type="ns3:windows_deviceType">

<ns3:name>S SCSI Disk Device</ns3:name>

<ns3:description>SCSI Disk Device</ns3:description>

<ns3:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMDA=</ns3:physical_name>

</ns2:device>

</ns2:source>

<ns2:destination>

<ns2:eid>7f29d970-3e31-46f3-9b59-2654329e3e55</ns2:eid>

<ns2:device xsi:type="ns3:windows_deviceType">

<ns3:name>My SCSI Disk Device</ns3:name>

<ns3:description>S SCSI Disk Device</ns3:description>

<ns3:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMDA=</ns3:physical_name>

</ns2:device>

</ns2:destination>

</ns2:forward>

</ns2:vzadevm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

222

Base Types and Interfaces

new_mount

Summary:

Mounts a Hardware Node device on the Hardware Node or inside a Virtuozzo Container.

Request specification:

Name Min/Max Type Description

new_mount mount_deviceType

(p.

199)

{

eid 1..1 eid_type (p. Server ID.

29)

}

Returns:

OK/Error

Description:

The device parameter specifies the name of the device that you would like to mount. The

point parameter is used to specify the name of the directory where you would like to mount the

device. If the specified directory does not exist, it will be created. Once the device is mounted, the

mount point will refer to the root of the file system on the device.

If the filesystem element is absent or set to auto, the system will attempt to detect the file

system type automatically. It is not always possible to recognize some file systems due to

differences in implementations. That's why you might want to specify the file system type via the

filesystem option.

If the permanent parameter is set to true, the device will be mounted permanently, which means

that the device will be mounted automatically every time the server is started or restarted. If the

parameter is set to false or omitted, the device will be mounted temporarily, i.e. the mount point

will exist for the duration of the current session only. You can change the status of the mount point

to "permanent" later if you wish. In order to do that, execute the new_mount call again passing the

same parameters and values as when you created the mount point except the permanent

parameter which should be set to true, and the active parameter which should be omitted from

the call (see code examples below). Please note that when mounting a device on the Hardware

Node, the mount information is written into the /etc/fstab file. However, when mounting a

Hardware Node device inside a Virtuozzo Container, the mount information is written into one of the

internal Virtuozzo script files, which are executed at the time a specific Container is started. Do not

attempt to modify the fstab file inside the Container manually as it will not work.

223

Base Types and Interfaces

If the active element is included, the command will make an attempt to attach the file system on

the device to the mount point at the end of the operation. If this option is omitted or set to false,

the mount point will still be created but it will remain in the "inactive" state, in which case you will

have to activate it before it can be used. To activate a mount point (to attach the filesystem on the

device to it), use the new_mount call again passing the same parameters and values as when you

created the mount point except the active parameter which should be set to true, and the

permanent parameter which should be omitted from the call (see code examples below). If the

device doesn't contain a valid file system (e.g. the CD drive is empty), the mount point will be

created but will also remain in the "inactive" state. Note that temporary mounts cannot exist in the

"inactive" state. If you specify the permanent parameter and the active parameter both set to

false (or if you omit both parameters), the mount point will not be created.

To retrieve the list of the available filesystems, partitions, and devices, use the get_info call (p.

211).

On Windows, the new_mount call allows to do the following:

• Mount a physical drive installed on the Hardware Node inside a Virtuozzo Container. The

device parameter is used to specify the physical drive letter. The point parameter is used to

specify the drive letter representing the mount point. For example, if a CD-ROM drive is

assigned the letter D: on the Hardware Node and you would like to mount it to drive letter F:

on a Virtuozzo Container, the device parameter should contain the D: value and the point

parameter should contain the F: value.

• Loopback-mount EFD filesystem images. EFD is Parallels' proprietary filesystem. Use the

device parameter to specify the image file name and path. The point parameter must

contain the drive letter that you want to use for this mount. The interface parameter must be

omitted from the request. Please note that you cannot mount the same image in more than one

Container. You can create EFD images using the create_drive call (p. 203).

• Configure Windows Cluster Server (MSCS) support. If you have an EFD image file on the

Hardware Node (or on a remote network share), you can mount it inside a Virtuozzo Container

as an emulated shared SCSI storage device. To mount a shared image, use the device

parameter to specify the image file name and path on the Hardware Node. The point

parameter must contain the drive letter that you would like to use for the mount. The value of

the interface parameter must be SCSI, which indicates that you are mounting an image as

an emulated shared SCSI storage device. Before you can use the new drive inside the

Container, you will have to initialize it (see the create_drive call (p. 203) for more information

on how to initialize the new drive in Windows and for more info Windows Cluster Server support

in Virtuozzo Containers).

Example 1:

Temporarily mounting a Hardware Node partition inside a Container.

<target>vzadevm</target>

<data>

224

Base Types and Interfaces

<new_mount>

<point>/mydrive</point>

</new_mount>

</vzadevm>

</data>

</packet>

Example 2:

Changing the status of the existing mount point from "temporary" to "permanent".

<target>vzadevm</target>

<data>

<new_mount>

<point>/mydrive</point>

</new_mount>

</vzadevm>

</data>

</packet>

Example 3:

Changing the state of the existing mount point from "inactive" to "active", i.e. attaching the

filesystem on the device to the mount point.

<target>vzadevm</target>

<data>

<new_mount>

<point>/mydrive</point>

</new_mount>

</vzadevm>

</data>

</packet>

Example 4:

Mounting the CD-ROM drive D: installed on the Hardware Node inside the specified Container.

Assigning the drive letter F: to the new mount inside the Container.

<target>vzadevm</target>

<data>

<new_mount>

225

Base Types and Interfaces

</new_mount>

</vzadevm>

</data>

</packet>

Example 5:

Mounting an EFD filesystem image inside a Container.

<target>vzadevm</target>

<data>

<new_mount>

</new_mount>

</vzadevm>

</data>

</packet>

226

Base Types and Interfaces

remove_forward

This call is available on Windows only.

Summary:

Cancels the forwarding of a device that was added to a Virtuozzo Container using the

forward_device call (p. 209).

Request specification:

Name Min/Max Type Description

remove_forward

{

forward 1..1

{

source 1..1 The original source device

information.

{

eid 0..1 eid_type (p. Not used here.

29)

device 0..1 common_deviceType

(p.

Device information.

200)

}

destination The device information inside a

Container.

{

eid 0..1 eid_type (p. Server ID.

29)

device 0..1 common_deviceType

(p.

Device information.

200)

}

Returns:

OK/Error

Description:

The remove_forward call has essentially the same exact parameters and values as the

forward_device call (p. 209). The only difference between the two is the name of the call itself.

Example:

227

Base Types and Interfaces

<packet xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/devm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0">

<target>vzadevm</target>

<data>

<remove_forward>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>S SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

<ns2:physical_name>U0NTSVxESVNLJlZFTl9WTVdBUkVfJlBST0RfVk1XQVJFX1ZJUlRVQUxfUyZSRVZfMS4w

XDQmM0E3Mzk1MjkmMCYwMDA=</ns2:physical_name>

</ns2:device>

</source>

<ns2:device xsi:type="ns2:scsi_deviceType">

<ns2:name>My SCSI Disk Device</ns2:name>

<ns2:description>Disk drive</ns2:description>

</ns2:device>

</destination>

</forward>

</remove_forward>

</vzadevm>

</data>

</packet>

228

Base Types and Interfaces

resize_drive

This call is available on Windows only.

Summary:

Resizes an EFD filesystem image mounted inside a Container.

Request specification:

Name Min/Max Type Description

resize_drive

{

size 1..1 long The new size in bytes. The minimum

allowed size is 6 megabytes. There's

no limit on the max size.

eid 0..1 eid_type (p. The ID of the server where the

image is mounted.

29)

[

point 1..1 string Mount point.

device 1..1 string This parameter is not currently used.

]

}

Returns:

OK/Error

Errors

See devm Errors

Description:

For more info on creating and mounting EFD filesystem images, see the create_drive call (p.

203).

Example:

<target>vzadevm</target>

<data>

<resize_drive>

</resize_drive>

</vzadevm>

</data>

229

Base Types and Interfaces

</packet>

230

Base Types and Interfaces

umount

Summary:

Unmounts a device that was previously mounted using the new_mount call (p. 222).

Request specification:

Name Min/Max Type Description

umount mount_deviceTyp

e (p.

199)

{

eid 1..1 eid_type (p. Server ID.

29)

}

Returns:

OK/Error

Description:

On Linux, the umount call is used to deactivate an existing mount point (i.e. to detach the

specified filesystem from the file hierarchy), to change the mount point status from "permanent" to

"temporary", or to remove the mount point from the system completely.

To deactivate the mount point, include the point parameter containing the directory name, the

eid parameter containing the Server ID, and the active parameter containing the true value

(see code examples below).

To change the status of the mount point from "permanent" to "temporary", include the point

parameter containing the directory name, the eid parameter containing the Server ID, and the

permanent parameter containing the true value (see code examples below). Please note that

temporary mounts can only exist in the "active" state, therefore you cannot make a mount point

temporary if it is not currently active.

To remove the mount point, include the point parameter containing the directory name, the eid

parameter containing the Server ID, the point parameter containing the directory name, and the

permanent parameter containing the true value (see code examples below).

On Windows, the umount call removes the drive that has been associated with a physical

storage device on the Hardware Node or an EFD image. When unmounting an EFD image, the

image file will not be physically deleted and can be re-mounted later. To permanently delete the

image file, use the delete_drive call (p. 207). The following parameters are used:

point -- the drive letter (e.g. E:) associated with the device or the image file.

eid -- Server ID.

231

Base Types and Interfaces

Example 1:

Deactivating the existing mount point.

<target>vzadevm</target>

<data>

<point>/mydrive</point>

</umount>

</vzadevm>

</data>

</packet>

Example 2:

Making the mount point temporary.

<target>vzadevm</target>

<data>

<point>/mydrive</point>

</umount>

</vzadevm>

</data>

</packet>

Example 3:

Removing the mount point.

<target>vzadevm</target>

<data>

<point>/mydrive</point>

</umount>

</vzadevm>

</data>

</packet>

Example 4:

Unmounting a device that was previously mounted inside a Container (the device can be a physical

drive or an EFD image).

<target>vzadevm</target>

232

Base Types and Interfaces

<data>

</umount>

</vzadevm>

</data>

</packet>

sample_manager

Purpose:

Sample configuration management interface. Sample configurations are used to create Virtuozzo

Container optimized for a particular purpose. For example, a general purpose Container may not

require as much resources as a Container that will be hosting a database server, so instead of

configuring each server individually, a sample configuration is created for each purpose in advance

and is saved in a file on the Hardware Node. The information stored in these files can then be used

to create new Containers. The env_samplem interface allows to create, modify, retrieve, and

delete the sample configuration data.

Calls

Call Description

get_sample_conf (p. 233) Retrieves a list of sample configurations from the

Hardware Node.

set_sample_conf Modifies an existing sample configuration or creates a

new one.

del_sample_conf Deletes an existing sample configuration.

233

Base Types and Interfaces

get

Summary:

Retrieves a list of Container sample configurations from a physical server.

Request specification:

Name Min/Max Type Description

get

{

id 0..[] string A list of IDs of sample

configurations to include in the

result set. If none specified, all

available sample configurations

will be retrieved.

eid 0..1 eid_type (p. 29) Server ID. If specified, retrieves

only the sample configurations

that can be used to create

Containers on the specified host.

}

Returns:

Name Min/Max Type Description

0..[] sample_confType

(p. 61)

Sample configuration data.

234

Base Types and Interfaces

Description:

The get call allows performing the following tasks:

• Retrieve a list of sample configurations available on the current server. If the server is a Master

Node in a group, the call retrieves sample configurations from every Node in the group. To

perform this task, do not include any parameters.

• Retrieve a specific sample configuration. To perform this task, specify the sample configuration

ID using the id element.

• Retrieve a list of sample configurations that can be used to create Containers on the specified

hosts. Consider the following example. Let's say that you have a group set up and you would

like to create Containers on one of the Nodes in the group. Each Node in the group may

contain unique sample configuration files, any of which can be used to create Virtuozzo

Containers on any of the Nodes in the group. However, not all sample configurations may be

compatible with the given Hardware Node because each sample configuration is designed for a

specific platform (Linux, Windows), CPU architecture, etc. To get the list of the sample

configurations that can be used to create Containers on a specific node, specify the Server ID

of the Node using the eid parameter.

The following examples demonstrate how to perform each of the tasks described above.

Example 1:

Retrieving a list of all sample configurations available on the Hardware Node (or in the entire group,

if we are connected to the Master Node).

Input

<target>vzasample_manager</target>

<data>

<vzasample_manager>

<get/>

</vzasample_manager>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns3="http://www.swsoft.com/webservices/vzl/4.0.0/sample_manager"

xmlns:ns2="http://www.swsoft.com/webservices/vza/4.0.0/vzasamplem"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns5="http://www.swsoft.com/webservices/vza/4.0.0/vzatypes"

xmlns:ns4="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="1bc4cf39711t491cr4c4" type="0" time="2010-11-29T12:10:47+0000">

<origin>vzasample_manager</origin>

<target>vzclient45-a91bcfea-3de2-ba43-859a-26f58f14706e</target>

<dst>

</dst>

<data>

<vzasample_manager>

235

Base Types and Interfaces

<virtual_config xsi:type="ns4:env_configType">

<on_boot>1</on_boot>

<offline_management>1</offline_management>

</address>

<qos>

<id>avnumproc</id>

</qos>

<qos>

<id>cpuunits</id>

</qos>

<qos>

<id>dcachesize</id>

</qos>

<qos>

<id>dgramrcvbuf</id>

</qos>

<qos>

<id>diskinodes</id>

</qos>

<qos>

<id>diskspace</id>

</qos>

<qos>

<id>kmemsize</id>

</qos>

<qos>

<id>lockedpages</id>

</qos>

<qos>

<id>numfile</id>

</qos>

<qos>

<id>numflock</id>

</qos>

<qos>

<id>numiptent</id>

</qos>

<qos>

236

Base Types and Interfaces

<id>numothersock</id>

</qos>

<qos>

<id>numproc</id>

</qos>

<qos>

Example 2:

Retrieving a specific sample configuration.

Input

<target>vzasample_manager</target>

<data>

<vzasample_manager>

<get>

</get>

</vzasample_manager>

</data>

</packet>

The output here is similar to the output shown in the previous example.

Example 3:

Retrieving a list of sample configurations that can be used to create Virtuozzo Containers.

Input

<target>server_group</target>

<data>

<server_group>

<get_list>

<type>generic</type>

</get_list>

</server_group>

</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/server_group"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="dc45ed4e57t41bbr274"

time="2007-03-06T09:05:31+0000" priority="0" version="4.0.0">

<ns1:origin>server_group</ns1:origin>

<ns1:target>vzclient5</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:server_group>

<ns2:eid>565b96bd-d2da-4c7e-a212-0943a4bd6b29</ns2:eid>

</ns2:server_group>

237

Base Types and Interfaces

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Now, that we have the Server ID of the host, use the get_sample_conf call to get the list of the

compatible sample configurations.

Input

<target>vzasample_manager</target>

<data>

<vzasample_manager>

<get>

</get>

</vzasample_manager>

</data>

</packet>

envm

Purpose:

The base server management interface that provides calls for physical and virtual server

management. Supported virtualization technologies have their own server management interfaces,

which are derived from the envm interface.

Derived interfaces:

vzaenvm (p. 633)

vzpenvm (p. 716)

238

Base Types and Interfaces

Calls

Call Description

create (p. 239) Creates a new virtual server.

repair (p. 259) Creates a Virtuozzo Container as a temporary

replacement for another Container that needs repairs.

stop_repair (p. 271) Stops and destroys the temporary Container created by

the repair call.

start (p. 269) Starts the specified Container.

stop (p. 270) Stops the specified Container.

restart (p. 260) Restarts a Container.

destroy (p. 246) Destroys a Container.

suspend (p. 272) Suspends a Container.

resume (p. 261) Resumes a Container that was previously suspended

with the suspend call.

get_info (p. 247) Retrieves Container information.

get_list (p. 253) Gets a list of Containers from a Hardware Node.

set (p. 262) Sets the Container configuration parameters.

put_private Creates or replaces a file in the Container private area.

get_private Retrieves the contents of a file from the private area of

the specified Container.

get_vt_settings (p. 257) Retrieves Virtuozzo Containers settings.

set_vt_settings (p. 268) Allows to modify Virtuozzo Containers settings.

get_vt_info (p. 256) Retrieves read-only information about the Virtuozzo

Containers software installed on the Hardware Node.

get_log (p. 255) Retrieves Virtuozzo Containers logs.

get_native_config (p. 273) Obtains a native Virtuozzo Container configuration based

on the provided virtual configuration.

get_virtual_config Obtains virtual configuration based on the provided native

Container configuration.

239

Base Types and Interfaces

create

Summary:

Creates a new virtual environment.

This is a logged operation.

Request specification:

Name Min/Max Type Description

create

{

force 0..1 none Ignore pool problems and forcibly

create a virtual server.

config 1..1 env_configType (p.

37)

Container configuration parameters.

• When creating a Virtuozzo

Container, use

venv_configType (p. 627),

which is a Virtuozzo

implementation of the config

structure.

• When creating a virtual

machine, use a VM specific

venv_configType (p. 695).

default 0..1 A list of configuration parameters that

should be set to default values.

Use this option when you are using a

sample configuration file but would like

to use the default values for some of

the parameters. If you are specifying all

of the parameters manually, you can

also use this list to set some of the

parameters to defaults.

{

parameter 1..[] string The names of the configuration

parameter to set to default values.

}

Returns:

Name Min/Max Type Description

env 0..[] envType (p. 39) The new virtual server information.

Description:

240

Base Types and Interfaces

To create new Virtuozzo Containers, use vzaenvm (p. 633), which is a Parallels Virtuozzo

implementation of this interface. The configuration parameters (the config element) must also be

passed using the venv_configType (p. 627), which is a Virtuozzo implementation of the generic

env_configType structure (p. 37).

The Container configuration parameters can be passed explicitly by specifying the parameters and

values or they can be passed by specifying the ID of a sample configuration file. Using a sample

configuration file is a standard way of creating a Container. All of the parameters in the

venv_configType (p. 627) structure are optional. You can pass just the sample configuration ID

and that should be enough to create a Container if the configuration file contains all the necessary

parameters. Some of those mandatory parameters are the OS template name, QoS counters, and

some others. Some configuration parameters can only be set manually. For example, parameters

like computer name, hostname, IP addresses will never have default values in a sample

configuration file, so if you want to set them, you have to populate the appropriate elements of the

configuration structure manually.

To create new virtual machines, use vzpenvm (p. 716), which is Parallels Server implementation of

this interface. The configuration parameters for a new virtual machine must also be passed using

the VM specific venv_configType (p. 695).

Example 1:

Creating a Virtuozzo Container using the following parameters:

Parameter Value Description

base_sample_id 9fb463e4-6f19-441c-

9c5d-7dc26585b742

The sample configuration ID. To retrieve a

list of sample configurations from the

Hardware Node, use get. (p. 233)

os_template/name redhat-as3-minimal OS template name. To retrieve the list of the

available OS template, use

packagem/list (p. 420).

name Test-VE5 Computer name.

hostname Host-105 Hostname.

The selection of the hosting server cannot

be automated.

veid 105 Container ID.

on_boot true Start the Container automatically on system

boot.

offline_management true Turn the offline-management feature on for

the Container.

241

Base Types and Interfaces

ip_address 81.20.139.91 IP address. We will assign the address to

the default venet0 virtual network adapter.

The venet0 adapter is created

automatically for every Container. We could

also create our own virtual network adapter

inside a Container and customize it

according to our needs. For more info on

how to create and configure virtual ethernet

adapters, see venv_configType (p. 627)

and net_vethType (p. 622).

Note: To automate IP address allocation,

specify the IP address. A vacant IP address

from a random IP pool will be assigned to

the Container.

nameserver 85.88.15.6 Name server IP address.

nameserver 85.88.14.6 Name server IP address.

Input:

<target>vzaenvm</target>

<data>

<base_sample_id>e89373d0-d13c-1741-a0e5-212d7cd3ae61</base_sample_id>

<on_boot>true</on_boot>

<offline_management>true</offline_management>

<os_template>

<name>redhat-as3-minimal</name>

</os_template>

<net_device>

<id>venet0</id>

<ip_address>

</ip_address>

<host_routed/>

</net_device>

</config>

</create>

</vzaenvm>

</data>

</packet>

Output:

The output contains the new Container information, including the Server ID (EID).

242

Base Types and Interfaces

<?xml version="1.0" encoding="UTF-8"?><ns1:packet

xmlns:ns4="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/envm"

xmlns:ns3="http://www.swsoft.com/webservices/vza/4.0.0/vzatypes"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="fc468cd97at5f90redc"

time="2007-07-05T14:33:42+0000" priority="4000" version="4.0.0">

<ns1:origin>vzaenvm</ns1:origin>

<ns1:target>vzclient3-cfa5a2f6-4bc8-9140-88a2-15b1eae98cac</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:vzaenvm>

<ns2:env xsi:type="ns3:envType">

<ns4:parent_eid>00000000-0000-0000-0000-000000000000</ns4:parent_eid>

<ns4:eid>78c510e9-6e4f-5349-9e22-48841e709fea</ns4:eid>

<ns4:status xsi:type="ns4:env_statusType">

<ns4:state>1</ns4:state>

</ns4:status>

<ns4:alert>0</ns4:alert>

<ns4:config xsi:type="ns4:env_configType"/>

<ns4:virtual_config xsi:type="ns3:venv_configType">

<base_sample_id>e89373d0-d13c-1741-a0e5-212d7cd3ae61</base_sample_id>

<on_boot>true</on_boot>

<offline_management>true</offline_management>

<os_template>

<name>redhat-as3-minimal</name>

</os_template>

<net_device>

<id>venet0</id>

</ip_address>

<host_routed/>

</net_device>

<ns4:architecture>i386</ns4:architecture>

<ns4:address>

<ns4:ip>0.0.0.0</ns4:ip>

</ns4:address>

<ns4:qos>

<ns4:id>avnumproc</ns4:id>

<ns4:hard>40</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>cpuunits</ns4:id>

<ns4:hard>1000</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>dcachesize</ns4:id>

<ns4:hard>1097728</ns4:hard>

<ns4:soft>1048576</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>dgramrcvbuf</ns4:id>

<ns4:hard>132096</ns4:hard>

<ns4:soft>132096</ns4:soft>

</ns4:qos>

243

Base Types and Interfaces

<ns4:qos>

<ns4:id>diskinodes</ns4:id>

<ns4:hard>220000</ns4:hard>

<ns4:soft>200000</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>diskspace</ns4:id>

<ns4:hard>1153434</ns4:hard>

<ns4:soft>1048576</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>kmemsize</ns4:id>

<ns4:hard>2936012</ns4:hard>

<ns4:soft>2752512</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>lockedpages</ns4:id>

<ns4:hard>32</ns4:hard>

<ns4:soft>32</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>numfile</ns4:id>

<ns4:hard>2048</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numflock</ns4:id>

<ns4:hard>110</ns4:hard>

<ns4:soft>100</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>numiptent</ns4:id>

<ns4:hard>128</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numothersock</ns4:id>

<ns4:hard>80</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numproc</ns4:id>

<ns4:hard>65</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numpty</ns4:id>

<ns4:hard>16</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numsiginfo</ns4:id>

<ns4:hard>256</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>numtcpsock</ns4:id>

<ns4:hard>80</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>oomguarpages</ns4:id>

<ns4:hard>2147483647</ns4:hard>

<ns4:soft>6144</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>othersockbuf</ns4:id>

<ns4:hard>336896</ns4:hard>

244

Base Types and Interfaces

<ns4:soft>132096</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>physpages</ns4:id>

<ns4:hard>2147483647</ns4:hard>

<ns4:soft>0</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>privvmpages</ns4:id>

<ns4:hard>24576</ns4:hard>

<ns4:soft>22528</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>quotatime</ns4:id>

<ns4:hard>0</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>shmpages</ns4:id>

<ns4:hard>8192</ns4:hard>

</ns4:qos>

<ns4:qos>

<ns4:id>slmmemorylimit</ns4:id>

<ns4:hard>33521664</ns4:hard>

<ns4:soft>33521664</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>tcprcvbuf</ns4:id>

<ns4:hard>524288</ns4:hard>

<ns4:soft>319488</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>tcpsndbuf</ns4:id>

<ns4:hard>524288</ns4:hard>

<ns4:soft>319488</ns4:soft>

</ns4:qos>

<ns4:qos>

<ns4:id>vmguarpages</ns4:id>

<ns4:hard>2147483647</ns4:hard>

<ns4:soft>6144</ns4:soft>

</ns4:qos>

<ns3:origin_sample>basic</ns3:origin_sample>

<ns4:name>Test-VE5</ns4:name>

<ns4:hostname>Host-105</ns4:hostname>

</ns4:virtual_config>

</ns2:env>

</ns2:vzaenvm>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Example 2:

The following example creates a Container on a Windows platform. As in the Linux example above,

we also use a sample configuration file and setting some of the parameters manually, including

computer name, hostname, Container ID (veid), the "on-boot" parameter, and the IP address for

the default venet0 network adapter.

245

Base Types and Interfaces

Input

<target>vzaenvm</target>

<data>

<base_sample_id>46413905-b2d7-4f41-bcd6-e2662e63cd63</base_sample_id>

<on_boot>true</on_boot>

<net_device>

<id>venet0</id>

<ip_address>

</ip_address>

<host_routed/>

</net_device>

</config>

</create>

</vzaenvm>

</data>

</packet>

246

Base Types and Interfaces

destroy

Summary:

Destroys a virtual server.

A logged operation.

Request specification:

Name Min/Max Type Description

destroy

{

eid 1..1 eid_type (p. 29) Server ID.

}

Returns:

OK/Error.

Description:

The call destroys the specified virtual server. All the virtual server data is removed from the physical

server and cannot be recovered. You can only destroy a stopped virtual server.

To destroy a Virtuozzo Container, use the vzaenvm (p. 633) interface.

To destroy a virtual machine, use the vzpenvm (p. 716) interface.

Example:

<target>vzaenvm</target>

<data>

</destroy>

</vzaenvm>

</data>

</packet>

247

Base Types and Interfaces

get_info

Summary:

Retrieves a Hardware Node or a Virtuozzo Container, or a virtual machine configuration information.

Request specification:

Name Min/Max Type Description

get_info

{

eid 0..[] eid_type (p. 29) Server ID.

When retrieving information for a

Hardware Node, this element may be

omitted.

When retrieving information for a

Virtuozzo Container, specify its Server

ID, or omit the element to retrieve

information for all Containers on the

current host.

config 0..1 none Include this element to retrieve the

Container or virtual machine

configuration information. If the

element is omitted, the output will

contain only the basic information.

filter_config 0..1 Specify the configuration parameters

that you want to be included in the

output. The config element (above)

must also be included in the request.

If this element is omitted then all

available configuration parameters will

be retrieved.

{

<xs:any> xs:any A list containing the names of the

configuration parameter to include in

the output. For a list of the available

parameters see env_configType

structure (p. 37) (Hardware Node

information), or venv_configType

(p. 627) (Virtuozzo Container

configuration), or

VM specific venv_configType (p.

695) (.virtual machine configuration)

}

Returns:

Name Min/Max Type Description

248

Base Types and Interfaces

env 0..[] envType (p. 39) Configuration information.

Description:

The call is available in the base envm interface (p. 237) and in its descendants, the vzaenvm

interface (p. 633) (for Virtuozzo Containers) and vzpenvm interface (p. 716) ( for virtual machines).

Use the envm interface to retrieve the information for the Hardware Node that you are currently

connected to. Use the vzaenvm interface to get the information for a particular Virtuozzo Container

or vzpenvm interface to get the information for a particular virtual machine.

When retrieving information for a Virtuozzo Container, the output will contain the Container virtual

configuration information (p. 627). Most of the configuration parameters are optional, so some may

not be included in the output structure. If a parameter is not included, it means that its default value

is currently used. To determine the default value, first use the envm/get_vt_setting (p. 257)

call. If you don't see the parameter in the output, then, depending on the parameter data type, the

default value is determined as follows:

Data Type Default Value

boolean false

string Empty string

int 0 or maxint

Example:

Retrieving information for the Hardware Node.

Input

<data>

<envm>

<get_info>

</get_info>

</envm>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns2="http://www.swsoft.com/webservices/vzl/4.0.0/types"

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/envm"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" time="2007-11-21T07:10:35+0000"

id="8c4747000ct18ber448" priority="0" version="4.0.0">

<target>vzclient6-a0f0a8d0-6c35-c64b-8f16-c1f0e13295c6</target>

<dst>

</dst>

<data>

<envm>

249

Base Types and Interfaces

<parent_eid>00000000-0000-0000-0000-000000000000</parent_eid>

</status>

<type>generic</type>

<platform>Linux</platform>

<name>Red Hat Enterprise Linux Server release 5 (Tikanga)</name>

</os>

</address>

</config>

<virtual_config xsi:type="ns2:venv_configType"/>

</env>

</envm>

</data>

<src>

</src>

</packet>

Example:

Retrieving information for a Virtuozzo Container.

Input

<target>vzaenvm</target>

<data>

<get_info>

</get_info>

</vzaenvm>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>vzaenvm</ns1:origin>

<ns1:target>vzclient5</ns1:target>

<ns1:data>

<ns2:vzaenvm>

<ns2:env xsi:type="ns3:envType">

<ns3:parent_eid>89e27960-97b8-461f-902f-557b4b16784b</ns3:parent_eid>

<ns3:eid>3e25fee2-1163-4336-9e74-8b8097936d47</ns3:eid>

<ns3:status xsi:type="ns3:env_statusType">

<ns3:state>6</ns3:state>

</ns3:status>

<ns3:alert>0</ns3:alert>

250

Base Types and Interfaces

<ns3:config xsi:type="ns3:env_configType"/>

<ns3:virtual_config xsi:type="ns4:venv_configType">

<ns3:hostname>myhost</ns3:hostname>

<ns3:name>Mycomputer</ns3:name>

<ns3:offline_management>1</ns3:offline_management>

<ns3:on_boot>1</ns3:on_boot>

<ns3:os_template>

<ns3:version>20061020</ns3:version>

<ns3:name>redhat-as3-minimal</ns3:name>

</ns3:os_template>

<ns3:ve_root>/vz/root/$VEID</ns3:ve_root>

<ns3:ve_private>/vz/private/$VEID</ns3:ve_private>

<ns3:ve_type>

<ns3:veid>0</ns3:veid>

<ns3:type>1</ns3:type>

</ns3:ve_type>

<ns3:qos>

<ns3:id>avnumproc</ns3:id>

<ns3:hard>40</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>cpuunits</ns3:id>

<ns3:hard>1000</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>dcachesize</ns3:id>

<ns3:hard>1097728</ns3:hard>

<ns3:soft>1048576</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>dgramrcvbuf</ns3:id>

<ns3:hard>132096</ns3:hard>

<ns3:soft>132096</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>diskinodes</ns3:id>

<ns3:hard>220000</ns3:hard>

<ns3:soft>200000</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>diskspace</ns3:id>

<ns3:hard>1153434</ns3:hard>

<ns3:soft>1048576</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>kmemsize</ns3:id>

<ns3:hard>2936012</ns3:hard>

<ns3:soft>2752512</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>lockedpages</ns3:id>

<ns3:hard>32</ns3:hard>

<ns3:soft>32</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>numfile</ns3:id>

<ns3:hard>2048</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numflock</ns3:id>

<ns3:hard>110</ns3:hard>

251

Base Types and Interfaces

<ns3:soft>100</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>numiptent</ns3:id>

<ns3:hard>128</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numothersock</ns3:id>

<ns3:hard>80</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numproc</ns3:id>

<ns3:hard>65</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numpty</ns3:id>

<ns3:hard>16</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numsiginfo</ns3:id>

<ns3:hard>256</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>numtcpsock</ns3:id>

<ns3:hard>80</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>oomguarpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>6144</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>othersockbuf</ns3:id>

<ns3:hard>336896</ns3:hard>

<ns3:soft>132096</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>physpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>0</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>privvmpages</ns3:id>

<ns3:hard>24576</ns3:hard>

<ns3:soft>22528</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>quotatime</ns3:id>

<ns3:hard>0</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>shmpages</ns3:id>

<ns3:hard>8192</ns3:hard>

</ns3:qos>

<ns3:qos>

<ns3:id>tcprcvbuf</ns3:id>

<ns3:hard>524288</ns3:hard>

<ns3:soft>319488</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>tcpsndbuf</ns3:id>

252

Base Types and Interfaces

<ns3:hard>524288</ns3:hard>

<ns3:soft>319488</ns3:soft>

</ns3:qos>

<ns3:qos>

<ns3:id>vmguarpages</ns3:id>

<ns3:hard>2147483647</ns3:hard>

<ns3:soft>6144</ns3:soft>

</ns3:qos>

<ns3:veid>101</ns3:veid>

<ns3:type>virtuozzo</ns3:type>

<ns3:offline_service>vzpp</ns3:offline_service>

<ns3:offline_service>vzpp-plesk</ns3:offline_service>

<ns3:os xsi:type="ns3:osType">

<ns3:platform>Linux</ns3:platform>

<ns3:kernel>2.6.9-023stab033.6</ns3:kernel>

<ns3:version>20061020</ns3:version>

<ns3:name>redhat-as3-minimal</ns3:name>

</ns3:os>

<ns3:net_device xsi:type="ns4:net_vethType">

<ns3:id>venet0</ns3:id>

<ns3:ip_address>

<ns3:ip>10.100.23.203</ns3:ip>

</ns3:ip_address>

<ns4:host_routed/>

</ns3:net_device>

<ns3:address>

<ns3:ip>10.100.23.203</ns3:ip>

</ns3:address>

</ns3:virtual_config>

</ns2:env>

</ns2:vzaenvm>

</ns1:data>

</ns1:packet>

253

Base Types and Interfaces

get_list

Summary:

Retrieves Server IDs of the Hardware Node and Virtuozzo Containers or virtual machines that it

hosts.

Request specification:

Name Min/Max Type Description

get_list

{

count 0..1 int The maximum number of

the IDs to include in the list.

type 0..1 string Retrieve only the servers of

the specified type.

The parameter is not

currently used.

status 0..[] env_statusType (p. 39) Retrieve only the Containers

or virtual machines, which

status match one of the

statuses specified here. By

using this parameter, you

can, for example, retrieve

only the IDs of the running

or stopped Containers or

virtual machines, etc.

}

Returns:

Name Min/Max Type Description

eid 0..[] eid_type (p. 29) A list of Server IDs.

Description:

To retrieve a list of Virtuozzo Containers from the Hardware Node, use vzaenvm (p. 633), which is

a Virtuozzo implementation of this interface.

To retrieve a list of virtual machines from the Hardware Node, use vzpenvm (p. 716), which is

Parallels Server implementation of this interface.

Example:

Retrieving a list of running Virtuozzo Containers.

Input

<target>vzaenvm</target>

<data>

254

Base Types and Interfaces

<get_list>

</status>

</get_list>

</vzaenvm>

</data>

</packet>

Output

<ns1:packet version="4.0.0">

<ns1:origin>vzaenvm</ns1:origin>

<ns1:data>

<ns2:vzaenvm>

<ns2:eid>3e25fee2-1163-4336-9e74-8b8097936d47</ns2:eid>

<ns2:eid>72145bf0-7562-43d4-b707-cc33d37e3f10</ns2:eid>

<ns2:eid>6dbd99dc-f212-45de-a5f4-ddb78a2b5280</ns2:eid>

</ns2:vzaenvm>

</ns1:packet>

255

Base Types and Interfaces

get_log

Summary:

Retrieves Virtuozzo Containers log data.

Request specification:

Name Min/Max Type Description

get_log

{

start_time 0..1 datetime_type

(p. 28)

Start time of the log.

end_time 0..1 datetime_type

(p. 28)

End time of the log.

records 0..1 int The number of records from the end of

the log to include in the result set. If this

element is omitted, all available records

will be retrieved.

options 0..1 log_optionsTyp

e (p. 621)

Additional options.

}

Returns:

Name Min/Max Type Description

log 0..1 base64Binary Log data.

Example:

Input

<target>vzaenvm</target>

<data>

<get_log>

<start_time>2006-05-28T19:05:30-0500</start_time>

<end_time>2007-08-28T19:05:30-0500</end_time>

</options>

</get_log>

</vzaenvm>

</data>

</packet>

256

Base Types and Interfaces

get_vt_info

Summary:

Retrieves the read-only Virtuozzo Containers information.

Request specification:

Name Min/Max Type Description

get_vt_info 1..1 none

Returns:

Name Min/Max Type Description

vt_info 0..1 vt_infoType (p. 71)

Example:

Using the Virtuozzo implementation of the interface to retrieve Virtuozzo information.

Input

<target>vzaenvm</target>

<data>

<get_vt_info/>

</vzaenvm>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>vzaenvm</ns1:origin>

<ns1:data>

<ns2:vzaenvm>

<ns2:vt_info xsi:type="ns3:vt_infoType">

<ns3:version>4.0.0-112.swsoft</ns3:version>

<ns3:release>?</ns3:release>

<ns3:sve_eid>72145bf0-7562-43d4-b707-cc33d37e3f10</ns3:sve_eid>

<ns3:hwid>BD95.2511.D49F.422B.6247.EAFC.0423.E8C2</ns3:hwid>

</ns2:vt_info>

</ns2:vzaenvm>

</ns1:data>

</ns1:packet>

257

Base Types and Interfaces

get_vt_settings

Summary:

Retrieves virtualization technology specific settings.

Request specification:

Name Min/Max Type Description

get_vt_settings 1..1 none To get Virtuozzo Containers

specific settings, use

vzaenvm (p. 633), which is a

Virtuozzo implementation of

this interface.

To get virtual machines

specific settings, use vzpenvm

(p. 716), which is Parallels

Server implementation of this

interface.

Returns:

vt_settings or Error.

Name Min/Max Type Description

vt_settings 0..1 vt_settingsType

(p. 71)

The actual type returned is:

• For Virtuozzo

Containers:vt_settingsTy

pe (p. 631), the Virtuozzo

Containers implementation of

the generic

vt_settingsType.

• For virtual machines: VM-

specific vt_settingsType.

Example. Getting Virtuozzo Containers specific settings:

Input

<target>vzaenvm</target>

<data>

<get_vt_settings/>

</vzaenvm>

</data>

</packet>

Output

258

Base Types and Interfaces

<ns1:packet version="4.0.0">

<ns1:origin>vzaenvm</ns1:origin>

<ns1:data>

<ns2:vzaenvm>

<ns2:vt_settings xsi:type="ns3:vt_settingsType">

<ns3:lock_dir>L3Z6L2xvY2s=</ns3:lock_dir>

<ns3:template_dir>L3Z6L3RlbXBsYXRl</ns3:template_dir>

<ns3:parameter>

<ns3:id>actionlogdir</ns3:id>

<ns3:value>/vz/actionlog</ns3:value>

</ns3:parameter>

<ns3:parameter>

<ns3:id>backups_mode</ns3:id>

<ns3:value>standard</ns3:value>

</ns3:parameter>

<ns3:parameter>

<ns3:id>bandwidth</ns3:id>

<ns3:value>eth0:102400</ns3:value>

</ns3:parameter>

<ns3:parameter>

<ns3:id>def_ostemplate</ns3:id>

<ns3:value>fedora-core-4</ns3:value>

</ns3:parameter>

<ns3:parameter>

<ns3:id>disk_quota</ns3:id>

<ns3:value>yes</ns3:value>

</ns3:parameter>

<ns3:offline_service xsi:type="ns3:redirect_serviceType">

<ns3:id>vzpp-plesk</ns3:id>

<ns3:port>8443</ns3:port>

<ns3:dst>72145bf0-7562-43d4-b707-cc33d37e3f10</ns3:dst>

<ns3:default/>

</ns3:offline_service>

<ns3:qoses/>

</ns2:vt_settings>

</ns2:vzaenvm>

</ns1:data>

</ns1:packet>

259

Base Types and Interfaces

repair

Summary:

Creates a Virtuozzo Container as a temporary replacement for another Container that needs repair.

Request specification:

Name Min/Max Type Description

repair

{

eid 1..1 eid_type (p. 29) The Server ID of the original Container.

}

Returns:

OK/Error.

Description:

If you have a Virtuozzo Container that needs repair or maintenance, you may use this call to create

a new Container that will act as a temporary replacement for your original Container for the duration

of the repairs. The call will create an exact copy of the specified Container, start it, and will stop the

original Container, all with zero-downtime, so the user will be able to continue using the Container

without interruption. Once you are done repairing the original Container, use the stop_repair call

(p. 271) to revert to it.

Example:

<target>vzaenvm</target>

<data>

</repair>

</vzaenvm>

</data>

</packet>

260

Base Types and Interfaces

restart

Summary:

Restarts the specified virtual server.

A logged operation.

Request specification:

Name Min/Max Type Description

restart

{

eid 1..1 eid_type (p. 29) The Server ID.

}

Returns:

OK/Error.

Description:

The call stops and then automatically starts the specified virtual server. If the virtual server is not

currently running, the call skips the stopping part and simply starts the virtual server.

To restart a Virtuozzo Container, use the vzaenvm (p. 633) interface.

To restart a virtual machine, use the vzpenvm (p. 716) interface.

Example:

<target>vzaenvm</target>

<data>

</restart>

</vzaenvm>

</data>

</packet>

261

Base Types and Interfaces

resume

Summary:

Resumes a Virtuozzo Container that was previously suspended by the suspend call.

Request specification:

Name Min/Max Type Description

resume

{

eid 1..1 eid_type (p. 29)The Server ID of the Container to resume.

}

Returns:

OK/Error

Description:

For the Virtuozzo-specific implementation of this call see the vzaenvm interface (p. 633).

To resume a virtual machine, use the vzpenvm (p. 716) interface.

262

Base Types and Interfaces

set

Summary:

Sets the server configuration parameters.

Note: for virtual machines, only eid and config are passed to the set call, see Request

specification (specifying parameters manually) below. Other options are applicable to Virtuozzo

Containers only.

Request specification (specifying parameter and values manually):

Name Min/Max Type Description

set

{

eid 1..1 eid_type (p. 29) Server ID.

config 1..1 env_configType

(p. 37)

Server configuration.

• When modifying

Virtuozzo Container

configuration, use

venv_configType

(p. 627).

• When modifying a

virtual machine, use a

VM specific

venv_configType (p.

695).

force 0..1 none For Virtuozzo Containers only.

Ignore possible pool problems

and forcibly assign the IP

address.

default 0..1 For Virtuozzo Containers only.

Use this element to specify a

list of configuration parameters

for which you want to use the

default values.

{

parameter 1..[] string For Virtuozzo Containers only.

Parameter name.

}

263

Base Types and Interfaces

set_mode 0..1 string For Virtuozzo Containers only.

Specifies the operation mode:

restart -- restart the server

if it is required to do so for a

new parameter value to take

effect.

ignore -- ignore possible

errors while applying the new

values to the running server.

Note: Request specification below is applicable to Virtuozzo Containers only.

Request specification (using values from a sample configuration):

Name Min/Max Type Description

set

{

eid 1..1 eid_type (p. 29) Server ID.

apply_config 0..1

{

sample_conf 1..1 guid_type (p. 29) Sample configuration ID. To

obtain a list of the available

sample configurations, use

get_sample_conf (p. 233).

264

Base Types and Interfaces

parameter 0..[] string A list of the parameters to set.

See env_configType (p.

37) for the parameter names.

• When modifying

Virtuozzo Container

configuration, see

venv_configType

(p. 627).

• When modifying a

virtual machine, use a

VM specific

venv_configType (p.

695).

Note: The template

and network specific

parameters cannot be

modified using this

function. These

parameters are:

template,

os_template,

ve_root,

ve_private,

hostname,

ip_address.

category 0..[] string A list of parameter categories.

If you would like to set an

entire parameter category (or

multiple categories), specify it

here. For the list of categories

see Description below.

config_customized 0..1 boolean A flag indicating that the server

configuration has been

customized after the server

was created. Set this element

to true to save the flag in the

configuration file for future

reference.

}

set_mode 0..1 string Specifies the operation mode:

restart -- restart the server

if it is required to do so for the

new value to take effect.

ignore -- ignore possible

errors while applying the new

values to the running server.

}

Returns:

265

Base Types and Interfaces

Name Min/Max Type Description

env_config 0..1 env_configType

(p. 37)

The updated configuration

information.

Description:

Specifying parameter and values manually

Using the syntax #1 (above), you can pass a list of parameters (or a single parameter) with values

that you would like to modify. The configuration parameters are specified using the config

element. Although you can modify any configuration parameter that you like, you should only use

this approach to set the parameters that cannot possibly break a Container (e.g. hostname, DNS

servers, etc.). Speaking about Virtuozzo Container, when modifying QoS-related parameters,

always make sure that you know exactly what you are doing, or use the second approach

described below. For a sample XML request, see Example 1-3 below.

When setting QoS parameter values manually, there's one notable exception: the CPU limit QoS

counter. There are two counters that can be used to set the CPU limit for a Container: cpulimit

and cpulimit_mhz. The cpulimit counter is used to set the limit in percentage of the total

physical CPU power. The cpulimit_mhz counter is used to set the limit in Megahertz. When

obtaining the Container configuration, the QoS section will contain the counter, which is currently

set. When using a sample configuration, the cpulimit counter is used by default.

Using values from a sample configuration

This approach (syntax #2) also allows to specify the name of the parameters but their values will be

taken from a sample configuration. This is useful when setting (or re-setting) the QoS values

because a sample configuration contains the values that are fine-tuned for the type of application

that you intend to run inside the Container. Although you can modify individual parameters, it often

makes sense to modify an entire parameter category. This is accomplished by specifying the

category ID using the category element. The following table lists the categories that can be set

using this approach.

Category ID Description

general_conf General Container parameters.

qos Resource parameters - UBC, disk quota, CPU - all at once.

quota Disk quota parameters.

cpu CPU parameters.

For a sample XML request, see Example 4 below.

When using either approach, the new values are applied to the server immediately and are saved in

the configuration file, making the configuration changes permanent.

Example 1:

Assigning a new hostname, adding a search domain two DNS servers to a Virtuozzo Container.

266

Base Types and Interfaces

Input

<target>vzaenvm</target>

<data>

<set>

<hostname>myhost</hostname>

<search_domain>ts6.com</search_domain>

</config>

</set>

</vzaenvm>

</data>

</packet>

Example 2:

Modifying the IP address for venet0 network adapter, which is the default virtual adapter inside a

Virtuozzo Container. This modification works in such a way that the existing IP addresses are first

removed from the adapter's configuration and then the new addresses are added. To add an IP

address, first retrieve the existing addresses, then add the new address (or addresses) to the list,

and then include the entire list in the request. On Linux, when modifying the default venet0

adapter, the host_routed element must be present in the request. Configuring a non-default

virtual network adapter is similar with one exception: you cannot use the host_routed mode, so

you have to attach the adapter to an existing Virtuozzo virtual network by including the

network_id element containing the ID of the virtual network.

Input

<target>vzaenvm</target>

<data>

<set>

<net_device>

<id>venet0</id>

<ip_address>

</ip_address>

<ip_address>

</ip_address>

<ip_address>

</ip_address>

<host_routed/>

</net_device>

</config>

</set>

</vzaenvm>

</data>

</packet>

267

Base Types and Interfaces

Example 3:

This example is a Windows version of the previous example (modifying the IP address configuration

for the default venet0 network adapter). The difference here is that you may or may not have to

include the host_routed element depending on the following conditions:

• Include the element if you would like to set the adapter to use the host_routed mode.

• Don't include it if you want the adapter to use the bridged mode. When using the bridged

mode, you must also specify the virtual network ID to connect the adapter to by populating the

network_id field. See net_vethType (p. 622) for more information.

• Configuring any other (non-default) virtual network adapter is exactly the same as configuring

the default venet0 adapter.

In our example, we are switching the adapter to the bridged mode and attaching it to the

specified Virtuozzo virtual network. For more information on Virtuozzo virtual networks, see the

vzanetworkm interface (p. 661).

Input

<target>vzaenvm</target>

<data>

<set>

<net_device>

<id>venet0</id>

<ip_address>

</ip_address>

<ip_address>

</ip_address>

<ip_address>

</ip_address>

<network_id>dnpuZXQx</network_id>

</net_device>

</config>

</set>

</vzaenvm>

</data>

</packet>

Example 4:

Setting an entire set of QoS parameters using the values from the specified sample configuration.

Input

<target>vzaenvm</target>

<data>

268

Base Types and Interfaces

<set>

<apply_config>

<sample_conf>f8e96630-7fd8-4eee-93b2-3ad7b6b53916</sample_conf>

</apply_config>

</set>

</vzaenvm>

</data>

</packet>

set_vt_settings

Summary:

Sets virtualization technology specific settings.

Request specification:

Name Min/Max Type Description

set_vt_settings

{

vt_settings 1..1 vt_settingsType (p.

71)

Virtuozzo Containers settings.

Use vt_settingsType (p.

631), the Virtuozzo

implementation of the generic

vt_settingsType structure.

For virtual machines use VM-

specific vt_settingsType.

}

Returns:

OK/Error.

Example:

Modifying the default OS template for the Virtuozzo Containers installation.

<target>vzaenvm</target>

<data>

<set_vt_settings>

<vt_settings>

<id>def_ostemplate</id>

<value>redhat-as3-minimal</value>

</parameter>

</vt_settings>

</set_vt_settings>

</vzaenvm>

</data>

</packet>

269

Base Types and Interfaces

start

Summary:

Starts the specified virtual server.

A logged operation.

Request specification:

Name Min/Max Type Description

start

{

eid 1..1 eid_type (p. 29) Server ID.

}

Returns:

OK/Error.

Description:

The call starts the specified virtual server. If the virtual server cannot be started or is already

running, the call will return an error.

To start a Virtuozzo Container, use the vzaenvm (p. 633) interface.

To start a virtual machine, use the vzpenvm (p. 716) interface.

Examples:

<target>vzaenvm</target>

<data>

<start>

</start>

</vzaenvm>

</data>

</packet>

270

Base Types and Interfaces

stop

Summary:

Stops the specified virtual server.

A logged operation.

Request specification:

Name Min/Max Type Description

stop

{

eid 1..1 eid_type (p. 29) Server ID.

force 0..1 none Forcibly stop the virtual server.

}

Returns:

OK/Error.

Description:

The call stops the specified virtual server. If the virtual server cannot be stopped, an error code will

be returned. You can try to forcibly stop the virtual server by including the force element in the

request.

To stop a Virtuozzo Container, use the vzaenvm (p. 633) interface.

To stop a virtual machine, use the vzpenvm (p. 716) interface.

Example:

<target>vzaenvm</target>

<data>

<stop>

</stop>

</vzaenvm>

</data>

</packet>

271

Base Types and Interfaces

stop_repair

Summary:

Stops and destroys the temporary Container created by the repair call (p. 259).

Request specification:

Name Min/Max Type Description

stop_repair

{

eid 1..1 eid_type (p. 29)The Server ID of the original Container.

}

Returns:

OK/Error.

Description:

This call will stop and destroy the temporary Container created by the repair call (p. 259). It will

then bring the original Container back up. Execute this call after you are done repairing the original

Container and want to revert to it.

Example:

<target>vzaenvm</target>

<data>

<stop_repair>

</stop_repair>

</vzaenvm>

</data>

</packet>

272

Base Types and Interfaces

suspend

Summary:

Suspends a virtual server.

Request specification:

Name Min/Max Type Description

suspend

{

eid 1..1 eid_type (p. 29) Server ID.

}

Returns:

OK/Error

Description:

Use this call to temporarily suspend a virtual server without shutting it down. The status of a virtual

server becomes "suspended". To resume a virtual server, use the resume call.

For the Virtuozzo-specific implementation of this call see the vzaenvm interface (p. 633).

To suspend a virtual machine, use the vzpenvm (p. 716) interface.

273

Base Types and Interfaces

get_native_config

Summary:

Converts a Container configuration data from the Agent format to the Virtuozzo Containers native

format.

Request specification:

Name Min/Max Type Description

get_native_config

{

virtual_config 1..1 venv_configType (p.

69)

Container configuration data

in the Agent format. To

obtain the Container

configuration from Agent,

use the get_info call (p.

247).

}

Returns:

Name Min/Max Type Description

native_config 0..[] native_configType

(p. 51)

Virtual configuration data in

the Virtuozzo Containers

native format. The

appropriate subtype of

native_configType (p.

51) will be used in the result.

Description:

Parallels Agent uses its own data structures for the Virtuozzo Containers configuration data (the

subtypes of venv_configType (p. 69)). You use this data structures when creating, examine, or

modifying a Virtuozzo Container through Parallels Agent API. The Virtuozzo Containers software

stores the same configuration data differently. It uses the bash style configuration data formatting,

which is a set of values in the VARNAME="value-string" form. The get_native_config call

allows to convert the Agent version of the configuration data to the native Virtuozzo Containers

formatting.

Example:

In the following example, we pass the Agent version of the Container configuration data to the

get_native_config call.

Input

<packet xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/protocol"

xmlns:ns2="http://www.swsoft.com/webservices/vza/4.0.0/vzatypes"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<target>vzaenvm</target>

<data>

274

Base Types and Interfaces

<get_native_config>

<virtual_config xsi:type="ns2:venv_configType">

<on_boot>0</on_boot>

<qos>

<id>cpuunits</id>

</qos>

<qos>

<id>dgramrcvbuf</id>

</qos>

<qos>

<id>diskinodes</id>

</qos>

<qos>

<id>diskspace</id>

</qos>

<qos>

<id>kmemsize</id>

</qos>

<!-- The rest of the configuration parameters

are omitted for brevity -->

</virtual_config>

</get_native_config>

</vzaenvm>

</data>

</packet>

Output

The Virtuozzo native configuration data is received as a block of base64-encoded data. After you

decode it, the result will look similar to the following example:

VERSION="2"

ONBOOT="no"

AVNUMPROC="40:40"

NUMPROC="65:65"

NUMTCPSOCK="80:80"

NUMOTHERSOCK="80:80"

VMGUARPAGES="6144:2147483647"

KMEMSIZE="2752512:2936012"

TCPSNDBUF="319488:524288"

TCPRCVBUF="319488:524288"

OTHERSOCKBUF="132096:336896"

DGRAMRCVBUF="132096:132096"

OOMGUARPAGES="6144:2147483647"

LOCKEDPAGES="32:32"

SHMPAGES="8192:8192"

PRIVVMPAGES="22528:24576"

NUMFILE="2048:2048"

NUMFLOCK="100:110"

275

Base Types and Interfaces

NUMPTY="16:16"

NUMSIGINFO="256:256"

DCACHESIZE="1048576:1097728"

PHYSPAGES="0:2147483647"

NUMIPTENT="128:128"

DISKSPACE="1048576:1153434"

DISKINODES="200000:220000"

QUOTATIME="0"

CPUUNITS="1000"

OFFLINE_MANAGEMENT="yes"

ARCH="x86"

PLATFORM="linux"

SLMMEMORYLIMIT="33521664:33521664"

get_virtual_config

Summary:

Converts virtual server configuration data from a virtualization technology native format to the Agent

format.

Request specification:

Name Min/Max Type Description

get_virtual_config

{

native_config 1..1 native_configType

(p. 51)

Virtuozzo Container

configuration data in the

Virtuozzo native format.

}

Returns:

Name Min/Max Type Description

virtual_config 0..[] venv_configType (p.

69)

Virtuozzo Container

configuration data in the

Agent format.

Description:

This call is an opposite of the get_native_config call (p. 273). It converts the Virtuozzo

Container configuration data from the Virtuozzo native format to the Agent format.

event_log

Purpose:

Provides calls that allow to access event logs.

276

Base Types and Interfaces

Calls

Call Description

get_events (p. 277) Retrieves information from the event log.

277

Base Types and Interfaces

get_events

Summary:

Retrieves information from the event log.

Request specification:

Name Min/Max Type Description

event_log

{

[ 0..1 Denotes a choice between the

eid and the subject elements.

eid 1..1 eid_type (p. 29) The ID of the server that

generated the event. This is

usually the Hardware Node

hosting Virtuozzo Containers.

When the event triggers in one of

the Containers, it is actually

generated by the Hardware

Node and its ID is recorded in

the log.

subject 1..1 eid_type (p. 29) The ID of the affected server.

This is usually the Container that

triggered the event. For example,

the Container the status of which

has changed. The ID of the

affected Container is also

recorded in the log together with

the server (host) that generated

the event.

]

start_time 0..1 datetime_type Start time of the log.

end_time 0..1 datetime_type End time of the log.

records 0..1 int Number of records to retrieve

from the end of the log.

sid 0..1 sidType (p. 30) Report only the events with the

SID specified in this element (the

user SID identifies the active user

at the time the event was

generated).

source 0..1 string Report only the events with the

source specified here (the source

is the name of the plug-in or an

Agent operator that generated

the event).

278

Base Types and Interfaces

category 0..1 string Report only the events

associated with the category

specified in this element. See the

Types section (p. 551) for the

available event types and their

corresponding categories.

data 0..1 none If this element is present, the

event data will also be retrieved

(the data element of the

returned event structure will be

populated with the event type-

specific data).

}

Returns:

Name Min/Max Type Description

event 0..[] eventType (p. 41) Event information.

Description

Every time something changes in a server that may affect its operations (e.g. status or configuration

change), a system event of a corresponding type is triggered and the event information is recorded

into a log. The get_events call allows to retrieve event data from the log. You may specify any of

the available parameters to narrow the search down and to retrieve only the information that you

require. For more information on system events, see the Events chapter (p. 551).

Example:

Getting the latest 2 records from the event log database.

Input

<target>event_log</target>

<data>

<event_log>

<get_events>

<data/>

</get_events>

</event_log>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>event_log</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:data>

<ns2:event_log>

<ns2:event xsi:type="ns3:eventType">

<ns3:eid>89e27960-97b8-461f-902f-557b4b16784b</ns3:eid>

<ns3:time>2007-01-16T20:11:57+0000</ns3:time>

<ns3:source>VZAConfPeriodic</ns3:source>

279

Base Types and Interfaces

<ns3:category>env_config</ns3:category>

<ns3:sid>S-1-1000-3</ns3:sid>

<ns3:count>1</ns3:count>

<ns3:id>4b9ba735-6084-774c-9632-3f92bd905066</ns3:id>

<ns3:info xsi:type="ns3:infoType">

<ns3:message>RW52aXJvbm1lbnQgJWVudiUgY29uZmlnIGNoYW5nZWQ=</ns3:message>

<ns3:name></ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>JXRpdGxlJQ==</ns3:message>

<ns3:name>env</ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>NzIxNDViZjAtNzU2Mi00M2Q0LWI3MDctY2MzM2QzN2UzZjEw</ns3:message>

<ns3:name>eid</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>bG9jYWxob3N0</ns3:message>

<ns3:name>title</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>dmlydHVvenpv</ns3:message>

<ns3:name>type</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>JXRpdGxlJQ==</ns3:message>

<ns3:name>source_env</ns3:name>

<ns3:translate/>

<ns3:parameter>

<ns3:message>ODllMjc5NjAtOTdiOC00NjFmLTkwMmYtNTU3YjRiMTY3ODRi</ns3:message>

<ns3:name>eid</ns3:name>

<ns3:translate/>

</ns3:parameter>

<ns3:parameter>

<ns3:message>ZGhjcDAtMTk0LnN3LnJ1</ns3:message>

<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:info>

</ns2:event>

</ns2:event_log>

</ns1:data>

</ns1:packet>

280

Base Types and Interfaces

filer

Purpose:

The file management interface.

Types

credType

Summary:

User and group information.

Type specification:

Name Min/Max Type Description

{

[

user 0..1 string User name.

uid 0..1 long User ID.

]

[

group 0..[] string Group name.

gid 0..[] long Group ID.

]

umask 0..1 int Operation umask.

}

Description:

The <umask> parameter is used to restrict file system entries permission mode using the following

rule:

[permission] AND ~[umask] => [result permission]

umask must specified using a decimal value, not octal.

281

Base Types and Interfaces

navigateType

Summary:

Filesystem navigation.

Type specification:

Name Min/Max Type Description

path 1..[] base64Binary Path on filesystem. If path is

empty then look up

partitions.

cwd 0..1 base64Binary Current working directory.

The default value is:

"/"

"C:\"

cred 0..1 credType (p. Credentials with which the

requested operation will be

performed.

280)

navigate_wildType

Summary:

Filesystem navigation with wildcards.

Type specification:

Extends navigateType (p. 281)

Adds the following elements:

Name Min/Max Type Description

wildcard 0..1 none If present, indicates that

the value of the path

element (derived from the

supertype

navigateType) contains

wildcards.

282

Base Types and Interfaces

fileType

Summary:

Filesystem element.

Type specification:

Name Min/Max Type Description

file 0..[] fileType (p. If filesystem element is a directory,

this field will contain the direct

children of the directory (files and

directories).

282)

name 1..1 base64Binary The filesystem element name.

type 0..1 int Element type:

1 - FIFO

2 - Character device

4 - Directory

6 - Block device

8 - Regular File

10 - Symbolic link

12 - Socket

16 - Floppy disk

17 - Hard disk

18 - Remote drive

19 - CD ROM

20 - RAM disk

21 - Mounted image file

22 - VZFS 'magic' file

mode 0..1 mode_type (p. The element access mode in

decimal form.

283)

user 0..1 string User name.

group 0..1 string Group name.

uid 0..1 int User ID.

gid 0..1 int Group ID.

size 0..1 long Element size.

date 0..1 datetime_type The date when the file element

was last changed.

283

Base Types and Interfaces

links 0..1 int Number of hard links.

link_name 0..1 string Where link points to.

offset 0..[] long Offset in the file where the block

of data was found by the search

call (p. 305).

body 0..1 base64Binary A buffer containing the file data.

content_type 0..1 string File contents description (in MIME

format).

mode_type

Summary:

File element access mode.

Type specification:

Simple type.

union: int, string

Calls

Call Description

list (p. 284) List directory contents.

remove (p. 289) Removes filesystem entries.

copy (p. 290) Copies files.

mkdir (p. 292) Creates new directories.

move (p. 293) Moves or renames files.

upload (p. 294) Upload files into the specified server.

download (p. 296) Downloads files from the specified server.

chmod (p. 298) Change access permissions for all elements in the list.

chown (p. 299) Change file owner and group.

link (p. 300) Create new link element.

stat (p. 301) Displays file or filesystem status.

readlink (p. 303) Display value of a symbolic link.

search (p. 305) Search the files for a block of data.

284

Base Types and Interfaces

list

Summary:

Lists information about files, directories and other filesystem elements. The command is also

capable of searching the backup archives and retrieve the information about the archived files and

directories.

Request specification:

Name Min/Max Type Description

list navigateType (p. 281)

{

info 0..1 The fields for which to

provide the output. If an

element from this sequence

is included in the call, the

information that it refers to

will be included in the result

set.

{

user 0..1 User name.

group 0..1 Group name.

uid 0..1 User ID.

gid 0..1 Group ID.

mode 0..1 Element mode.

size 0..1 Element size.

date 0..1 Date of last change.

links 0..1 Number of hard links.

link_name 0..1 Where the link points to.

content_type 0..1 File contents description.

}

usage 0..1 If present, the size returned

for an element is a gross

size on a disk, so for

directories it is calculated by

traversing their children.

{

single_fs 0..1 If included, the operation will

not go across different

partitions while traversing.

}

285

Base Types and Interfaces

follow_links 0..1 If present, the information

returned for links will be

about their references

instead of themselves.

filter 0..[] File filtering criteria. Inside a

single filter, the AND rule

applies (all must be

satisfied). Multiple filters

work as the OR rule (at least

one should be satisfied).

{

[ Denotes a choice between

user, uid, or the

start_uid/end_uid

sequence.

user 1..1 string User name (supports

wildcards).

uid 1..1 int User ID.

{ This sequence is not a child

of the uid element but is a

separate entry in the choice

group.

start_uid 0..1 int First UID of the range.

end_uid 0..1 int Last UID of the range.

}

]

[ Denotes a choice between

the gid, group, or the

start_uid/end_uid

sequence.

gid 1..1 int Group ID.

group 1..1 string Group name (supports

wildcards).

{ The sequence is not a child

of the group element but a

separate choice.

start_uid 0..1 int First UID of the range.

end_uid 0..1 int Last UID of the range.

}

]

start_date 0..1 date Time of the last change to

start with.

end_date 0..1 date Time of the last change to

end with.

min_size 0..1 long Minimum size.

286

Base Types and Interfaces

max_size 0..1 long Maximum size.

type 0..1 int The filesystem element type.

See fileType/type (p.

282) for the available types.

name 0..1 base64Binary The element name

(supports wildcards).

block 0..1 base64Binary List files containing this text

(this could be a time

consuming operation).

}

recursively 0..1 none To list the entire tree

including subdirectories

include this element in the

request.

}

Returns:

Name Min/Max Type Description

file 0..[] fileType (p. 280) The file information

structure.

Description:

The path can be specified using wildcard extensions. Please note that if you are using a wildcard in

any of the path elements, you must include the wildcard option. If an absolute path is given, the

cwd parameter is ignored.

To search the backup archives, the path option must contain the URI specifying the location of the

archived file or directory. The format of the URI is as follows:

backup://BACKUP_ID/path

where backup indicates that we want to search the backup archive; BACKUP_ID is a string

containing the backup ID; path is the absolute path to the original location of a file or directory. For

example:

<path>backup://2005-09-04T203847+0400@tc9/C:/Windows/info.txt</path>

If the usage option is included, the size returned for an element is the actual size on the disk (the

size of the elements in blocks multiplied by the filesystem block size ). For directories it is calculated

by adding up the sizes of all the descendents of a directory.

You can customize the result set by specifying only the file properties that you want to see. This

can be done by including the appropriate parameters in the info option.

The values of the start_date and the end_date elements are specified as a time in seconds

starting from the year 1970. If start_date is absent, filter everything from 0 to the value specified

in the end_date element. If end_date is absent, filter everything from start_date up to the

current date.

287

Base Types and Interfaces

Note: By default, the call will get the list of files from the Hardware Node. To retrieve the list from a

Virtuozzo Container, use the remote message targeting mechanism by including the dst element in the

message header containing the target Server ID. This rule applies to most of the file management calls.

Example:

Retrieving a list of files from the "/" directory from the specified server.

Input

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<list>

<info>

<user/>

<name/>

<uid/>

<gid/>

</info>

</list>

</filer>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>filer</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:data>

<ns2:filer>

<ns2:file>

<ns2:name>aG9tZQ==</ns2:name>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

</ns2:file>

<ns2:file>

<ns2:name>bGli</ns2:name>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

</ns2:file>

<ns2:file>

<ns2:name>cHJvYw==</ns2:name>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

288

Base Types and Interfaces

</ns2:file>

<ns2:file>

<ns2:name>Li4=</ns2:name>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

</ns2:file>

<ns2:file>

<ns2:name>bWlzYw==</ns2:name>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

</ns2:file>

<ns2:file>

</ns2:filer>

</ns1:data>

</ns1:packet>

289

Base Types and Interfaces

remove

Summary:

Removes filesystem entries.

Request specification:

Name Min/Max Type Description

remove 1..1 navigateType (p. 281)

{

recursively 0..1 none Include this element in the

request if you are removing a

directory.

force 0..1 none Ignore errors if a file or a

directory does not exist.

}

Returns:

OK/Error

Example:

Removing the specified directory from the specified server. When performing the operation on a

Virtuozzo Container, specify it's Server ID using the remote message targeting mechanism (the dst

element in the message header).

Input

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<path>dGVzdGRpcg==</path>

</remove>

</filer>

</data>

</packet>

290

Base Types and Interfaces

copy

Summary:

Copies files and directories.

Request specification:

Name Min/Max Type Description

copy navigateType (p. 281) The parent

navigate_wildType

type contains parameters

allowing to specify source

file information.

{

dst_path 1..1 base64Binary Destination path including

the directory name and the

file name.

recursively 0..1 A flag indicating to process

directories recursively.

force 0..1 A flag indicating to

overwrite the file if it exists

in the target directory.

{ 0..1 Remote copying.

The sequence is not a child

of the force element but

a separate sequence.

dst 1..1 connection_infoType

(p. 34)

The destination Container

connection information.

The Container must be

located on the same host.

mode 0..1 mode_type (p. 283) New access mode (in

decimal form) to assign to

copied files on the target

machine.

}

Returns:

OK/Error

Description:

You can copy files between directories on the same server. You can also copy files between

Virtuozzo Containers on the same host. To copy a file from one Container to another, include the

dst element specifying the destination Server ID and, if necessary, the mode element specifying

the new file access mode.

291

Base Types and Interfaces

Example:

Copies a file mylog.log from the /root directory to the /root/mylogs directory using

root/root credentials.

<target>filer</target>

<data>

<filer>

<copy>

<path>cm9vdC9teWxvZy5sb2c=</path>

<cred>

</cred>

<dst_path>L3Jvb3QvbXlsb2dzL215bG9nLmxvZw==</dst_path>

</copy>

</filer>

</data>

</packet>

292

Base Types and Interfaces

mkdir

Summary:

Creates a new directory.

Request specification:

Name Min/Max Type Description

mkdir navigateType (p.

281)

{

mode 0..1 mode_type (p. 283) Access mode in decimal form.

recursively 0..1 If any part of the path does not

exist, create it.

}

Returns:

OK/Error

Example:

<target>filer</target>

<data>

<filer>

<mkdir>

<path>cm9vdC9teWxvZ3M=</path>

<cred>

</cred>

</mkdir>

</filer>

</data>

</packet>

293

Base Types and Interfaces

move

Summary:

Moves or renames files.

Request specification:

Name Min/Max Type Description

move navigateType (p.

281)

{

dst_path 1..1 base64Binary The destination path.

force 0..1 Overwrite if destination exists.

}

Returns:

OK/Error

Description:

To rename a file or a directory, specify the new name in the dst_path. To copy files to a different

directory, specify the full directory path.

294

Base Types and Interfaces

upload

Summary:

Uploads a file to a server.

Request specification:

Name Min/Max Type Description

upload

{

cwd 0..1 base64Binary Current working directory. The

default value is:

"/"

"C:\"

cred 0..1 credType (p. Credentials with which the

requested operation will be

performed.

280)

file 1..[] Files to upload. One packet may

contain multiple file elements

so you can transfer more than

one block of data in one call.

{

path 1..1 base64Binary Target path and file name.

size 1..1 long The size of the data block being

transferred in bytes.

offset 0..1 long Offset in the target file in bytes.

If not supplied, then the data will

be inserted at the beginning of

the file.

If set to -1, then the data will be

appended at the end of the file.

The force element (below)

must be always included when

working with existing files.

body 0..1 base64Binary The block of data to be

transferred.

}

mode 0..1 mode_type (p. 283) Access permissions for the

new file in decimal form. The

mode is affected by umask.

295

Base Types and Interfaces

force 0..1 none Include this element if the

destination file already exists and

you want to overwrite it or add

more data to it using the

offset option.

If the element is absent and the

file already exists on the

destination machine, the call will

fail.

}

Returns:

OK/Error

Example:

Input

Uploading the first block of data. The file doesn't exist on the target machine yet, so it will be

created.

<target>filer</target>

<data>

<filer>

<file>

<path>dGVzdDAxLnR4dA==</path>

<body>RGF0YSBibG9jayAx</body>

</file>

</upload>

</filer>

</data>

</packet>

Uploading the second data block. To append the data to the end of the file, the offset and the

force options must be used.

<target>filer</target>

<data>

<filer>

<file>

<path>dGVzdDAxLnR4dA==</path>

<body>U2Vjb25kIGRhdGEgYmxvY2s=</body>

</file>

</upload>

</filer>

</data>

</packet>

296

Base Types and Interfaces

download

Summary:

Downloads a file from a server. The call is also capable of extracting files from a backup archive.

Request specification:

Name Min/Max Type Description

download

{

cwd 0..1 base64Binary Current working directory. The

default value is:

"/"

"C:\"

cred 0..1 credType (p. Credentials with which the

requested operation will be

performed.

280)

file 1..[] Files to download.

{

path 1..1 base64Binary The source path and file name.

size 0..1 long Size of the data block to be

transferred.

offset 0..1 long Offset in the source file.

}

Returns:

Name Min/Max Type Description

file

{

body 0..1 base64Binary The file data.

}

Description:

The call reads the data from the specified source file and transfers the data to the client in blocks of

the specified size. It does not automatically create a file on the target machine, so it is your

responsibility to process the received data.

To extract a file from a backup archive, the <cwd> element must contain a URI specifying the

backup ID. The format of the URI is as follows:

backup://backup_id

297

Base Types and Interfaces

where backup_id is the ID of the backup archive, and the <path> element must contain an

absolute path to the original location of a file or directory. For example:

<cwd>backup://a28d77df-a4e1-4d98-a01c-dc85b6d19f7b/20060718064512</cwd>

<path>C:/Windows/info.txt</path>

Example:

Downloading a file from a server in two sequential transfers.

Input

Reading the first block of data.

<target>filer</target>

<data>

<filer>

<file>

<path>dGVzdDAxLnR4dA==</path>

</file>

</download>

</filer>

</data>

</packet>

Output

The body element contains the data.

<ns1:packet version="4.0.0">

<ns1:origin>filer</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:filer>

<ns2:file>

<ns2:body>RGF0YSBibG9jayAx</ns2:body>

</ns2:file>

</ns2:filer>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

Input

Reading the second block of data. The offset element marks the beginning of the block in the

source file.

<target>filer</target>

<data>

<filer>

298

Base Types and Interfaces

<file>

<path>dGVzdDAxLnR4dA==</path>

</file>

</download>

</filer>

</data>

</packet>

Output

The body element contains the data.

<ns1:packet version="4.0.0">

<ns1:origin>filer</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:data>

<ns2:filer>

<ns2:file>

<ns2:body>U2Vjb25kIGRhdGEgYmxvY2s=</ns2:body>

</ns2:file>

</ns2:filer>

</ns1:data>

</ns1:packet>

chmod

Summary:

Change access permissions for filesystem elements.

Request specification:

Name Min/Max Type Description

chmod navigateType (p.

281)

{

mode 1..1 mode_type (p. 283) New access mode in decimal

form.

[ 0..1 Turn on/off bits supplied in

mode. Analogues to +/- in

chmod command.

on 1..1 none

off 1..1 none

]

recursively 0..1 none Apply changes recursively.

}

Returns:

OK/Error

299

Base Types and Interfaces

chown

Summary:

Changes the user and/or group ownership of a specified file.

Request specification:

Name Min/Max Type Description

chown navigateType (p.

281)

{

recursively 0..1 Process elements recursively.

owner 1..1 credType (p. 280) Owner name ( as it exists in

/etc/passwd).

follow_links 0..1 Operates as lchown.

}

Returns:

OK/Error

Description:

New owner/group information is supplied as a set of user or uid and/or group or gid within

the owner structure.

The user element can be used to specify a user or a group.

Example:

Changing the owner of /test to apache/apache.

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<chown>

<path>dGVzdA==</path>

<cred>

<user>apache</user>

<group>apache</group>

</cred>

</chown>

</filer>

</data>

</packet>

300

Base Types and Interfaces

link

Summary:

Creates a link to the specified filesystem entry.

Request specification:

Name Min/Max Type Description

link navigateType (p.

281)

{

name 1..1 base64Binary Link name.

symbolic 0..1 Creates symbolic link if present,

otherwise creates hard link.

force 0..1 Ignores errors if present.

}

Returns:

OK/Error

Example:

Creating a symbolic link to /test.

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<link>

<path>dGVzdA==</path>

<name>dGVzdC1kaXI=</name>

</link>

</filer>

</data>

</packet>

301

Base Types and Interfaces

stat

Summary:

Returns filesystem element status information. The call is also capable of searching the backup

archives and display the status information for the archived files and directories.

Request specification:

Name Min/Max Type Description

stat navigateType (p.

281)

{

usage 0..1 If present, the size returned for

an element is a gross size on a

disk, so for directories it is

calculated by traversing their

children.

{

single_fs 0..1 Do not go across different

partitions, while traversing.

}

follow_links 0..1 If present, the information

returned for links will be about

their references, instead of

themselves.

info 0..1 The list of properties to retrieve

the information for. Simply

include any of the following

elements in the request if you

would like the corresponding

information to be included in

the output.

{

user 0..1 none User name.

group 0..1 none Group name.

uid 0..1 none User ID.

gid 0..1 none Group ID.

mode 0..1 none Mode.

size 0..1 none Size.

date 0..1 none Date.

links 0..1 none Hard link information.

link_name 0..1 none Link name.

content_type 0..1 none File element content type.

}

302

Base Types and Interfaces

Returns:

Name Min/Max Type Description

file 0..[] fileType (p. 282) Status information.

Example:

Get the status of the "/" directory.

Input

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<stat>

</stat>

</filer>

</data>

</packet>

Output

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>filer</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:data>

<ns2:filer>

<ns2:file>

<ns2:name>Lw==</ns2:name>

<ns2:type>4</ns2:type>

<ns2:mode>493</ns2:mode>

<ns2:user>root</ns2:user>

<ns2:group>root</ns2:group>

<ns2:uid>0</ns2:uid>

<ns2:gid>0</ns2:gid>

<ns2:links>27</ns2:links>

<ns2:size>0</ns2:size>

<ns2:date>2007-01-24T01:50:25+0000</ns2:date>

</ns2:file>

</ns2:filer>

</ns1:data>

</ns1:packet>

303

Base Types and Interfaces

readlink

Summary:

Returns the contents of a symbolic link.

Request specification:

Name Min/Max Type Description

readlink credType (p.

280)

{

path 1..[] base64Binary Path on filesystem.

cwd 0..1 base64Binary Current working directory. If

absent, it is set to "/" by default.

}

Returns:

Name Min/Max Type Description

file 0..[] fileType (p. File information structure.

282)

If the path is a symbolic link,

returns its contents (what it links

to) in file/name. Returns an

error otherwise. On systems that

do not support symbolic links,

the operation will always return

an error.

Description:

If the path is a symbolic link, returns its contents (what it links to) in file/name Returns an error

otherwise. On systems that do not support symbolic links, the operation will always return an error.

Example:

Input

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<path>L2hvbWUvZWR2dC9kLWVkdnQ=</path>

</readlink>

</filer>

</data>

</packet>

Output

304

Base Types and Interfaces

<origin>filer</origin>

<target>vzclient84</target>

<data>

<filer>

<file>

<name>L2hvbWUvZWR2dA==</name>

</file>

</filer>

</data>

</packet>

305

Base Types and Interfaces

search

Summary:

Finds the first occurrence of a data block in files.

Request specification:

Name Min/Max Type Description

search navigateType (p. 281)

{

offset 0..1 long Starting search offset. Positive

offset means offset from the

beginning of a file, and

negative from the end of a file.

block 1..1 base64Binary Data block to find in a file.

backward 0..1 Search backwards.

}

Returns:

Name Min/Max Type Description

file 0..[]

{

name fileType (p. 282) The name of the file containing

the specified block of data.

offset 0..[] long Offset at which the block is

located in the file.

}

Example:

Search for a string "aaa" in the /tmp.txt file on the specified Virtuozzo Container.

Input

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>filer</target>

<data>

<filer>

<block>YWFhYQ==</block>

</search>

</filer>

</data>

306

Base Types and Interfaces

</packet>

Output

<origin>filer</origin>

<target>vzclient123</target>

<data>

<filer>

<file>

</file>

</filer>

</data>

</packet>

firewallm

This interface is available on Linux-based systems only.

Purpose:

The firewall management interface.

Types

chainType

Summary:

An enumeration defining the firewall chain types.

Type specification:

Enumeration, string.

Enumerator Description

INPUT An input chain. Called for inbound packets

only.

OUTPUT An output chain. Called for outbound

packets only.

FORWARD Forward chain. Called for packets that pass

through the system.

307

Base Types and Interfaces

policyType

Summary:

An enumeration defining the firewall control policy types.

Type specification:

Enumeration, string.

Enumerator Description

ACCEPT Accept a packet.

DROP Drop a packet.

REJECT Reject a packet.

port_rangeType

Summary:

This type is used to specify a single TCP port or a range of TCP ports.

Type specification:

Name Min/Max Type Description

first_port 1..1 int The first port number in the

range. If specifying a single

port, include it here and

omit the last_port

element (below).

last_port 0..1 int The last port number in the

range.

308

Base Types and Interfaces

ruleType

Summary:

Contains the firewall rule settings.

Type specification:

Name Min/Max Type Description

name 1..1 string Name of the service.

protocol 1..1 transport_type (p.

30)

Protocol type (tcp or udp).

chain 0..1 chainType (p. 306) The firewall chain to which this

rule is applied.

policy 0..1 policyType (p. 307) Firewall security policy.

allowed 0..1 boolean Indicates whether the protocol

is enabled or disabled when

the firewall is switched on.

true -- the protocol will be

enabled.

false -- the protocol will be

disabled.

src_addr 0..1 net_addressType Source address. The internal

address of the packets (e.g.:

IPv4 or IPv6 address, the

name of a network interface,

etc.)

dst_addr 0..1 net_addressType Destination address. The

address where the packets

are sent.

src_ports 0..1 port_rangeType (p.

307)

Source port range.

dst_ports 0..1 port_rangeType (p.

307)

Destination port range.

input_iface 0..1 string Input interface.

output_iface 0..1 string Output interface.

309

Base Types and Interfaces

Calls

Call Description

get (p. 310) Lists existing firewall rules.

set (p. 311) Adds or modifies a rule.

delete (p. 312) Deletes a rule.

is_enabled (p. 313) Checks if the firewall is enabled.

enable (p. 314) Enables the firewall.

disable (p. 315) Disables the firewall.

310

Base Types and Interfaces

get

Summary:

Lists existing firewall rules.

Request specification:

Name Min/Max Type Description

get 0..1

Returns:

Name Min/Max Type Description

rule 1..[] ruleType (p. Firewall rule structure.

308)

Example:

Listing firewall rules for the specified Virtuozzo Container.

Input

<dst>

Host9bafbeb7-85f7-499e-a210-40e00850a5f3</host>

</dst>

<target>firewallm</target>

<data>

<get/>

</firewallm>

</data>

</packet>

Output

<origin>firewallm</origin>

<target>vzclient30</target>

<data>

<rule>

<name>REJECT_MAIL</name>

<chain>INPUT</chain>

<policy>REJECT</policy>

<src_addr>

Host192.168.1.10</host>

</src_addr>

<src_ports>

<first_port>25</first_port>

</src_ports>

</rule>

</firewallm>

</data>

</packet>

311

Base Types and Interfaces

set

Summary:

Adds a rule to the firewall, or bans/permits an existing rule.

Request specification:

Name Min/Max Type Description

set

{

rule 0..[] ruleType (p. Firewall rule to set.

308)

}

Returns:

OK/Error

Example:

Setting a new rule for the specified Virtuozzo Container.

<dst>

Host9bafbeb7-85f7-499e-a210-40e00850a5f3</host>

</dst>

<target>firewallm</target>

<data>

<set>

<rule>

<name>REJECT_MAIL</name>

<chain>INPUT</chain>

<policy>REJECT</policy>

<src_addr>

Host192.168.2.10</host>

</src_addr>

<src_ports>

<first_port>25</first_port>

</src_ports>

</rule>

</set>

</firewallm>

</data>

</packet>

312

Base Types and Interfaces

delete

Summary:

Deletes a firewall rule.

Request specification:

Name Min/Max Type Description

delete

{

rule 0..[] ruleType (p. Firewall rule to delete. If none

specified, deletes all existing

rules.

308)

}

Returns:

OK/Error

Example:

Deleting a firewall rule from the specified Container. All of the parameters shown in the example

must be specified.

Input

<dst>

Host9bafbeb7-85f7-499e-a210-40e00850a5f3</host>

</dst>

<target>firewallm</target>

<data>

<rule>

<name>REJECT_MAIL1</name>

<chain>INPUT</chain>

<policy>REJECT</policy>

<src_addr>

Host192.168.2.10</host>

</src_addr>

<src_ports>

<first_port>25</first_port>

</src_ports>

</rule>

</delete>

</firewallm>

</data>

</packet>

313

Base Types and Interfaces

is_enabled

Summary:

Checks if the firewall is enabled.

Request specification:

Name Min/Max Type Description

is_enabled 0..1

Returns:

Name Min/Max Type Description

status 0..1 boolean true -- the firewall is enabled.

false -- the firewall is disabled.

Example:

Input

<dst>

Host9bafbeb7-85f7-499e-a210-40e00850a5f3</host>

</dst>

<target>firewallm</target>

<data>

<is_enabled/>

</firewallm>

</data>

</packet>

Output:

<ns1:packet priority="0" version="4.0.0">

<ns1:origin>firewallm</ns1:origin>

<ns1:target>vzclient3</ns1:target>

<ns1:data>

<ns2:firewallm>

<ns2:status>0</ns2:status>

</ns2:firewallm>

</ns1:data>

</ns1:packet>

314

Base Types and Interfaces

enable

Summary:

Enables a firewall.

Request specification:

Name Min/Max Type Description

enable 0..1

Returns:

OK/Error

Example:

Enabling a firewall in the specified Container.

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>firewallm</target>

<data>

</firewallm>

</data>

</packet>

315

Base Types and Interfaces

disable

Summary:

Disables a firewall.

Request specification:

Name Min/Max Type Description

disable 0..1

Returns:

OK/Error

Example:

Disabling a firewall in the specified Container.

<dst>

Host24b9acf5-8ca5-49c9-b7b1-4c93fe048389</host>

</dst>

<target>firewallm</target>

<data>

</firewallm>

</data>

</packet>

licensem

Purpose:

Virtuozzo Containers license management interface.

316

Base Types and Interfaces

Types

parameterType

Summary:

Contains information about a license parameter.

Type specification:

Name Min/Max Type Description

name 1..1 string Parameter name.

value 1..1 base64Binary Parameter value.

used 0..1 base64Binary Number of licensable units already in

use. For example, the number of

Virtuozzo Containers in use. By

subtracting used from value you'll

get the number of Containers that

you still can create under the given

license. The value is only provided

for some of the license parameters.

licenseType

Summary:

Contains a list of license parameters.

Type specification:

Name Min/Max Type Description

parameter 0..[] parameterType (p. 316) A list of license parameters.

licensesType

Summary:

License information.

Type specification:

Name Min/Max Type Description

body 1..1 string License body.

license 1..[] licenseType (p. 316) License information.

317

Base Types and Interfaces

license_eventType

Summary:

Event-specific data returned in the event of license expiration. See subscribe (p. 612) for more

information on events and subscriptions.

Type specification:

Name Min/Max Type Description

license 1..[]

{

serial 1..1 base64Binary License serial number.

status 0..1 base64Binary License status. If absent then

the license was deleted.

}

Calls

Call Description

list (p. 318) Retrieves a list of installed licenses.

install (p. 322) Installs a new license.

parse (p. 325) Parse license provided and get it's info.

delete (p. 328) Delete license from the host server.

get_hwid (p. 329) Gets Hardware Node HWID(s).

update Updates current license.

318

Base Types and Interfaces

list

Summary:

Retrieves the Virtuozzo Containers license installed on the Hardware Node.

Request specification:

Name Min/Max Type Description

list 1..1

{

serial 0..[] string This parameter is not currently used.

type 0..[] string This parameter is not currently used.

}

Returns:

Name Min/Max Type Description

licenses 0..[] licensesType (p.

316)

Virtuozzo Containers license

information.

Example:

Input

<target>licensem</target>

<data>

<list/>

</licensem>

</data>

</packet>

Output

<?xml version="1.0" encoding="UTF-8"?><packet

xmlns:ns1="http://www.swsoft.com/webservices/vzl/4.0.0/licensem"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="4.0.0" priority="0"

id="1c4794742dt4823r9b8" time="2008-01-21T14:06:59+0000">

<origin>licensem</origin>

<target>vzclient2-9634f0ee-8c54-924d-9193-64f79dfc8736</target>

<dst>

</dst>

<data>

<body>========================================================================

== This file contains license for Virtuozzo product. ==

== Please visit http://www.sw-soft.com for more information on ==

== Virtuozzo and SWsoft. ==

== Please email your questions and/or suggestions to ==

== sales@sw-soft.com ==

=========================== Start of license ===========================

+hLwC8cTKogM7uox6MfKIwYGgk/eYX5KAxiTGNN0PsmvwSkG3L+UVC7oT6VoN0xQlAd7GhIk

319

Base Types and Interfaces

6JuvxGvTpyDKbA22JfBiftDv1hK0X9p6OoaMdmvnEAL/peUfmcnbAR+JgBJu4+x8OeUNWftY

B6SlA8mt5ZONKQWzvT6il8rqdnDzgBevNQ+GcptCpPhibUtzP0x3ocKApGtKseAP1QK5zW4F

Y8LMds8dgrtjVe8tPUFXAnAzDkrpM0ugwqlimp2XwDA0ZXFHCdI1TN2L1Nehzng/xQ/a1Wmw

YyyHaV9irXtysOMT+D69Jrg1Jgcvz5i7uv8jIBWIaqhbu0Gqje2bTNjAEOWzdYrpeWZn2vYj

gGThn5QUlZArDt2Cg4UggTSLq4C1uQBylXlX/899v4AiT5zy9o5xfFlqzK+B9mofR8IBTI3+

B9QzTehiXqE4Ry2bsLgyxfbSWuF3cFx23Mdt/Um+fB9PF/OgqnsifAKSqjSApN1eQNFDERbm

oUEKAkIVCbtLcmHGpGETsWVMuWLGvQzkOidwJEIThYiO+Lon82qmMZkZ38TUUjC25pRr+Jia

+GdzO6Rr4bN8cqsZkb0Hw0SN3lRff+P/D56yzxNYlxeF6xfb99ynGQ4hDuoLQcgdLxIjX/aE

vkIliXHmVZVpQINIyxzfGoUIpNmc3X9GNcUl2vfRLtAyQm4h9vo8eQ0m8qn8wrEya3DOHcu8

duJ5/6ZyTrkiUhuhz1KQUco4cQiFe4aEn3Tjvvv1P/RHcJ8p7q0eAkOoIvFhyfWwKSkApfn2

+475QB0wD/rUci/bDj2TALdW0a0xRL0kFYq9JhJUy6rkvYUKjzLj0qzmVWdcQtpSwWjJrTds

22eJfG0Po6NL4+bQaC/qDJ1leK132DYeAWvgzjvP8iB7527swde67mvcfzALbJtXRaXpmlyL

qfzyzaVLkTEhgg6ffYDQpYSO7jgY1KF41Q+jPsqQp1/Kn7HfOlShPvDExfKlB6OHpQPu50om

oZXs27l7u6jwKhTbSd4bvDUXGyZWKHA=

============================ End of license ============================

</body>

<name>CLASS</name>

<value>VlpTUlY=</value>

</parameter>

<name>owner_name</name>

<value>RXZhbHVhdGlvbiBWejQuMCBzZXJ2ZXIgSQ==</value>

</parameter>

<name>status</name>

<value>QUNUSVZF</value>

</parameter>

<name>version</name>

</parameter>

<name>owner_id</name>

<value>MTEuMg==</value>

</parameter>

<value>MDAwMC4wMDAwLjAwMDAuMDAwMC4wMDAwLjAwMDAuMDAwMC4wMDAw</value>

</parameter>

<name>serial</name>

<value>NTc4RS43RjE3LkE5MEYuNzQyMS45RUU3LkRBOTIuMkVERC42ODI5</value>

</parameter>

<name>expiration</name>

<value>MjAwOC0wMi0wMVQwMDowMDowMCswMDAw</value>

</parameter>

<name>start_date</name>

<value>MjAwNi0wOS0wMVQwMDowMDowMCswMDAw</value>

</parameter>

<name>issue_date</name>

<value>MjAwNy0xMi0yN1QwNzowNjozMCswMDAw</value>

</parameter>

<name>graceperiod</name>

320

Base Types and Interfaces

</parameter>

<name>key_number</name>

<value>VlouMDAwMDAwMTMuMDAwNA==</value>

</parameter>

<name>key_number_version</name>

<value>MDAwNA==</value>

</parameter>

<name>key_number_value</name>

<value>MDAwMDAwMTM=</value>

</parameter>

<name>product</name>

<value>VmlydHVvenpv</value>

</parameter>

<name>ct_total</name>

</parameter>

<name>cpu_total</name>

</parameter>

<name>vzpp_allowed</name>

</parameter>

<name>backup_mgmt_allowed</name>

</parameter>

<name>workflow_mgmt_allowed</name>

</parameter>

<name>pvaagent_allowed</name>

</parameter>

<name>max_vzmc_users</name>

</parameter>

<name>max_vzcc_users</name>

</parameter>

<name>architecture</name>

</parameter>

<name>architecture</name>

</parameter>

<name>architecture</name>

321

Base Types and Interfaces

</parameter>

<name>platform</name>

</parameter>

</license>

</licenses>

</licensem>

</data>

<src>

</src>

</packet>

322

Base Types and Interfaces

install

Summary:

Installs a Virtuozzo Containers license on the Hardware Node.

Request specification:

Name Min/Max Type Description

install 1..1

{

license 1..1 string License body, product key, or

product activation code, whichever

is available to you.

options 1..1 Installation options.

{

transfer 0..[] boolean Include this parameter and set it to

true if you would like to transfer the

license to a different Hardware

Node.

The parameter can only be used

when the license element

contains a product activation code.

If you have a license file or a product

key, delete the license first using the

delete call (p. 328) and then install

it on another Hardware Node using

the install call in a usual manner.

}

Returns:

Name Min/Max Type Description

licenses 0..[] licensesType (p.

316)

License information.

Example:

Installing a Virtuozzo Containers license using a product key.

Input

<target>licensem</target>

<data>

<license>0M9Y96-2GVKXG-82773A-BBKHYB-VFDYDP</license>

</install>

</licensem>

323

Base Types and Interfaces

</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/licensem"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="10c464846a5t5f90re80"

time="2007-05-15T10:23:28+0000" priority="0" version="4.0.0">

<ns1:origin>licensem</ns1:origin>

<ns1:target>vzclient2</ns1:target>

<ns1:dst>

<ns1:director>gend</ns1:director>

</ns1:dst>

<ns1:data>

<ns2:licensem>

<ns2:license>

<ns2:parameter>

<ns2:name>CLASS</ns2:name>

<ns2:value>VlpTUlY=</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>status</ns2:name>

<ns2:value>VkFMSUQ=</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>version</ns2:name>

<ns2:value>NC4w</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>serial</ns2:name>

<ns2:value>ME05WTk2LTJHVktYRy04Mjc3M0EtQkJLSFlCLVZGRFlEUA==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>expiration</ns2:name>

<ns2:value>MjAwNy0wNi0wMVQyMzo1OTo1OSswMDAw</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>graceperiod</ns2:name>

<ns2:value>MzYwMA==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>key_number</ns2:name>

<ns2:value>VlouMDAwMDAwMTMuMDAwMA==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>cpu_total</ns2:name>

<ns2:value>NjQ=</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>ve_total</ns2:name>

<ns2:value>ODIwMA==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>max_vzmc_users</ns2:name>

<ns2:value>MTI4</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>max_vzcc_users</ns2:name>

<ns2:value>MjYw</ns2:value>

</ns2:parameter>

324

Base Types and Interfaces

<ns2:parameter>

<ns2:name>platform</ns2:name>

<ns2:value>QW55</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>product</ns2:name>

<ns2:value>VmlydHVvenpv</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>vzpp_allowed</ns2:name>

<ns2:value>MQ==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>backup_mgmt_allowed</ns2:name>

<ns2:value>MQ==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>workflow_mgmt_allowed</ns2:name>

<ns2:value>MQ==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>pvaagent_allowed</ns2:name>

<ns2:value>MQ==</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>architecture</ns2:name>

<ns2:value>eDg2</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>architecture</ns2:name>

<ns2:value>eDg2XzY0</ns2:value>

</ns2:parameter>

<ns2:parameter>

<ns2:name>architecture</ns2:name>

<ns2:value>aWE2NA==</ns2:value>

</ns2:parameter>

</ns2:license>

</ns2:licensem>

</ns1:data>

<ns1:src>

<ns1:director>gend</ns1:director>

</ns1:src>

</ns1:packet>

325

Base Types and Interfaces

parse

Summary:

Parses a license body and obtains the license parameters.

Request specification:

Name Min/Max Type Description

parse 1..1

{

body 1..1 string Base64-encoded license body.

type 0..[] string This parameter is not currently used.

serial 0..[] string This parameter is not currently used.

}

Returns:

Name Min/Max Type Description

licenses 0..[] licensesType (p.

316)

License information.

Example:

Input

<target>licensem</target>

<data>

<parse>